diff --git a/SCOPE.md b/SCOPE.md index c90f43d..e45500f 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,45 +1,162 @@ -# SCOPE.md — llm-connect +# SCOPE -## Purpose +> This file helps you quickly understand what this repository is about, +> when it is relevant, and when it is not. -`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. +## One-liner -## This repo owns +`llm-connect` is a multi-provider LLM client library for Python. -- `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 +## Core Idea -- 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` +`llm-connect` provides a unified adapter interface over OpenAI, Gemini, +OpenRouter, Anthropic-compatible APIs, and the Claude Code CLI. It keeps +consumer applications from binding directly to provider-specific request, +response, embedding, token-estimation, and configuration details. -## Consumers (as of 2026-04-01) +The library was extracted from `markitect`; the `markitect.llm` module remains a +re-export shim pointing here. -| 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 +## In Scope -- 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 +- `LLMAdapter` ABC and `RunConfig` / `LLMResponse` data models. +- Concrete provider adapters such as `OpenAIAdapter`, `GeminiAdapter`, + `OpenRouterAdapter`, and `ClaudeCodeAdapter`. +- Embedding adapters including `EmbeddingAdapter`, + `OpenAICompatibleEmbeddingAdapter`, `EmbeddingCache`, and + `create_embedding_adapter`. +- TOML-based configuration resolution via `toml_config.py` and `config.py`. +- Shared HTTP utilities, token estimation, similarity helpers, and the + `LLMError` exception hierarchy. + +--- + +## Out of Scope + +- Consumer application logic; that belongs in `markitect`, `inter-hub`, and + other callers. +- Secret-management infrastructure; keys are resolved from environment variables + or configured key files, while secure storage belongs to the calling + environment. +- Consumer-specific model routing policy, beyond reusable primitives. +- Owning the Claude Code CLI binary itself; `ClaudeCodeAdapter` shells out to the + installed `claude` command. + +--- + +## Relevant When + +- You need one Python interface for multiple LLM providers. +- You want to switch between OpenAI, Gemini, OpenRouter, Anthropic-compatible + APIs, or Claude Code CLI without changing consumer code. +- You need embeddings, token estimation, provider configuration, or consistent + error handling around LLM calls. +- You are building a repository that should depend on provider-neutral LLM + primitives instead of vendor-specific client code. + +--- + +## Not Relevant When + +- You need a complete application-level agent framework. +- You need hosted secret storage, key rotation, or organization-wide credential + governance. +- You only call one provider directly and do not need adapter portability. +- You need UI, persistence, workflow orchestration, or domain-specific prompting. + +--- + +## Current State + +- Status: pre-release, version `0.1.0`. +- Core layer (`LLMAdapter`, `RunConfig`, `LLMResponse`) is intended to stabilize + by `v1.0.0`. +- Provider adapters, embedding helpers, and TOML configuration are implemented. +- Breaking core changes should require a major version bump once the core layer + is declared stable. + +--- + +## How It Fits + +- Upstream dependencies: provider SDKs or HTTP APIs for supported LLM services. +- Downstream consumers: `markitect` re-exports the library and uses it for + document generation; `inter-hub` uses it through its LLM bridge. +- Often used with: repositories that need optional LLM assistance while keeping + deterministic non-LLM behavior independently testable. + +--- + +## Terminology + +- Preferred terms: adapter, provider, run config, response, embedding adapter, + token estimator, provider-neutral LLM interface. +- Also known as: LLM adapter library, provider abstraction. +- Potentially confusing terms: `ClaudeCodeAdapter` integrates the Claude Code CLI, + not Anthropic's hosted Messages API directly. + +--- + +## Related / Overlapping + +- `markitect` - original source of the extracted adapter layer and current + downstream consumer. +- `inter-hub` - uses LLM calls through a bridge for interaction federation. +- `repo-scoping` - can use `llm-connect` as optional LLM assistance for + repository characteristic extraction. + +--- + +## Getting Oriented + +- Start with: `README.md`, `pyproject.toml`, and `contracts/functional/adapters.md`. +- Key files / directories: `llm_connect/`, `tests/`, `contracts/`, and + `.github/workflows/`. +- Entry points: adapter factory/configuration helpers and the provider adapter + classes under `llm_connect/`. + +--- + +## Provided Capabilities + +```capability +type: api +title: Multi-provider LLM adapter interface +description: > + Provides one Python adapter contract for OpenAI, Gemini, OpenRouter, + Anthropic-compatible APIs, and Claude Code CLI calls. +keywords: [llm, adapter, openai, gemini, openrouter, anthropic, claude] +``` + +```capability +type: api +title: Embedding adapter and cache support +description: > + Provides embedding adapter abstractions, OpenAI-compatible embedding support, + and embedding cache helpers for downstream retrieval workflows. +keywords: [embedding, vector, cache, retrieval, openai-compatible] +``` + +```capability +type: configuration +title: TOML-based LLM provider configuration +description: > + Resolves provider settings and model configuration from TOML and environment + sources so callers can configure LLM usage without hard-coding provider + details. +keywords: [toml, configuration, provider, model, credentials] +``` + +--- + +## Notes + +- Current known consumers are `markitect` and `inter-hub`. +- The library is intentionally provider-neutral; product-specific prompting and + routing decisions belong in the caller.