Scope update from repo-scoping refactor

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.