llm-connect/SCOPE.md

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

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]

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]

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.