# SCOPE.md — llm-connect

## Purpose

`llm-connect` is a **multi-provider LLM client library for Python**.
It provides a unified adapter interface over OpenAI, Gemini, OpenRouter,
and the Claude Code CLI, with embedding support, token estimation, and a
TOML-based configuration chain.

Extracted from [markitect](https://github.com/worsch/markitect).
The `markitect.llm` module remains a re-export shim pointing here.

## This repo owns

- `LLMAdapter` ABC and `RunConfig` / `LLMResponse` data models (Core)
- All concrete provider adapters: `OpenAIAdapter`, `GeminiAdapter`,
  `OpenRouterAdapter`, `ClaudeCodeAdapter` (Functional)
- Embedding adapters: `EmbeddingAdapter` ABC, `OpenAICompatibleEmbeddingAdapter`,
  `EmbeddingCache`, `create_embedding_adapter` factory (Functional)
- TOML-based config resolution (`toml_config.py`, `config.py`) (Configuration)
- Shared HTTP utility (`_http.py`), token estimator (`_token_estimator.py`),
  cosine similarity utilities (`similarity.py`)
- The full `LLMError` exception hierarchy

## This repo does NOT own

- Consumer application logic — that lives in `markitect`, `inter-hub`, etc.
- API key management infrastructure — keys are resolved from env vars or
  plaintext key files; secret storage belongs in the calling environment
- Model routing decisions specific to a consumer — `RoutingPolicy` (WP-0003)
  provides primitives; policy configuration belongs in the consumer
- The Claude Code CLI binary itself — `ClaudeCodeAdapter` shells out to `claude`

## Consumers (as of 2026-04-01)

| Consumer | How it uses llm-connect |
|----------|------------------------|
| `markitect` | Re-exports via `markitect.llm` shim; drives document generation |
| `inter-hub` (IHF) | Subprocess bridge (`scripts/llm_bridge.py` + `AgentBridge.hs`) for multi-agent federation |

## Versioning

- Current version: **0.1.0** (pre-release; API not yet stable)
- Core layer (`LLMAdapter`, `RunConfig`, `LLMResponse`) will be stabilised at **v1.0.0**
- Breaking Core changes require a major version bump