# AbstractCore

> Unified Python interface for cloud + local LLM providers with streaming, tool calling, structured output, media handling (images/audio/video + documents), embeddings, and an optional OpenAI-compatible HTTP server. Default install stays lightweight; features are enabled via extras.

Last reviewed against source: 2026-05-04. Package version in source: 2.13.2. Supported Python: 3.9+; GitHub CI tests 3.9, 3.10, 3.11, 3.12, and 3.13.

This is the curated, high-signal index for agents. For a self-contained handbook with the important details inlined, read `llms-full.txt`.

Important notes:
- Default tool execution is **pass-through**: AbstractCore returns tool calls; your host/runtime executes them.
- AbstractCore is **offline-first** for local models: it will not silently download model weights (download/pull explicitly).

Ecosystem note:
- AbstractCore is part of **AbstractFramework** (umbrella: https://github.com/lpalbou/AbstractFramework).
- In the ecosystem, **AbstractRuntime** is the recommended runtime for executing `response.tool_calls` durably (policy, retries, persistence): https://github.com/lpalbou/abstractruntime

Quick start:
- Install: `pip install abstractcore`
- Hosted SDK bundle: `pip install "abstractcore[remote]"` (OpenAI + Anthropic SDKs; OpenRouter/Portkey/local `/v1` providers use core HTTP dependencies)
- First steps: `docs/getting-started.md` -> `docs/prerequisites.md`
- Run the gateway server: `pip install "abstractcore[server]"` then `python -m abstractcore.server.app`
- Run the single-model endpoint: `pip install "abstractcore[server]"` then `abstractcore-endpoint --help` (see `docs/endpoint.md`)
- Repo/dev checks: `pip install -e ".[dev,test]"` ; `pytest -q` ; `black .` ; `ruff check .`

## Read First

- [README](README.md): what AbstractCore is + install matrix
- [Docs index](docs/README.md): recommended reading paths
- [Getting Started](docs/getting-started.md): `create_llm(...)`, `generate(...)`, streaming, tools, structured output, media
- [Prerequisites](docs/prerequisites.md): provider setup (keys/base URLs) + local hardware notes
- [FAQ](docs/faq.md): common issues + setup gotchas

## Examples

- [Examples index](examples/README.md): organized by topic + a guided learning path
- [Learning path](examples/learning_path/README.md): 6 scripts in order (`01_...` → `06_...`)
- [Prompt caching](examples/prompt_caching/README.md): `CachedSession` + attachments + REPL demo
- [Media](examples/media/README.md): inspect pipeline + image/video/audio demos
- [Tools](examples/tools/README.md): tool calling + host execution (ToolRegistry vs manual dispatcher)

## Core API + Concepts

- [API (Python)](docs/api.md): public API map and common patterns
- [API Reference](docs/api-reference.md): full function/class listing
- [Generation parameters](docs/generation-parameters.md): max tokens / thinking / temperature semantics across providers
- [Prompt caching](docs/prompt-caching.md): `CachedSession`, cache keys, and file attachments
- [Tool calling](docs/tool-calling.md): `@tool`, passthrough vs execution, built-in tools
- [Tool syntax rewriting](docs/tool-syntax-rewriting.md): preserve tool-call markup (`tool_call_tags`, server `agent_format`)
- [Structured output](docs/structured-output.md): `response_model=...`, native vs prompted, validation/retry behavior
- [Media handling](docs/media-handling-system.md): `media=[...]`, audio/video policies, vision fallback and plugins
- [Centralized config](docs/centralized-config.md): `abstractcore --config`, defaults, provider keys, HTTP server auth/hardening, logging, vision/audio/video strategies

## Providers (IDs + setup)

- [Provider registry](abstractcore/providers/registry.py): provider IDs, defaults, install extras
- [Provider setup guide](docs/prerequisites.md): env vars + examples for OpenAI/Anthropic/Ollama/LMStudio/MLX/HuggingFace/vLLM/OpenRouter/Portkey/OpenAI-compatible

## Server (OpenAI-compatible `/v1`)

- [Server docs](docs/server.md): run + env vars + auth + endpoints and extensions (`base_url`, `agent_format`, `thinking`, `prompt_cache_key`). Request body/query `api_key` is disabled; use server-side provider config, `X-AbstractCore-Provider-API-Key`, or `Authorization` only when server auth is not configured.
- [Server implementation](abstractcore/server/app.py): FastAPI gateway source
- [Endpoint docs](docs/endpoint.md): single-model OpenAI-compatible endpoint (`abstractcore-endpoint`)
- [Endpoint implementation](abstractcore/endpoint/app.py): endpoint server source

## Contributing

- [Contributing](CONTRIBUTING.md): formatting/lint/test + release checklist
- [Changelog](CHANGELOG.md): version history + upgrade notes
- [pyproject.toml](pyproject.toml): extras + console scripts

## Optional

- [Architecture](docs/architecture.md): core/provider/session/tool/media/capabilities design
- [Practical recipes](docs/examples.md): copy/paste code snippets (provider-agnostic)
- [Troubleshooting](docs/troubleshooting.md): common errors and fixes
- [Embeddings](docs/embeddings.md): EmbeddingManager (optional)
- [Capabilities](docs/capabilities.md): `llm.voice` / `llm.audio` / `llm.vision` plugin model
- [MCP](docs/mcp.md): MCP tool servers (HTTP/stdio)
- [llms-full](llms-full.txt): self-contained agent handbook (this repo)