Metadata-Version: 2.4
Name: kaze-agent-base
Version: 0.1.0
Summary: Reusable ADK-based agent infrastructure — plugin loader, background workflow engine, FastAPI server, memory service.
Project-URL: Homepage, https://github.com/speedrun-labs/kaze-agent-base
Project-URL: Repository, https://github.com/speedrun-labs/kaze-agent-base
Author: Speedrun Labs
License: Apache-2.0
Keywords: adk,agent,llm,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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: a2a-sdk>=0.2.0
Requires-Dist: anyio>=4.0
Requires-Dist: fastapi>=0.110
Requires-Dist: google-adk>=2.0.0a3
Requires-Dist: httpx>=0.27.0
Requires-Dist: litellm==1.82.3
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: memory
Requires-Dist: mem0ai>=0.1.80; extra == 'memory'
Requires-Dist: psycopg2-binary>=2.9; extra == 'memory'
Provides-Extra: tracing
Requires-Dist: langfuse<3,>=2.0; extra == 'tracing'
Description-Content-Type: text/markdown

# kaze-agent-base

Reusable ADK-based agent infrastructure — plugin loader, background workflow
engine, FastAPI server, memory service, LLM wrapper with trace propagation.

Extracted from
[kaze-agent-ops](https://github.com/speedrun-labs/kaze-agent-ops) so other
agents can be built on the same framework.

## Install

```bash
pip install kaze-agent-base
# Optional extras:
pip install "kaze-agent-base[memory]"    # Mem0 + pgvector
pip install "kaze-agent-base[tracing]"   # Langfuse callbacks
```

## Build your own agent

Your agent package owns:
- `plugin.yaml` + `tools.py` files under `my_agent/plugins/<name>/`
- `config.yaml` listing models and specialists
- A package `__init__.py` that builds the workflow
- An entrypoint script that calls `create_app(...)`

**Directory layout**

```
my_agent/
  pyproject.toml              # depends on kaze-agent-base
  config.yaml                 # model tiers, specialists
  my_agent/
    __init__.py               # builds workflow, exposes _workflow_*
    serve.py                  # calls create_app(...)
    plugins/
      root/plugin.yaml + prompt.md
      <specialist>/plugin.yaml + tools.py [+ workflows/]
```

**`my_agent/__init__.py`**

```python
from pathlib import Path

from kaze.agent_base.workflow.graph import build_workflow

_PKG_ROOT = Path(__file__).parent

_workflow, _agents = build_workflow(
    config_path=_PKG_ROOT.parent / "config.yaml",
    plugins_root=_PKG_ROOT / "plugins",
    plugins_package="my_agent.plugins",
    workflow_name="my_agent",
    workflow_description="My agent — short tagline",
)

_workflow_agents = _agents
_workflow_config = _workflow._kaze_config
_workflow_mcp_toolsets = _workflow._kaze_mcp_toolsets

root_agent = _workflow
__all__ = ["root_agent"]
```

**`my_agent/serve.py`**

```python
from pathlib import Path

from kaze.agent_base import create_app
from kaze.agent_base.server import run


def main():
    app, host, port = create_app(
        app_module="my_agent",
        agents_dir=Path(__file__).resolve().parents[1],
        title="My Agent API",
        description="…",
        version="0.1.0",
    )
    run(app, host, port)


if __name__ == "__main__":
    main()
```

Wire up a `[project.scripts]` entry (e.g., `my-agent-serve = "my_agent.serve:main"`)
and you have a deployable agent.

## Environment variables

| Var | Purpose | Default |
|---|---|---|
| `KAZE_GATEWAY_URL` / `_API_KEY` | LLM gateway endpoint | `http://localhost:4200` |
| `KAZE_CONFIG_PATH` | Path to `config.yaml` | `./config.yaml` |
| `KAZE_PLUGINS_ROOT` / `KAZE_PLUGINS_PACKAGE` | Plugin location | (required; pass args or env) |
| `KAZE_APP_NAME` | ADK app name | `kaze_app` |
| `KAZE_DATA_DIR` | SQLite location | `.adk/` |
| `KAZE_A2A_HOST` / `KAZE_A2A_PORT` | Server bind | `0.0.0.0:8080` |
| `KAZE_MEM0_*` | Mem0 config (see `state/memory.py`) | — |
| `LANGFUSE_*` | Tracing (optional) | — |
| `AGENT_API_KEY` | Bearer token for `/api/v1/*` | — |

The `KAZE_` prefix is historical; downstream agents can use the same prefix
or layer on their own env vars.

## Public API

```python
from kaze.agent_base import (
    acompletion,           # LLM call with trace linkage
    set_trace_id,
    reset_trace_id,
    ToolAgent,             # ADK BaseAgent that runs a tool in a thread
    get_engine,            # background WorkflowEngine singleton
    spill,                 # persist large outputs to disk
    discover_plugins,
    get_workflow_templates,
    get_tool_registry,
    resolve_tools,
    create_app,            # FastAPI factory
)
```

## Layout

```
src/kaze/agent_base/
  config.py                  load_config(path)
  models.py                  LiteLlm factory (gateway-routed)
  llm.py                     acompletion + trace propagation
  plugin.py                  discover_plugins(plugins_root, plugins_package)
  tool_registry.py           framework:* + <plugin>:* namespaces
  tools/                     background, memory, notify, system, code, bash, fs, artifacts
  jobs/                      engine, store, tool_agent (background workflows)
  state/                     memory (mem0), config_store, sessions, services
  server/                    app (create_app, run), routes, schemas
  workflow/                  graph, agents, callbacks, mcp
```

## License

Apache-2.0
