zespan-flask 1.0.0__tar.gz

zespan_flask-1.0.0/.gitignore

@@ -0,0 +1,55 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Dependencies
+node_modules
+.pnp
+.pnp.js
+
+
+
+langfuse-main/
+langwatch-main/
+.claude
+.gemini
+
+
+# Testing
+coverage
+
+# Turbo
+.turbo
+
+# Vercel
+.vercel
+
+# Wrangler (Cloudflare dev artifacts — not used in VPS deploy)
+.wrangler/
+
+# Build Outputs
+.next/
+.open-next/
+out/
+build
+dist
+
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Misc
+.DS_Store
+*.pem
+
+.hypothesis
+.kiro
+.vscode
+
+lumiqtrace-landing
+# Production secrets — never commit
+ops/cloudflared/creds.json
+
+# Added by code-review-graph
+.code-review-graph/
+.gitnexus

zespan_flask-1.0.0/PKG-INFO

@@ -0,0 +1,96 @@
+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).

zespan_flask-1.0.0/README.md

@@ -0,0 +1,84 @@
+# 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).

zespan_flask-1.0.0/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@zespan/middleware-flask",
+  "version": "0.1.0",
+  "description": "Zespan trace middleware for Flask - Automatic LLM observability",
+  "main": "src/zespan_flask/__init__.py",
+  "scripts": {
+    "build": "echo 'Python package - no build step required'",
+    "dev": "echo 'Python package - no dev server'"
+  },
+  "keywords": ["zespan", "flask", "middleware", "llm", "observability", "tracing"],
+  "license": "MIT"
+}

zespan_flask-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zespan-flask"
+dynamic = ["version"]
+description = "Zespan observability middleware for Flask"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "flask>=2.0",
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.hatch.version]
+path = "src/zespan_flask/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zespan_flask"]

zespan_flask-1.0.0/src/zespan_flask/__init__.py

@@ -0,0 +1,280 @@
+"""
+Zespan Trace - Flask Middleware
+Automatic Agent observability for Flask applications
+"""
+
+__version__ = "1.0.0"
+
+import time
+import uuid
+import json
+from typing import Any, Dict, List, Optional, Callable
+from functools import wraps
+from contextvars import ContextVar
+
+# Context for current trace
+current_trace: ContextVar[Optional["TraceContext"]] = ContextVar("current_trace", default=None)
+
+
+class TraceContext:
+    """Context for a single trace/span"""
+    
+    def __init__(self, trace_id: str, span_id: str, name: str = "", parent_id: Optional[str] = None):
+        self.trace_id = trace_id
+        self.span_id = span_id
+        self.parent_id = parent_id
+        self.name = name
+        self.start_time = time.time()
+        self.attributes: Dict[str, Any] = {}
+
+
+class ZespanConfig:
+    """Configuration for Zespan middleware"""
+    
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.zespan.com",
+        enabled: bool = True,
+        sample_rate: float = 1.0,
+        capture_request_body: bool = False,
+        capture_response_body: bool = False,
+        redact_fields: Optional[List[str]] = None,
+        debug: bool = False
+    ):
+        self.api_key = api_key
+        self.base_url = base_url
+        self.enabled = enabled
+        self.sample_rate = sample_rate
+        self.capture_request_body = capture_request_body
+        self.capture_response_body = capture_response_body
+        self.redact_fields = redact_fields or ["password", "token", "api_key"]
+        self.debug = debug
+
+
+class ZespanFlaskExtension:
+    """
+    Flask extension for automatic LLM observability.
+    
+    Usage:
+        from flask import Flask
+        from zespan_flask import ZespanFlaskExtension, ZespanConfig
+        
+        app = Flask(__name__)
+        config = ZespanConfig(api_key="your-api-key")
+        zespan = ZespanFlaskExtension(app, config)
+    """
+    
+    def __init__(self, app=None, config: Optional[ZespanConfig] = None):
+        self.app = app
+        self.config = config or ZespanConfig(api_key="")
+        self._queue: List[Dict[str, Any]] = []
+        self._flush_interval = 5.0
+        self._last_flush = time.time()
+        
+        if app is not None:
+            self.init_app(app)
+    
+    def init_app(self, app):
+        """Initialize the extension with a Flask app"""
+        self.app = app
+        
+        @app.before_request
+        def before_request():
+            if not self.config.enabled:
+                return
+                
+            trace_id = f"trace_{uuid.uuid4().hex}"
+            span_id = f"span_{uuid.uuid4().hex[:16]}"
+            
+            from flask import request
+            trace_ctx = TraceContext(
+                trace_id=trace_id,
+                span_id=span_id,
+                name=f"{request.method} {request.path}",
+            )
+            
+            # Store start time
+            trace_ctx.attributes["http.method"] = request.method
+            trace_ctx.attributes["http.url"] = request.url
+            trace_ctx.attributes["http.route"] = request.path
+            trace_ctx.attributes["http.user_agent"] = request.headers.get("User-Agent")
+            
+            current_trace.set(trace_ctx)
+        
+        @app.after_request
+        def after_request(response):
+            if not self.config.enabled:
+                return response
+                
+            trace_ctx = current_trace.get()
+            if not trace_ctx:
+                return response
+            
+            duration_ms = (time.time() - trace_ctx.start_time) * 1000
+            
+            trace_data = {
+                "trace_id": trace_ctx.trace_id,
+                "span_id": trace_ctx.span_id,
+                "name": trace_ctx.name,
+                "type": "http_request",
+                "duration_ms": duration_ms,
+                "status": "success" if response.status_code < 400 else "error",
+                "http_status": response.status_code,
+                "attributes": trace_ctx.attributes,
+                "timestamp": time.time(),
+            }
+            
+            self._queue.append(trace_data)
+            
+            # Flush if needed
+            if len(self._queue) >= 10 or time.time() - self._last_flush > self._flush_interval:
+                self._flush()
+            
+            return response
+        
+        @app.teardown_appcontext
+        def teardown(exception):
+            # Final flush on request end
+            if self._queue:
+                self._flush()
+    
+    def _flush(self):
+        """Send queued traces to Zespan"""
+        if not self._queue:
+            return
+            
+        traces = self._queue[:]
+        self._queue = []
+        self._last_flush = time.time()
+        
+        try:
+            import requests
+            requests.post(
+                f"{self.config.base_url}/v1/ingest/batch",
+                json={"traces": traces},
+                headers={"X-API-Key": self.config.api_key},
+                timeout=5.0
+            )
+        except Exception as e:
+            if self.config.debug:
+                print(f"[Zespan] Failed to send traces: {e}")
+
+
+def observe_span(name: str, span_type: str = "custom"):
+    """
+    Decorator to observe a function as a span.
+    
+    Usage:
+        @observe_span("my_llm_call", span_type="llm")
+        def my_llm_function(prompt: str):
+            return call_llm(prompt)
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            trace_ctx = current_trace.get()
+            if not trace_ctx:
+                return func(*args, **kwargs)
+            
+            span_id = f"span_{uuid.uuid4().hex[:16]}"
+            start = time.time()
+            
+            try:
+                result = func(*args, **kwargs)
+                duration = (time.time() - start) * 1000
+                
+                # Add to parent trace
+                trace_ctx.attributes[f"span.{name}.duration_ms"] = duration
+                trace_ctx.attributes[f"span.{name}.status"] = "success"
+                
+                return result
+            except Exception as e:
+                duration = (time.time() - start) * 1000
+                trace_ctx.attributes[f"span.{name}.duration_ms"] = duration
+                trace_ctx.attributes[f"span.{name}.status"] = "error"
+                trace_ctx.attributes[f"span.{name}.error"] = str(e)
+                raise
+                
+        return wrapper
+    return decorator
+
+
+def observe_llm(model: Optional[str] = None, provider: Optional[str] = None):
+    """
+    Decorator specifically for LLM calls with automatic token tracking.
+    
+    Usage:
+        @observe_llm(model="gpt-4", provider="openai")
+        def generate_text(prompt: str):
+            response = openai.chat.completions.create(...)
+            return response
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            trace_ctx = current_trace.get()
+            
+            span_id = f"span_{uuid.uuid4().hex[:16]}"
+            start = time.time()
+            
+            # Extract prompt from args/kwargs if possible
+            prompt = kwargs.get("prompt") or (args[0] if args else None)
+            
+            try:
+                result = func(*args, **kwargs)
+                duration = (time.time() - start) * 1000
+                
+                if trace_ctx:
+                    trace_ctx.attributes.update({
+                        "llm.model": model or "unknown",
+                        "llm.provider": provider or "unknown",
+                        "llm.duration_ms": duration,
+                        "llm.prompt": str(prompt)[:1000] if prompt else None,
+                    })
+                    
+                    # Try to extract token usage from common response formats
+                    if hasattr(result, "usage"):
+                        usage = result.usage
+                        trace_ctx.attributes["llm.tokens.input"] = getattr(usage, "prompt_tokens", None)
+                        trace_ctx.attributes["llm.tokens.output"] = getattr(usage, "completion_tokens", None)
+                        trace_ctx.attributes["llm.tokens.total"] = getattr(usage, "total_tokens", None)
+                    elif isinstance(result, dict):
+                        usage = result.get("usage", {})
+                        trace_ctx.attributes["llm.tokens.input"] = usage.get("prompt_tokens")
+                        trace_ctx.attributes["llm.tokens.output"] = usage.get("completion_tokens")
+                        trace_ctx.attributes["llm.tokens.total"] = usage.get("total_tokens")
+                
+                return result
+            except Exception as e:
+                if trace_ctx:
+                    trace_ctx.attributes["llm.error"] = str(e)
+                raise
+                
+        return wrapper
+    return decorator
+
+
+def set_attribute(key: str, value: Any):
+    """Set an attribute on the current trace context"""
+    trace_ctx = current_trace.get()
+    if trace_ctx:
+        trace_ctx.attributes[key] = value
+
+
+def get_current_trace_id() -> Optional[str]:
+    """Get the current trace ID if available"""
+    trace_ctx = current_trace.get()
+    return trace_ctx.trace_id if trace_ctx else None
+
+
+# Re-exports
+__all__ = [
+    "ZespanFlaskExtension",
+    "ZespanConfig",
+    "observe_span",
+    "observe_llm",
+    "set_attribute",
+    "get_current_trace_id",
+    "TraceContext",
+]