Q&A

Technical questions about Corpus OS protocols, SDK usage, adapter implementation, and conformance testing.

[mbedjoko]

I’m trying to implement custom adapters using the Corpus OS SDK. What are the recommended patterns or best practices to ensure proper protocol conformance and avoid runtime errors? Are there specific tests or debugging tools you suggest for validating adapter implementations?

Any examples or guidance from your experience would be appreciated.

[LOWVesspucci]

Great questions. Adapter implementation is one of the most common topics we get asked about, so I'll share the patterns that work best.

Start with the working examples. Before writing anything from scratch, check the /examples directory in the repo. There are full working adapters for all four domains (LLM, Embedding, Vector, Graph) plus a complete RAG pipeline that chains three protocols together. They're runnable implementations that show exactly how to structure your adapter. The docs/guides/QUICK_START.md guide walks you through each step by step.

The core pattern is simple: wrap your provider. You're not rewriting your provider's SDK — you're wrapping it. Your adapter inherits from the appropriate base class (BaseLLMAdapter, BaseEmbeddingAdapter, BaseVectorAdapter, BaseGraphAdapter) and implements _do_* hooks that call your provider under the hood. The base handles validation, deadlines, observability, and error normalization. You handle the translation between the Corpus protocol and your provider's API.

Start with the minimum viable adapter. Every adapter only requires three hooks: _do_capabilities, your core operation (_do_complete, _do_embed, _do_query, etc.), and _do_health. All other methods have safe no-op defaults. Start there, get the conformance tests passing, then layer on additional operations. Trying to implement everything at once is a way to introduce runtime errors.

Use the base classes, don't bypass them. The bases handle validation, deadline enforcement, observability, and error normalization for you. If you're calling provider APIs directly without going through the _do_* hooks, you're skipping all of that, and your adapter won't conform to the protocol.

Wrap provider errors immediately. The most common runtime errors come from letting raw provider exceptions propagate. Every call to an external API should be wrapped in a try/catch that maps to the normalized error taxonomy — BadRequest, TransientNetwork, Unavailable, ResourceExhausted, etc. If an unexpected exception escapes, the base catches it as UnhandledException in metrics, but that's a fallback, not a strategy.

The suite covers protocol compliance, error handling, deadline behavior, and capability reporting. If your adapter passes conformance, it works with any Corpus-compatible router or control plane. The test output links to the relevant spec section for any failures, so you can trace exactly what needs fixing.

Before running tests, read docs/conformance/CONFORMANCE.md. It documents the full certification requirements — Platinum, Gold, Silver, and Development tiers, so you know exactly what level of compliance you're targeting and what each tier requires. This saves you from chasing test failures that aren't relevant to your certification goal.

For debugging at runtime:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("corpus_sdk").setLevel(logging.DEBUG)

This exposes the full lifecycle — validation, deadline checks, cache lookups, metrics emission, and the actual _do_* dispatch. Usually, the issue is obvious once you can see where in the lifecycle the error occurs.

A few patterns that save time:

1. Test in thin mode first. This disables the built-in circuit breaker, rate limiter, and cache, so you're only testing your adapter logic without infrastructure interference. Switch to standalone once the adapter itself is solid.

2. Implement _do_capabilities accurately. Don't claim supports_streaming=True if you haven't implemented streaming. The conformance suite validates behavior against declared capabilities, so mismatches will fail tests.

3. Use OperationContext consistently. Pass request_id, tenant, and deadline_ms through every operation. This ensures proper tracing, metrics attribution, and timeout behavior. Skipping context is the second most common source of subtle bugs.

Check out docs/guides/IMPLEMENTATION.md and docs/guides/ADAPTER_RECIPES.md for full walkthroughs with real-world multi-provider examples.

Let us know what provider you're building the adapter for. Happy to point you to relevant examples or help debug specific conformance failures.