Metadata-Version: 2.4
Name: ak-agentbase
Version: 0.1.0a1
Summary: Unified AI agent configuration, observability, and model management for multi-agent applications
Project-URL: Homepage, https://github.com/Shivam1904/AgentBase
Project-URL: Documentation, https://github.com/Shivam1904/AgentBase/blob/main/README.md
Project-URL: Repository, https://github.com/Shivam1904/AgentBase
Project-URL: Issues, https://github.com/Shivam1904/AgentBase/issues
Author-email: Shivam Srivastava <shivam.sriv93@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,configuration,langsmith,llm,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic==2.12.5
Requires-Dist: pyyaml==6.0.3
Provides-Extra: dev
Requires-Dist: build==1.2.2; extra == 'dev'
Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
Requires-Dist: pytest==9.0.3; extra == 'dev'
Requires-Dist: ruff==0.15.12; extra == 'dev'
Requires-Dist: twine==6.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# AgentBase v0.1-alpha

**Unified AI agent configuration, observability, and model management for production multi-agent systems.**

AgentBase is a lightweight, framework-agnostic control plane that standardizes how AI-heavy products configure models, register agents, and emit observability metadata. No framework dependencies. No vendor lock-in. Just YAML + Python.

## Status

✅ **v0.1-alpha** — Core library complete. 96 tests passing. First projects integrated (Writerverse, Skill-Deck pipeline).

## What It Does

```python
import agentbase
from langchain_openai import ChatOpenAI

# Load configuration
agentbase.load_config("agentbase.yaml", "agents.yaml")
agentbase.init_tracing()

# Resolve an agent
resolved = agentbase.resolve("my_analyzer")

# Construct LLM with AgentBase config
llm = ChatOpenAI(model=resolved.model_id, **resolved.default_params)

# Enable LangSmith tracing
result = llm.invoke(messages, config=resolved.langchain_config())
```

**Returns:**
- `model_id`: Resolved model name (e.g., `gpt-4o`, `claude-sonnet-4-20250514`)
- `default_params`: Model config (temperature, max_tokens, etc.)
- `langchain_config()`: LangSmith trace metadata (tags, generation_name, metadata)

## Core Features

- **YAML Config** — Single source of truth for all model aliases and agent definitions
- **Model Aliases** — `fast`, `smart`, `creative` that resolve to provider-specific IDs per environment
- **Agent Registry** — Centralized agent metadata (owner, version, prompt location, status)
- **LangSmith Integration** — Automatic trace metadata in every chain/workflow
- **Environment Switching** — Dev/prod model aliases in one config file
- **Zero Framework Dependencies** — Works with LangChain, Anthropic SDK, OpenAI SDK, etc.
- **CLI Validation** — `agentbase validate` checks config and resolves all agents

## Installation

```bash
pip install agentbase==0.1.0a1
```

## Quick Start

**1. Create config files:**

`agentbase.yaml`:
```yaml
project: my-project

models:
  fast:
    dev: gpt-4o-mini
    production: gpt-4o
  smart:
    dev: gpt-4o
    production: claude-sonnet-4-20250514

defaults:
  environment: dev
  model_alias: smart

tracing:
  backend: langsmith
  enabled: true
```

`agents.yaml`:
```yaml
agents:
  - agent_name: analyzer
    model_alias: fast
    owner: team
    status: active
    agent_version: "0.1.0"
    prompt_ref: "git:backend/prompts/analyze.py"
    description: "Analyzes input data"
```

**2. Set environment variables:**

```bash
LANGCHAIN_API_KEY=lsv2_pt_xxxxx
OPENAI_API_KEY=sk-xxxxx
```

**3. Initialize in your app:**

```python
import agentbase

agentbase.load_config(config_path="agentbase.yaml", registry_path="agents.yaml")
agentbase.init_tracing()
```

**4. Use in your chains:**

```python
resolved = agentbase.resolve("analyzer")
llm = ChatOpenAI(model=resolved.model_id, **resolved.default_params)
result = chain.invoke(input, config=resolved.langchain_config())
```

See [QUICKSTART.md](QUICKSTART.md) for full setup instructions.

## Architecture

```
agentbase.load_config()
  ├─ Loads agentbase.yaml (project, models, defaults, tracing)
  ├─ Loads agents.yaml (agent registry)
  └─ Validates all required fields

agentbase.init_tracing()
  └─ Sets LANGCHAIN_TRACING_V2 and LANGCHAIN_PROJECT env vars
     (if LangSmith backend is enabled)

agentbase.resolve(agent_name)
  ├─ Looks up agent in registry
  ├─ Resolves model_alias → model_id (using defaults.environment)
  ├─ Returns ResolvedAgent with:
  │  ├─ model_id (e.g., "gpt-4o")
  │  ├─ default_params (temperature, max_tokens, etc.)
  │  ├─ langchain_config() → LangSmith metadata
  │  └─ trace_metadata → raw metadata dict
  └─ (Throws ConfigValidationError if not found or invalid)
```

## API

### Core Functions

```python
agentbase.load_config(config_path: str, registry_path: str) → None
  # Load and validate agentbase.yaml and agents.yaml
  # Raises ConfigValidationError if validation fails

agentbase.init_tracing() → None
  # Set up LangSmith tracing if enabled in config
  # Requires LANGCHAIN_API_KEY env var if using LangSmith

agentbase.resolve(agent_name: str) → ResolvedAgent
  # Resolve agent and return config
  # Returns ResolvedAgent with model_id, default_params, langchain_config()
  # Raises ConfigValidationError if agent not found

agentbase.validate(config_path: str, registry_path: str) → None
  # Validation-only mode (no tracing setup)
  # Used by CLI and tests
```

### ResolvedAgent

```python
@dataclass
class ResolvedAgent:
    model_id: str | None          # "gpt-4o", "claude-sonnet-4-20250514", None for workflows
    default_params: dict[str, Any] # {"temperature": 0.7, "max_tokens": 4096}
    
    def langchain_config(self) -> dict[str, Any]:
        # Returns LangSmith-compatible config for chain.invoke(config=...)
        # Fields: generation_name, trace_name, tags, metadata
```

## CLI

```bash
# Validate config (exit 0 if valid, 1 if errors)
agentbase validate agentbase.yaml agents.yaml

# Resolve an agent (pretty-print)
agentbase resolve agent_name --config agentbase.yaml --registry agents.yaml

# Version
agentbase --version
```

## Configuration Reference

### agentbase.yaml

```yaml
project: <string>              # Project name (used in LangSmith traces)

models:
  <alias>:                      # e.g., "fast", "smart", "creative"
    dev: <model_id>             # e.g., "gpt-4o-mini"
    production: <model_id>      # e.g., "gpt-4o"

defaults:
  environment: <env>            # "dev" or "production"
  model_alias: <alias>          # Default model alias
  [other defaults...]

tracing:
  backend: langsmith | none     # "langsmith" or "none"
  enabled: true | false         # Enable/disable tracing
```

### agents.yaml

```yaml
agents:
  - agent_name: <string>        # Unique agent identifier
    model_alias: <string>       # References models.* in agentbase.yaml
    owner: <string>             # Team or person responsible
    status: active | inactive   # Status
    agent_version: <semver>     # e.g., "0.1.0"
    prompt_ref: <string>        # Reference to prompt (e.g., "git:path/to/file.py")
    description: <string>       # Human-readable description
```

## Environment Variables

| Variable | Required | Purpose |
|----------|----------|---------|
| `LANGCHAIN_API_KEY` | If tracing enabled | LangSmith API key |
| `OPENAI_API_KEY` | If using gpt-* models | OpenAI API key |
| `ANTHROPIC_API_KEY` | If using claude-* models | Anthropic API key |

## Why AgentBase?

**Before AgentBase:**
- Each project had its own config system (get_ai_config, hardcoded model names)
- LLM setup was duplicated across chains
- No unified observability or cost tracking
- Difficult to switch models for A/B testing

**With AgentBase:**
- One config file per project, YAML-based
- Agents registered once, resolved anywhere
- Automatic LangSmith integration
- Model switching via `defaults.environment`
- Cost visibility per agent per environment

## For Projects Using AgentBase

- **Writerverse** — 35 agents + 7 LangGraph workflows (scene generation, consistency analysis, chat, supervisor)
- **Skill-Deck** — Q&A system with dynamic model routing
- **Shivam Portfolio** — Proof-of-concept (first integration)

See [QUICKSTART.md](QUICKSTART.md) for project integration steps.

## For Publishing

See [PUBLISH.md](PUBLISH.md) for detailed steps to publish to PyPI.

## Development

```bash
# Install dev dependencies
pip install -e .[dev]

# Run tests
pytest tests/ -v

# Lint
ruff check agentbase/ tests/

# Format
ruff format agentbase/ tests/
```

## License

MIT — see [LICENSE](LICENSE)

## Author

Shivam Srivastava — [GitHub](https://github.com/Shivam1904)

---

**Questions?** Open an issue on [GitHub](https://github.com/Shivam1904/AgentBase/issues)
