Metadata-Version: 2.4
Name: zespan-flask
Version: 1.0.0
Summary: Zespan observability middleware for Flask
Requires-Python: >=3.9
Requires-Dist: flask>=2.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# zespan-flask

Automatic LLM observability middleware for Flask. Traces every request, LLM call, and custom span with zero code changes for basic usage.

## Installation

```bash
pip install zespan-flask
```

## Quick Start

```python
from flask import Flask
from zespan_flask import ZespanFlaskExtension, ZespanConfig

app = Flask(__name__)

config = ZespanConfig(api_key="zsp_your_api_key")
lumiq = ZespanFlaskExtension(app, config)
```

Every HTTP request is now automatically traced.

## Application Factory Pattern

```python
lumiq = ZespanFlaskExtension()

def create_app():
    app = Flask(__name__)
    lumiq.init_app(app)
    return app
```

## Trace LLM Calls

```python
from zespan_flask import observe_llm

@observe_llm(model="gpt-4o", provider="openai")
def generate_response(prompt: str):
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response
```

## Trace Custom Spans

```python
from zespan_flask import observe_span

@observe_span("fetch_context", span_type="retrieval")
def fetch_context(query: str):
    return vector_db.search(query)
```

## Set Custom Attributes

```python
from zespan_flask import set_attribute

@app.route("/chat")
def chat():
    set_attribute("user.id", current_user.id)
    set_attribute("session.id", session.get("id"))
```

## Configuration

| Option | Default | Description |
|---|---|---|
| `api_key` | required | Zespan API key (`zsp_...`) |
| `base_url` | `https://api.zespan.com` | API endpoint |
| `enabled` | `True` | Toggle tracing on/off |
| `sample_rate` | `1.0` | Fraction of requests to trace (0.0–1.0) |
| `capture_request_body` | `False` | Include request body in traces |
| `capture_response_body` | `False` | Include response body in traces |
| `redact_fields` | `["password","token","api_key"]` | Fields redacted automatically |
| `debug` | `False` | Print flush errors to stdout |

Get your API key at [zespan.com](https://zespan.com).
