# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.

---

## One-liner

`llm-connect` is a multi-provider LLM client library for Python.

---

## Core Idea

`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.

The library was extracted from `markitect`; the `markitect.llm` module remains a
re-export shim pointing here.

---

## In Scope

- `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.