generated from coulomb/repo-seed
163 lines
5.1 KiB
Markdown
163 lines
5.1 KiB
Markdown
# 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.
|