PKG-INFO

Metadata-Version: 2.4
Name: agentspring
Version: 0.1.0
Summary: A modular, extensible agentic API framework inspired with a focus on flexibility and rapid development.
Home-page: https://github.com/navdeep-G/agentspring
Author: Your Name
Author-email: mr.navdeepgill@gmail.com
License: MIT
Project-URL: Documentation, https://github.com/navdeep-G/agentspring
Project-URL: Source, https://github.com/navdeep-G/agentspring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: FastAPI
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.95.0
Requires-Dist: pydantic>=1.10.0
Requires-Dist: celery>=5.2.0
Requires-Dist: redis>=4.0.0
Requires-Dist: uvicorn>=0.18.0
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AgentSpring

AgentSpring is a **Python framework** for building, deploying, and operating **agentic APIs** and **agent-driven workflows** with minimal boilerplate and lots of hooks for production use.

> **TL;DR:** You get a batteries‑included FastAPI “agent app,” a tool registry, an LLM provider system (sync/async & streaming), optional Celery/Redis for async jobs, Prometheus metrics, JSON logging, and a simple DAG‑style workflow engine.

---

## 🧭 Why AgentSpring?

* **API-first agents**: Ship a FastAPI app with standard health, metrics, and async task endpoints.
* **Tools + Workflows**: Register tools with schemas/permissions and compose them in a lightweight workflow engine.
* **LLM integration**: Provider registry + base class with retries, rate limiting, validation, and streaming.
* **Production touches**: Auth (API key), RBAC helpers, multi‑tenancy primitives, Prometheus metrics, JSON logs, Sentry hooks.
* **Boring‑but‑useful**: Docker Compose + Kubernetes manifests to help you run locally or in a cluster.

> **Note:** Earlier docs mentioned an `orchestration.py` module. The current codebase uses a **`workflow`** module instead. This README reflects the actual files in the repo.

---

## 📦 Project Structure (what’s actually here)

```
agentspring/
├── agentspring/                      # Framework package
│   ├── __init__.py                   # Extension hooks (admin panels, metrics, background tasks)
│   ├── api.py                        # FastAPIAgent, Auth middleware, RBAC, std endpoints
│   ├── api_versioning.py             # API version manager + router + request/response transforms
│   ├── app_loader.py                 # Loads an app module via AGENTSPRING_APP (factory-style)
│   ├── audit.py                      # Audit logging helper
│   ├── celery_app.py                 # Celery config (broker/backend via env)
│   ├── cli.py                        # `python -m agentspring.cli create-app <Name>`
│   ├── logging_config.py             # JSON logging to ./logs with PII scrubbing
│   ├── metrics.py                    # Prometheus counters/histograms and /metrics route helper
│   ├── models.py                     # Pydantic request/response + validators
│   ├── multi_tenancy.py              # Tenant router + Redis‑backed manager
│   ├── task_base.py                  # (stub)
│   ├── tasks.py                      # AsyncTaskManager + batch helpers (Celery)
│   ├── tools/__init__.py             # ToolRegistry + @tool decorator + parameter validation
│   ├── llm/
│   │   ├── __init__.py               # Public LLM API (exports base + registry)
│   │   ├── base.py                   # LLMProvider base: sync/async, streaming, retries, rate limits
│   │   └── registry.py               # LLMRegistry: register/get/list providers
│   ├── agent/__init__.py             # Base Agent + @agent_tool decorator for methods
│   └── workflow/__init__.py          # DAG‑style workflow engine (alpha)
├── examples/
│   └── workflow_example.py           # LLM→plan→tool execution demo (uses Ollama)
├── k8s/                              # Kubernetes manifests (app, worker, redis, config, secrets)
├── docker-compose.yml                # Minimal stack (app, redis, optional ollama)
├── docker-compose.full.yml           # Full stack (app, redis, prometheus, grafana, *log shippers*)
├── prometheus.yml                    # Prometheus scrape config
├── filebeat.yml                      # Filebeat -> Logstash (sample; Logstash not included)
├── promtail-config.yaml              # Promtail -> Loki (sample; Loki not included)
└── README.md                         # (this)
```

---

## 🚀 Quickstart (local, no Docker)

### 1) Install

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e .
```

### 2) Minimal app

Create `main.py`:

```python
from agentspring.api import FastAPIAgent
from agentspring.metrics import setup_metrics

agent = FastAPIAgent(title="AgentSpring Demo")
app = agent.get_app()
setup_metrics(app)  # exposes /metrics

# Example custom endpoint
@agent.app.get("/hello")
def hello():
    return {"message": "Hello from AgentSpring"}
```

Run it:

```bash
export API_KEY=demo-key   # header name is x-api-key
uvicorn main:app --reload
```

### 3) Smoke test

```bash
curl -H "x-api-key: $API_KEY" http://localhost:8000/health
curl -H "x-api-key: $API_KEY" http://localhost:8000/readiness
curl -H "x-api-key: $API_KEY" http://localhost:8000/liveness
```

Open docs at `http://localhost:8000/docs` and metrics at `http://localhost:8000/metrics` (Prometheus text format).

---

## 🔐 Auth & RBAC

* **API key**: All protected endpoints expect `x-api-key` to match the value from the `API_KEY` env var (`demo-key` default).
* **Roles**: A helper `require_role("admin"|"user")` is provided. It reads the role from the `x-role` header and returns 403 if not sufficient.

Example RBAC usage:

```python
from fastapi import Depends
from agentspring.api import FastAPIAgent

agent = FastAPIAgent()
app = agent.get_app()
require_role = agent.require_role

@app.post("/secure-endpoint", dependencies=[Depends(require_role("admin"))])
def secure(payload: dict):
    return {"ok": True}
```

---

## 📊 Metrics & Logging

* **Prometheus**: `metrics.setup_metrics(app)` installs an HTTP middleware to count requests and exposes `/metrics`.

  * Key series include `api_requests_total` (method, endpoint, http\_status) and histograms for tool execution.
* **Logging**: `logging_config.setup_logging()` outputs **JSON logs** into `./logs/agentspring.log` with basic PII/secret scrubbing.
* **Sentry**: If `SENTRY_DSN` is set, both the web app and Celery worker capture exceptions.

---

## 📮 Async Tasks (Celery + Redis)

Enable background jobs and polling endpoints.

1. Start Redis (local or Docker) and set env vars:

```bash
export CELERY_BROKER_URL=redis://localhost:6379/0
export CELERY_RESULT_BACKEND=redis://localhost:6379/0
```

2. Start a Celery worker:

```bash
celery -A agentspring.celery_app.celery_app worker --loglevel=info
```

3. Your API app (created via `FastAPIAgent`) will automatically register:

   * `POST /analyze/async` → returns a task id (demo stub)
   * `GET  /tasks/{task_id}/status`
   * `GET  /tasks/{task_id}/result`
   * `GET  /tenants/{tenant_id}/tasks/{task_id}/status` (tenant‑aware variant)

Programmatic submission:

```python
from celery import shared_task
from agentspring.tasks import AsyncTaskManager
from agentspring.celery_app import celery_app

@shared_task
def heavy(x: int) -> int:
    return x * x

manager = AsyncTaskManager(celery_app)
job_id = manager.submit_task(heavy, 12)
status = manager.get_task_status(job_id)
```

---

## 🛠 Tools (registry + decorator)

Register callable tools with schemas/permissions and execute them by name.

```python
from agentspring.tools import tool, tool_registry

@tool("read_file", description="Read a local file")
def read_file(path: str) -> dict:
    return {"content": open(path).read()}

# Introspection
print(tool_registry.list_tools())          # ["read_file", ...]
print(tool_registry.get_all_schemas())     # {"read_file": ToolSchema(...)}

# Direct execution
res = tool_registry.execute_tool("read_file", path="README.md")
print(res.success, res.result)
```

* The registry validates parameters, maps names, and records execution time.
* Unknown parameters are **warned** but do not crash by default.

---

## 🤖 LLM Provider System

A thin but robust abstraction for plugging different LLM backends.

**What you get:**

* Base `LLMProvider` with `generate`/`generate_async` and `stream`/`stream_async` methods
* Tenacity‑based retries, error classification, and **rate limiting** with automatic backoff
* Input validation (length/emptiness) and structured exceptions (`LLMError`, `RateLimitError`)
* A simple `LLMRegistry` to register and fetch providers

**Implement a provider:**

```python
from agentspring.llm.base import LLMProvider, ProviderConfig

class MyLLM(LLMProvider):
    def __init__(self):
        super().__init__(config=ProviderConfig(model="my-model"))

    async def generate_async(self, prompt: str, **kwargs) -> str:
        # call your backend here, return text
        return "hello world"
```

**Use via the registry:**

```python
from agentspring.llm import LLMRegistry

LLMRegistry.register_provider("mine", MyLLM)
provider = LLMRegistry.get_provider("mine")
print(provider.generate("Say hi"))
```

For a full, end‑to‑end demo using **Ollama** + tool planning, see `examples/workflow_example.py`.

---

## 🧱 Workflow Engine (alpha)

Model multi‑step processes as a small DAG and execute them asynchronously.

```python
import asyncio
from agentspring.workflow import Workflow, NodeType
from agentspring.tools import tool, tool_registry

@tool("sum", "Sum numbers")
async def sum_numbers(values: list[int]) -> int:
    return sum(values)

wf = Workflow(workflow_id="wf1", name="Demo")
wf.tools = tool_registry  # use the global registry
wf.add_node(
    node_id="step1",
    node_type=NodeType.TOOL,
    config={"tool_name": "sum", "parameters": {"values": [1,2,3]}},
)

result = asyncio.run(wf.execute())
print(result)
```

* Node types include **AGENT**, **TOOL**, **CONDITION**, **PARALLEL**, **SEQUENCE** (some are TODOs).
* Dependencies are topologically sorted; each node records status, timing, and errors.

> The earlier “orchestrator” mention in older drafts has been replaced with this `workflow` engine.

---

## 👥 Multi‑Tenancy (primitives)

* `multi_tenancy.TenantManager` stores tenant configs (API keys, features, limits) in Redis.
* A **tenant router** provides CRUD endpoints:

  * `POST /tenants`, `GET /tenants`, `GET /tenants/{id}`, `PUT /tenants/{id}`, `DELETE /tenants/{id}`
* You can include the router in your app:

```python
from fastapi import Depends
from agentspring.multi_tenancy import tenant_router
from agentspring.api import FastAPIAgent

agent = FastAPIAgent()
app = agent.get_app()
app.include_router(tenant_router, prefix="/admin")
```

---

## 🔢 API Versioning

`api_versioning.py` provides:

* An `APIVersion` enum and a `VersionManager` (register versions, mark deprecated/sunset dates)
* Request/response transformers to keep old clients working
* A `create_versioned_router("/api")` helper exposing:

  * `GET /api/versions` (list, with latest), `GET /api/versions/{version}` (details)

Transform your payloads per version:

```python
from agentspring.api_versioning import versioned_request, versioned_response

req_v1 = versioned_request("v1", incoming_dict)
resp   = versioned_response("v1", {"summary": "..."})
```

---

## 🐳 Docker & Kubernetes

### Docker Compose (minimal)

```bash
docker-compose up --build
```

* Default command in the compose files expects an ASGI app (e.g. `main:app`). Create a `main.py` as in the Quickstart or edit the `command:` to point at your module.
* Services: `app`, `redis`, and (optionally) `ollama` for the example workflow.

### Docker Compose (full observability)

```bash
docker-compose -f docker-compose.full.yml up --build
```

Includes Prometheus and Grafana out of the box; log shippers are configured (Filebeat/Promtail). **You may need to add services** for Logstash/Loki to match the sample configs (`filebeat.yml`, `promtail-config.yaml`).

### Kubernetes

Manifests live in `k8s/`:

```bash
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/redis-deployment.yaml
kubectl apply -f k8s/app-deployment.yaml
kubectl apply -f k8s/celery-worker-deployment.yaml
kubectl apply -f k8s/app-service.yaml
```

---

## 🧪 Testing & Linting

```bash
pytest -q
# or with coverage
coverage run -m pytest && coverage report --fail-under=40
```

* Ruff/Black config lives in `pyproject.toml`.

---

## 🔧 Environment Variables

* `API_KEY` – API auth key for `x-api-key` (default: `demo-key`)
* `SENTRY_DSN` – Sentry DSN (optional)
* `LOG_DIR` – logs directory (default: `./logs`)
* `CELERY_BROKER_URL` – e.g., `redis://localhost:6379/0`
* `CELERY_RESULT_BACKEND` – e.g., `redis://localhost:6379/0`
* `AGENTSPRING_APP` – Python module path to load with `app_loader.py` (if you use that pattern)

---

## ❓ FAQ / Troubleshooting

* **401 Unauthorized**: Ensure `x-api-key` matches `$API_KEY`.
* **/metrics missing**: Call `setup_metrics(app)` or expose your own metrics route.
* **Async task endpoints missing**: Ensure Redis is reachable and a Celery worker is running; FastAPIAgent registers task routes only when async is enabled.
* **Docker Compose app won’t start**: Point `uvicorn` at your ASGI app (e.g., `main:app`), not a module that returns a module. The full compose’s `command:` is a template—adjust to your file.
* **Grafana/Loki/Logstash issues**: The configs are provided as references; add the missing services or update endpoints to match your stack.

---

## 🤝 Contributing

Issues and PRs welcome! Please run `pytest` and ensure formatting (Ruff/Black) before submitting.