feat(api): LLM provider adapters — Anthropic + OpenAI-compatible #337

Merged

james merged 1 commit from 336-llm-provider-adapters into main 2026-06-29 00:26:40 +00:00

Conversation 1 Commits 1 Files changed 10 +1260

james commented 2026-06-29 00:00:47 +00:00

Owner

Copy link

Adds the thin non-streaming inference layer (ADR-0029 §1 + §4, #336): an LlmClient interface with an Anthropic adapter (official @anthropic-ai/sdk) and an OpenAI-compatible adapter (plain fetch — covers OpenAI, OpenRouter, and local Ollama). It consumes #333's per-user config/key and the #51 tool registry.

Rebased onto main after #334 merged, so the diff is just the adapters.

What's in it (apps/api/lib/llm/)

• client.ts — LlmClient interface (generate(req): Promise<LlmResult>), normalized types (LlmMessage/LlmToolDef/LlmGenerateRequest/LlmResult/LlmStopReason), a typed LlmError (not_configured/key_required/auth/rate_limited/overloaded/provider_error — carries only kind/message/status, never the key or raw error), and getLlmClientForUser(userId, db).
• tools.ts — zod → JSON Schema (z.toJSONSchema, allOf-flattened, mirroring the MCP endpoint) + llmToolDefsFromRegistry() over #51's allTools().
• anthropic.ts — translates normalized ↔ Anthropic Messages API (system, tool_use/tool_result blocks, tools); injectable client/fetch for tests; model-agnostic (no thinking/sampling params in v1). 529/overload detected via status === 529 || type === "overloaded_error" (the brief's OverloadedError class doesn't exist in SDK 0.106).
• openai-compatible.ts — fetch to ${baseUrl}/chat/completions, Authorization omitted when keyless; maps function-tools + tool_calls/tool role; injectable fetch.
• getLlmClientForUser selects the adapter from the #333 config + decrypted key (anthropic → key required; openai_compatible → key optional).

Bounded to inference + provider selection — streaming, the agent loop, conversations/messages, the SSE endpoint, and the chat UI are later tickets that consume this.

Dependency

@anthropic-ai/sdk@^0.106.0 (latest stable; the requested ^0.69.0 is superseded). Established package (won't trip package-age); no install lifecycle script, so no onlyBuiltDependencies entry. OpenAI-compatible uses fetch — no openai dep. Lockfile updated; pnpm install --frozen-lockfile clean.

Verification

• typecheck + lint clean; semgrep (full CI pack set) — 0 findings (incl. the user-baseUrl fetch); openapi:check up to date (lib-only, no contract change).
• Full suite on BOTH engines: 1150 passed / 0 skipped (ephemeral Postgres — the provider-selection test touches #333's table via describePerEngine). Tests inject transport (fake Anthropic client / fake fetch) — no live API calls: request translation, response normalization (text + tool_calls + stop reason), tool-use round, error mapping, keyless Ollama, selection + not_configured/key_required, and an assertion that no tool def carries user_id.

Closes #336

🤖 Generated with Claude Code

Adds the thin **non-streaming inference layer** (ADR-0029 §1 + §4, #336): an `LlmClient` interface with an **Anthropic** adapter (official `@anthropic-ai/sdk`) and an **OpenAI-compatible** adapter (plain `fetch` — covers OpenAI, OpenRouter, and **local Ollama**). It consumes #333's per-user config/key and the #51 tool registry. Rebased onto `main` after #334 merged, so the diff is just the adapters. ## What's in it (`apps/api/lib/llm/`) - `client.ts` — `LlmClient` interface (`generate(req): Promise<LlmResult>`), normalized types (`LlmMessage`/`LlmToolDef`/`LlmGenerateRequest`/`LlmResult`/`LlmStopReason`), a typed `LlmError` (`not_configured`/`key_required`/`auth`/`rate_limited`/`overloaded`/`provider_error` — carries only kind/message/status, never the key or raw error), and `getLlmClientForUser(userId, db)`. - `tools.ts` — zod → JSON Schema (`z.toJSONSchema`, `allOf`-flattened, mirroring the MCP endpoint) + `llmToolDefsFromRegistry()` over #51's `allTools()`. - `anthropic.ts` — translates normalized ↔ Anthropic Messages API (system, `tool_use`/`tool_result` blocks, `tools`); injectable client/fetch for tests; **model-agnostic** (no `thinking`/sampling params in v1). 529/overload detected via `status === 529 || type === "overloaded_error"` (the brief's `OverloadedError` class doesn't exist in SDK 0.106). - `openai-compatible.ts` — `fetch` to `${baseUrl}/chat/completions`, `Authorization` omitted when keyless; maps function-tools + `tool_calls`/`tool` role; injectable `fetch`. - `getLlmClientForUser` selects the adapter from the #333 config + decrypted key (anthropic → key required; openai_compatible → key optional). Bounded to **inference + provider selection** — streaming, the agent loop, `conversations`/`messages`, the SSE endpoint, and the chat UI are later tickets that consume this. ## Dependency `@anthropic-ai/sdk@^0.106.0` (latest stable; the requested `^0.69.0` is superseded). Established package (won't trip package-age); **no install lifecycle script**, so no `onlyBuiltDependencies` entry. OpenAI-compatible uses `fetch` — no `openai` dep. Lockfile updated; `pnpm install --frozen-lockfile` clean. ## Verification - typecheck + lint clean; **semgrep (full CI pack set) — 0 findings** (incl. the user-`baseUrl` fetch); `openapi:check` up to date (lib-only, no contract change). - **Full suite on BOTH engines: 1150 passed / 0 skipped** (ephemeral Postgres — the provider-selection test touches #333's table via `describePerEngine`). Tests inject transport (fake Anthropic client / fake `fetch`) — **no live API calls**: request translation, response normalization (text + tool_calls + stop reason), tool-use round, error mapping, keyless Ollama, selection + `not_configured`/`key_required`, and an assertion that no tool def carries `user_id`. Closes #336 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-29 00:00:47 +00:00

feat(api): LLM provider adapters — Anthropic + OpenAI-compatible ... e95bdbac11

Adds the thin non-streaming inference layer (ADR-0029 §1 + §4, #336): an
LlmClient interface with an Anthropic adapter (official @anthropic-ai/sdk)
and an OpenAI-compatible adapter (plain fetch — covers OpenAI, OpenRouter,
and local Ollama). Normalized messages + the #51 tool registry (zod →
JSON Schema) translate to each provider and back to
{ text, toolCalls, stopReason }.

getLlmClientForUser selects the adapter from the #333 per-user config +
decrypted key (anthropic → key required; openai_compatible → key optional
for keyless local). Typed LlmError never carries the key or the raw
provider error. Model-agnostic v1: no thinking/sampling params.

Bounded to inference + provider selection — streaming, the agent loop,
conversations/messages, the SSE endpoint, and the chat UI are later
tickets that consume this. New dep @anthropic-ai/sdk@^0.106.0 (no install
lifecycle script). Tests use injected transport (no live API calls).

Closes #336

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

forgejo-actions commented 2026-06-29 00:07:20 +00:00

Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric	Value	Soft target
Lines	78.9% ✅	≥ 50%
Branches	70.8% ⚠️	≥ 75%
Functions	79.3%	informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 78.9% ✅ | ≥ 50% | | Branches | 70.8% ⚠️ | ≥ 75% | | Functions | 79.3% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

james force-pushed 336-llm-provider-adapters from e95bdbac11 to 32c903d0b5 2026-06-29 00:18:07 +00:00 Compare

james merged commit 5e3b1e9c30 into main 2026-06-29 00:26:40 +00:00

james deleted branch 336-llm-provider-adapters 2026-06-29 00:26:41 +00:00

james referenced this pull request from a commit 2026-06-29 00:26:42 +00:00

Merge pull request 'feat(api): LLM provider adapters — Anthropic + OpenAI-compatible' (#337) from 336-llm-provider-adapters into main

james referenced this pull request 2026-06-29 00:29:59 +00:00

feat(api): agent loop + conversations/messages schema (non-streaming) #338

james referenced this pull request from a commit 2026-06-29 00:55:38 +00:00

feat(api): server-side agent loop + conversations/messages schema

james referenced this pull request 2026-06-29 00:56:01 +00:00

feat(api): server-side agent loop + conversations/messages schema #339

james referenced this pull request 2026-06-29 01:06:48 +00:00

feat(api): streaming agent turns — LlmClient.stream() + SSE chat endpoint #340

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!337

No description provided.