# Logos ADK Documentation

**Current Version:** 0.3.0

Welcome to the Logos ADK documentation. This guide covers everything from quick start to advanced features.

## Quality Baseline

The public repository maintains a curated release gate through:

```bash
bash scripts/quality_baseline.sh
```

This baseline is intended to stay green for public releases and validates linting, typing, and the main public runtime surfaces.

## Documentation Index

### Getting Started

- **[README](../README.md)** — Overview, installation, and quick start examples
- **[Core Concepts](core-concepts.md)** — Fundamental concepts and architecture
- **[Examples](examples.md)** — Practical code examples and patterns
- **[API Reference](api-reference.md)** — Complete API documentation
- **[CLI Reference](cli.md)** — Command-line interface guide
- **[Advanced Guide](advanced_guide.md)** — Deep dive into framework internals
- **[Production MVP](production.md)** — Deployment, migrations, auth, CI gates, and operator baseline
- **[Testing & Fixes](testing-fixes.md)** — Test results and bug fixes implemented
- **[HTTP API Reference](http-api.md)** — Complete HTTP server endpoint documentation
- **[Session Management](sessions.md)** — Working with sessions and task runs
- **[Streaming & SSE](streaming.md)** — Using streaming responses and Server-Sent Events
- **[Quality Testing](quality-testing.md)** — Regression and load testing
- **[Semver Policy](semver.md)** — Stable public API and deprecation rules
- **[Migration Notes](migration-notes.md)** — Upgrade notes between framework lines
- **[Threat Model](threat-model.md)** — Security assumptions, boundaries, and risks
- **[Audit Trail Policy](audit-trail-policy.md)** — Audit retention, redaction, and deletion flow
- **[Public API](public-api.md)** — Explicit public/private module discipline
- **[Upgrade Guide](upgrade-guide.md)** — Version upgrades and rollout workflow
- **[Breaking Changes Checklist](breaking-changes-checklist.md)** — Release/change discipline
- **[Compliance & Security](compliance-security.md)** — External-facing governance baseline
- **[Multi-Tenant Architecture](multi-tenant-architecture.md)** — Tenant isolation guidance
- **[Secret Rotation](secret-rotation.md)** — Secrets lifecycle and audit guidance
- **[Scaling Limits](scaling-limits.md)** — Practical deployment limits and expectations
- **[Reference Architectures](reference-architectures.md)** — Deployment blueprints
- **[Cookbook](cookbook.md)** — Common patterns for external users
- **[Troubleshooting Matrix](troubleshooting-matrix.md)** — Fast diagnosis by subsystem
- **[Self-Learning Baseline](self-learning-baseline.md)** — Current self-improvement capabilities, closed-loop architecture, and KPI contract
- **[Self-Learning Roadmap](self-learning-roadmap.md)** — Phased implementation checklist from coordinator to meta-learning

---

## Quick Navigation

### I want to...

| Goal | Go to |
|------|-------|
| Install Logos ADK | [README →](../README.md#installation) |
| Quick Start Guide | [README →](../README.md#quick-start) |
| Create my first agent | [README →](../README.md#quick-start) |
| Graph workflow | [README →](../README.md#quick-start) |
| HTTP server | [Examples →](examples.md#web-server) |
| Add tools to an agent | [Examples →](examples.md#tools) |
| Enable memory | [Examples →](examples.md#memory) |
| Add safety guardrails | [Examples →](examples.md#guardrails) |
| Use RAG with documents | [Examples →](examples.md#rag) |
| Create multi-agent team | [Examples →](examples.md#multi-agent-teams) |
| Start a web server | [Examples →](examples.md#web-server) |
| Use the CLI | [CLI Reference](cli.md) |
| Understand API details | [API Reference](api-reference.md) |
| Prepare for production | [Production MVP](production.md) |
| Understand stable compatibility | [Semver Policy](semver.md) |
| Upgrade safely | [Upgrade Guide](upgrade-guide.md) |
| Find architecture patterns | [Reference Architectures](reference-architectures.md) |

---

## Documentation Overview

### [README](../README.md)

Start here if you're new to Logos ADK. Covers:
- Installation and setup
- Quick start examples
- Feature overview
- Project structure

### [Core Concepts](core-concepts.md)

Deep dive into Logos ADK architecture:
- Agent lifecycle and configuration
- Tool system and creation
- Memory strategies (session, long-term, shared)
- Guardrails for safety
- RAG (Retrieval-Augmented Generation)
- MCP (Model Context Protocol)
- Multi-agent teams
- Observability and tracing
- Caching strategies
- Error handling

### [Examples](examples.md)

Practical, copy-paste ready examples:
- Basic agent patterns
- Tool creation and usage
- Memory configuration
- Guardrail implementations
- RAG setup with different loaders
- Team orchestration
- MCP integration
- Streaming responses
- Structured output with Pydantic
- Caching (exact and semantic)
- Observability exporters
- Web server deployment
- YAML configuration
- Testing patterns

### [API Reference](api-reference.md)

Complete API documentation:
- `Agent` class and methods
- `Team` orchestration
- `Tool` system
- `Memory` classes and backends
- `Guardrail` implementations
- `RAG` components
- `MCP` integration
- `Observer` exporters
- `Cache` backends
- Type definitions
- Configuration classes
- Error types
- Testing utilities
- Cost tracking
- Runtime and state

### [CLI Reference](cli.md)

Command-line interface documentation:
- `chat`, `run`, `test`, `validate`, `describe`, `tui`
- `serve`, `test-live`
- `quality`, `integration`, `regression`, `load-test`, `judge-eval`
- `storage`, `retrieval`, `tool-workflow`, `model-routing`, `evaluation`, `improvement`, `transfer`
- `project`, `upgrade`, `admin`

---

## Key Features

### 🤖 Agent System
Create AI agents with configurable models, prompts, and behaviors.

```python
from logos_adk import Agent

agent = Agent("assistant", model="claude-sonnet-4-20250514")
```

### 🔧 Tools
Extend agents with custom tools.

```python
from logos_adk import tool

@tool
async def search(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"
```

### 🧠 Memory
Multiple memory strategies for context management.

```python
from logos_adk import SessionMemory, LongTermMemory

agent.memory(
    SessionMemory(max_messages=20),
    LongTermMemory(backend=SQLiteBackend("memory.db"))
)
```

### 🛡️ Guardrails
Input/output validation and content filtering.

```python
from logos_adk import ContentFilter

agent.input_guardrail(
    ContentFilter(blocked=["spam", "abuse"])
)
```

### 📚 RAG
Retrieval-Augmented Generation for knowledge bases.

```python
from logos_adk import KnowledgeBase

agent.knowledge(kb, mode="memory")
```

### 👥 Teams
Multi-agent orchestration.

```python
from logos_adk import Team

team = Team("team", agents=[agent1, agent2], orchestrator="agent1")
```

### 🔗 MCP
Model Context Protocol integration.

```python
agent.mcp("http://localhost:3000/sse")
```

### 📊 Observability
Built-in tracing and metrics.

```python
from logos_adk import ConsoleExporter, OpenTelemetryExporter

agent.observe(ConsoleExporter(), OpenTelemetryExporter(endpoint="..."))
```

### 💾 Caching
Response caching for performance.

```python
from logos_adk import InMemoryCacheBackend

agent.cache(InMemoryCacheBackend(), ttl=3600)
```

### 🌐 Serving
HTTP API server with streaming.

```bash
logos-adk serve --agents agent.yaml --port 8000
```

---

## Supported Providers

| Provider | Models | Setup |
|----------|--------|-------|
| Anthropic | Claude family | `pip install logos-adk[anthropic]` |
| OpenAI | GPT-4, GPT-3.5 | `pip install logos-adk[openai]` |
| Google | Gemini family | Built-in |
| Ollama | Local models | Built-in |
| OpenAI-Compatible | vLLM, LM Studio, etc. | Built-in |

---

## Optional Dependencies

```bash
# All features
pip install logos-adk[all]

# Individual features
pip install logos-adk[anthropic]   # Anthropic provider
pip install logos-adk[openai]      # OpenAI provider
pip install logos-adk[mcp]         # MCP support
pip install logos-adk[serve]       # HTTP server
pip install logos-adk[cli]         # CLI tools
pip install logos-adk[rag-pdf]     # PDF loading
pip install logos-adk[rag-chroma]  # ChromaDB vector store
pip install logos-adk[dev]         # Development tools
```

---

## Getting Help

### Documentation
- This documentation set
- [Examples guide](examples.md) for working code
- [API Reference](api-reference.md) for detailed signatures

### Common Issues

**Agent not responding:**
1. Check provider configuration
2. Verify API keys
3. Run `logos-adk test agent.yaml`

**Memory not persisting:**
1. Ensure backend is configured
2. Check file permissions for SQLite
3. Verify session_id is consistent

**Tools not being called:**
1. Check tool schema generation
2. Ensure async functions
3. Verify tool names match LLM expectations

---

## Version

This documentation covers Logos ADK version **0.3.0**.

---

## License

MIT License — see project repository for details.
