karenina-adapter-implement

Follow the file-by-file order: availability check, error mapping, message conversion, trace and usage extraction, then agent, llm, and parser port classes, finishing with registry registration. Read the port protocol files in karenina/src/karenina/ports/ first to get exact interface signatures.

A typical adapter contains __init__.py with lazy exports, availability.py, errors.py, messages.py, trace.py, usage.py, agent.py, llm.py, parser.py, registration.py, and a prompts/ directory. Optional files include initialization.py and mcp.py depending on the SDK.

Create a registration.py that calls AdapterRegistry.register() with an AdapterSpec defining factories and capability flags. For built-in adapters, import it in registry.py's _load_builtins(); for plugins, declare a karenina.adapters entry point in pyproject.toml.

Zero tokens usually means usage extraction reads only the last message instead of summing across all AI messages, or with_structured_output() discarded the raw response. Use include_raw=True or the SDK equivalent to retain token counts.

Wrap execution in asyncio.wait_for() on all paths, accumulate messages incrementally, and on TimeoutError return a partial AgentResult with timeout_reached=True if any messages exist. Raise AgentTimeoutError only when no messages were collected at all.

Every LLM adapter must define astream() and stream_invoke(), but adapters without SDK streaming support may raise NotImplementedError and set supports_streaming=False in PortCapabilities. Streaming enables partial content capture on request timeouts.