# AbstractCore

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

Core install:
- `pip install abstractcore`

Common extras (quote brackets for zsh):
- `pip install "abstractcore[openai]"` / `"abstractcore[anthropic]"`
- `pip install "abstractcore[huggingface]"` / `"abstractcore[mlx]"` / `"abstractcore[vllm]"`
- `pip install "abstractcore[tools]"` / `"abstractcore[media]"` / `"abstractcore[embeddings]"` / `"abstractcore[compression]"`
- `pip install "abstractcore[server]"` / `"abstractcore[tokens]"`

## Start Here

- [README.md](README.md): project overview, install matrix, quickstart
- [docs/README.md](docs/README.md): docs index and reading paths
- [docs/getting-started.md](docs/getting-started.md): 5-minute intro (`create_llm`, `generate`)
- [docs/prerequisites.md](docs/prerequisites.md): provider setup + install extras
- [docs/faq.md](docs/faq.md): common questions and setup gotchas
- [docs/api.md](docs/api.md): public API map and patterns
- [docs/api-reference.md](docs/api-reference.md): public API reference

## Core API

- [abstractcore/__init__.py](abstractcore/__init__.py): lightweight public exports
- [abstractcore/core/factory.py](abstractcore/core/factory.py): `create_llm(...)`
- [abstractcore/providers/registry.py](abstractcore/providers/registry.py): provider IDs + install extras
- [abstractcore/providers/base.py](abstractcore/providers/base.py): shared generate logic (tools/media/structured output)
- [docs/centralized-config.md](docs/centralized-config.md): config defaults + API key management

## Features

- [docs/tool-calling.md](docs/tool-calling.md): `@tool`, passthrough vs execution
- [abstractcore/tools/](abstractcore/tools/): tool system (core/registry/parser/handler)
- [abstractcore/tools/common_tools.py](abstractcore/tools/common_tools.py): built-in tools (web_search/skim_websearch/skim_url/fetch_url + filesystem helpers; requires `abstractcore[tools]`)
- [examples/skim_tools_benchmark.py](examples/skim_tools_benchmark.py): benchmark output footprint/latency for skim_* vs fetch_*
- [docs/tool-syntax-rewriting.md](docs/tool-syntax-rewriting.md): tool-call format rewriting (`tool_call_tags`, server `agent_format`)
- [docs/structured-output.md](docs/structured-output.md): `response_model=...`
- [docs/events.md](docs/events.md): global event bus (`on_global`)
- [docs/structured-logging.md](docs/structured-logging.md): configure console/file logging
- [docs/media-handling-system.md](docs/media-handling-system.md): `media=[...]` + file processing
- [docs/vision-capabilities.md](docs/vision-capabilities.md): image/video input + vision fallback (and how this differs from generative vision)
- [abstractcore/capabilities/registry.py](abstractcore/capabilities/registry.py): capability plugins (`core.voice/core.audio/core.vision`) + `status()` discovery
- [abstractcore/media/](abstractcore/media/): media pipeline (optional deps behind extras)
- [docs/glyphs.md](docs/glyphs.md): glyph compression
- [abstractcore/compression/](abstractcore/compression/): glyph compression (optional)
- [docs/embeddings.md](docs/embeddings.md): embeddings usage
- [abstractcore/embeddings/](abstractcore/embeddings/): `EmbeddingManager` (optional)
- [docs/mcp.md](docs/mcp.md): MCP tool servers (HTTP/stdio)

## Server

- [docs/server.md](docs/server.md): OpenAI-compatible HTTP endpoints
- [abstractcore/server/app.py](abstractcore/server/app.py): FastAPI implementation

Notes:
- `/v1/images/*` endpoints are optional and require `abstractvision`.
- `/v1/audio/*` endpoints are optional and require an audio/voice capability plugin (typically `abstractvoice`).

## Development

- [pyproject.toml](pyproject.toml): dependencies + extras (keep default small)
- [CHANGELOG.md](CHANGELOG.md): release notes and upgrade guidance
- [SECURITY.md](SECURITY.md): responsible vulnerability reporting
- [CONTRIBUTING.md](CONTRIBUTING.md): contributor workflow
- [tests/](tests/): pytest suite

## Optional

- [docs/reports/README.md](docs/reports/README.md): non-authoritative engineering notes
- [docs/research/README.md](docs/research/README.md): non-authoritative research/experiments
- [docs/archive/README.md](docs/archive/README.md): historical/superseded documentation
- [llms-full.txt](llms-full.txt): standalone repo context for LLMs