ADR-002: Direct Claude SDK, No Abstraction Layer
Status: Accepted Date: 2026-02
Context
The AI synthesis engine is Envara's core differentiator. Report quality depends on sophisticated prompt engineering: carefully structured system prompts, context injection, output schema control, and iterative refinement. The question is whether to use the Anthropic SDK directly or adopt an abstraction layer like LangChain.
Decision
Use the Anthropic Claude SDK directly with no abstraction layer. Prompt construction is handled by a custom prompt builder that assembles sections (system context, collection purpose, audience context, response data, analytical instructions) into the final prompt.
Alternatives Considered
| Option | Pros | Cons |
|---|---|---|
| Direct SDK | Full control over prompts, no overhead, easier debugging | More code to write for retries, streaming |
| LangChain | Abstractions for chains, memory, tools | Heavy dependency, hides prompt details, harder to debug, overkill for this use case |
| Vercel AI SDK | Good streaming support, provider-agnostic | Adds a layer between us and the API, less control over raw prompt structure |
Consequences
Positive:
- Complete visibility into what's sent to the API. Every token is intentional.
- Prompt debugging is straightforward — the
prompt_snapshotcolumn stores exactly what was sent. - No dependency bloat. The Anthropic SDK is lightweight.
- Switching models (e.g. Claude Opus → Sonnet for cost) is a one-line change.
Negative:
- Must implement retry logic, rate limiting, and error handling manually.
- If we later need multi-model orchestration or tool use, we build it ourselves.
These trade-offs are acceptable. The synthesis task is a single, well-defined API call — not a multi-step agent chain. Simplicity wins.