gavio 0.1.0__tar.gz

gavio-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# ─── OS / editor ──────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+*.swp
+*~
+.idea/
+.vscode/
+*.iml
+
+# ─── Node / TypeScript (gavio-js) ─────────────────────────────
+node_modules/
+dist/
+build/
+out/
+coverage/
+*.tsbuildinfo
+.npm/
+.pnpm-store/
+.yarn/
+npm-debug.log*
+yarn-error.log*
+.vitest/
+
+# ─── Python (gavio-py) ────────────────────────────────────────
+.venv/
+venv/
+env/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+
+# ─── Java / Maven / Gradle (gavio-java) ───────────────────────
+target/
+.gradle/
+*.class
+*.jar
+*.war
+hs_err_pid*
+
+# ─── Secrets / local env ──────────────────────────────────────
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# ─── SigMap local artifacts ───────────────────────────────────
+# Generated context (copilot-instructions.md) is committed on purpose;
+# only the local metrics/cache are ignored.
+.context/
+.sigmap-cache/
+
+
+# ---docs--- #
+MASTER_*.md
+SDK_*.md
+*PLAN.md

gavio-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: gavio
+Version: 0.1.0
+Summary: The open standard AI gateway for production systems — PII protection, audit trails, reliability, and cost control as composable interceptors.
+Project-URL: Homepage, https://gavio.io
+Project-URL: Repository, https://github.com/gavio-ai/gavio
+Project-URL: Changelog, https://github.com/gavio-ai/gavio/blob/main/CHANGELOG.md
+Author: Gavio core team
+License: MIT
+Keywords: ai,anthropic,audit,gateway,interceptor,llm,openai,pii
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: elasticsearch; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp; extra == 'all'
+Requires-Dist: opentelemetry-sdk; extra == 'all'
+Requires-Dist: pgvector; extra == 'all'
+Requires-Dist: presidio-analyzer; extra == 'all'
+Requires-Dist: psycopg2; extra == 'all'
+Requires-Dist: redis; extra == 'all'
+Requires-Dist: spacy; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: elasticsearch
+Requires-Dist: elasticsearch; extra == 'elasticsearch'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp; extra == 'otel'
+Requires-Dist: opentelemetry-sdk; extra == 'otel'
+Provides-Extra: pgvector
+Requires-Dist: pgvector; extra == 'pgvector'
+Requires-Dist: psycopg2; extra == 'pgvector'
+Provides-Extra: presidio
+Requires-Dist: presidio-analyzer; extra == 'presidio'
+Requires-Dist: spacy; extra == 'presidio'
+Provides-Extra: redis
+Requires-Dist: redis; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Gavio — Python SDK
+
+> The open standard AI gateway for production systems. PII protection, audit
+> trails, reliability, and cost control as composable interceptors.
+
+`gavio` sits between your application and any LLM provider. The same request
+passes through a pre/post interceptor chain — PII redaction, retries, cost
+tracking, audit logging — before and after the provider call.
+
+Part of the [Gavio](https://gavio.io) project. MIT licensed.
+
+## Install
+
+```bash
+pip install gavio            # zero mandatory dependencies
+pip install gavio[dev]       # + pytest, ruff, mypy
+```
+
+Requires Python 3.10+.
+
+## Quick start (dev mode — no API key, no network)
+
+```python
+import asyncio
+from gavio import Gateway
+from gavio.interceptors.pii import PiiGuard
+
+gw = (
+    Gateway.builder()
+    .dev_mode(True)                 # MockProvider + stdout audit
+    .use(PiiGuard())                # redact PII before it leaves the process
+    .build()
+)
+
+async def main():
+    resp = await gw.complete(
+        messages=[{"role": "user", "content": "Email jan@example.com about NL91ABNA0417164300"}],
+        agent_id="demo",
+    )
+    print(resp.content)             # PII restored in the reply
+    print(f"cost=${resp.cost_usd:.6f} latency={resp.latency_ms}ms")
+    print("pii types:", resp.audit.pii_entity_types)
+
+asyncio.run(main())
+```
+
+## Real providers
+
+```python
+from gavio import Gateway, Provider
+from gavio.interceptors.pii import PiiGuard
+from gavio.interceptors.audit import AuditInterceptor
+from gavio.interceptors.reliability import RetryInterceptor, TimeoutPolicy
+
+gw = (
+    Gateway.builder()
+    .provider(Provider.ANTHROPIC)          # reads ANTHROPIC_API_KEY
+    .model("claude-sonnet-4-6")
+    .use(PiiGuard(sensitivity="strict"))
+    .use(AuditInterceptor(sink="stdout://"))
+    .use(TimeoutPolicy(timeout_seconds=30))
+    .use(RetryInterceptor(max_attempts=3))
+    .build()
+)
+
+resp = await gw.complete(messages=[{"role": "user", "content": "Hi"}])
+```
+
+`OPENAI_API_KEY` / `Provider.OPENAI` work the same way.
+
+## What ships in v0.1.0
+
+- **Core** — `Gateway` fluent builder, `InterceptorChain`, `GavioRequest` /
+  `GavioResponse`, UUID v7 `trace_id`, `agent_id` / `parent_trace_id`.
+- **PII Guard (F-SEC-01)** — Email, IBAN (mod-97), BSN (11-proef),
+  CreditCard (Luhn), Phone, IP, SSN scanners, redact/mask/tag/block, restore.
+- **Secret Scanner (F-SEC-04)** — API keys, JWTs, PEM keys, DB URLs.
+- **Reliability** — retry with backoff (F-REL-01), fallback chain (F-REL-02),
+  timeout (F-REL-07).
+- **Cost tracking (F-GOV-01)** — per-request `cost_usd`.
+- **Audit (F-OBS-01)** — `AuditRecord` + `StdoutSink` (F-OBS-05).
+- **Dev mode (F-DX-01)** and **dry-run mode (F-DX-02)**.
+- **Providers** — OpenAI, Anthropic, Mock.
+
+See the [Python guide](../../docs/packages/python.md) and [CHANGELOG.md](../../CHANGELOG.md).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/unit -v
+ruff check gavio
+```

gavio-0.1.0/README.md

@@ -0,0 +1,93 @@
+# Gavio — Python SDK
+
+> The open standard AI gateway for production systems. PII protection, audit
+> trails, reliability, and cost control as composable interceptors.
+
+`gavio` sits between your application and any LLM provider. The same request
+passes through a pre/post interceptor chain — PII redaction, retries, cost
+tracking, audit logging — before and after the provider call.
+
+Part of the [Gavio](https://gavio.io) project. MIT licensed.
+
+## Install
+
+```bash
+pip install gavio            # zero mandatory dependencies
+pip install gavio[dev]       # + pytest, ruff, mypy
+```
+
+Requires Python 3.10+.
+
+## Quick start (dev mode — no API key, no network)
+
+```python
+import asyncio
+from gavio import Gateway
+from gavio.interceptors.pii import PiiGuard
+
+gw = (
+    Gateway.builder()
+    .dev_mode(True)                 # MockProvider + stdout audit
+    .use(PiiGuard())                # redact PII before it leaves the process
+    .build()
+)
+
+async def main():
+    resp = await gw.complete(
+        messages=[{"role": "user", "content": "Email jan@example.com about NL91ABNA0417164300"}],
+        agent_id="demo",
+    )
+    print(resp.content)             # PII restored in the reply
+    print(f"cost=${resp.cost_usd:.6f} latency={resp.latency_ms}ms")
+    print("pii types:", resp.audit.pii_entity_types)
+
+asyncio.run(main())
+```
+
+## Real providers
+
+```python
+from gavio import Gateway, Provider
+from gavio.interceptors.pii import PiiGuard
+from gavio.interceptors.audit import AuditInterceptor
+from gavio.interceptors.reliability import RetryInterceptor, TimeoutPolicy
+
+gw = (
+    Gateway.builder()
+    .provider(Provider.ANTHROPIC)          # reads ANTHROPIC_API_KEY
+    .model("claude-sonnet-4-6")
+    .use(PiiGuard(sensitivity="strict"))
+    .use(AuditInterceptor(sink="stdout://"))
+    .use(TimeoutPolicy(timeout_seconds=30))
+    .use(RetryInterceptor(max_attempts=3))
+    .build()
+)
+
+resp = await gw.complete(messages=[{"role": "user", "content": "Hi"}])
+```
+
+`OPENAI_API_KEY` / `Provider.OPENAI` work the same way.
+
+## What ships in v0.1.0
+
+- **Core** — `Gateway` fluent builder, `InterceptorChain`, `GavioRequest` /
+  `GavioResponse`, UUID v7 `trace_id`, `agent_id` / `parent_trace_id`.
+- **PII Guard (F-SEC-01)** — Email, IBAN (mod-97), BSN (11-proef),
+  CreditCard (Luhn), Phone, IP, SSN scanners, redact/mask/tag/block, restore.
+- **Secret Scanner (F-SEC-04)** — API keys, JWTs, PEM keys, DB URLs.
+- **Reliability** — retry with backoff (F-REL-01), fallback chain (F-REL-02),
+  timeout (F-REL-07).
+- **Cost tracking (F-GOV-01)** — per-request `cost_usd`.
+- **Audit (F-OBS-01)** — `AuditRecord` + `StdoutSink` (F-OBS-05).
+- **Dev mode (F-DX-01)** and **dry-run mode (F-DX-02)**.
+- **Providers** — OpenAI, Anthropic, Mock.
+
+See the [Python guide](../../docs/packages/python.md) and [CHANGELOG.md](../../CHANGELOG.md).
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/unit -v
+ruff check gavio
+```

gavio-0.1.0/gavio/__init__.py

@@ -0,0 +1,63 @@
+"""Gavio — the open standard AI gateway for production systems.
+
+Public API surface (v0.1.0):
+
+    from gavio import Gateway, GavioRequest, GavioResponse, Provider
+
+See https://gavio.io for documentation. MIT licensed.
+"""
+
+from __future__ import annotations
+
+from .context import InterceptorContext
+from .exceptions import (
+    BudgetExceededError,
+    ConfigurationError,
+    GavioError,
+    GuardrailViolationError,
+    PiiBlockedError,
+    ProviderError,
+    ProviderUnavailableError,
+    RateLimitError,
+    ServerError,
+)
+from .gateway import Gateway, GatewayBuilder
+from .request import GavioRequest
+from .response import GavioResponse
+from .types import (
+    CacheType,
+    GuardrailOutcome,
+    Message,
+    PiiMode,
+    Provider,
+    Sensitivity,
+    TokenUsage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Gateway",
+    "GatewayBuilder",
+    "GavioRequest",
+    "GavioResponse",
+    "InterceptorContext",
+    "Provider",
+    "Message",
+    "TokenUsage",
+    "CacheType",
+    "PiiMode",
+    "Sensitivity",
+    "GuardrailOutcome",
+    # exceptions
+    "GavioError",
+    "ConfigurationError",
+    "ProviderError",
+    "ProviderUnavailableError",
+    "RateLimitError",
+    "ServerError",
+    "PiiBlockedError",
+    "BudgetExceededError",
+    "GuardrailViolationError",
+]

gavio-0.1.0/gavio/_ids.py

@@ -0,0 +1,64 @@
+"""UUID v7 generation — time-sortable, unique identifiers for traces.
+
+Python's stdlib only gains ``uuid.uuid7`` in 3.14, so we ship a compliant
+generator here. UUID v7 layout (RFC 9562): 48-bit Unix millisecond timestamp,
+4-bit version, 12 bits of randomness, 2-bit variant, 62 bits of randomness.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+import uuid
+
+_lock = threading.Lock()
+_last_ms = -1
+_seq = 0  # 12-bit per-millisecond sequence in rand_a, for monotonicity
+
+
+def _next_timestamp_and_seq() -> tuple[int, int]:
+    """Return a (unix_ms, sequence) pair that is monotonically non-decreasing.
+
+    Within a single millisecond the 12-bit sequence increments so IDs stay
+    strictly ordered (RFC 9562 method 1). If the sequence overflows, the
+    timestamp is nudged forward.
+    """
+    global _last_ms, _seq
+    with _lock:
+        now_ms = int(time.time() * 1000)
+        if now_ms > _last_ms:
+            _last_ms = now_ms
+            _seq = int.from_bytes(os.urandom(2), "big") & 0x0FFF
+        else:
+            _seq += 1
+            if _seq > 0x0FFF:
+                _last_ms += 1
+                _seq = 0
+        return _last_ms, _seq
+
+
+def uuid7() -> uuid.UUID:
+    """Return a new UUID version 7 (time-ordered, monotonic within a process)."""
+    unix_ms, rand_a = _next_timestamp_and_seq()
+
+    # 48 bits of millisecond timestamp.
+    time_high = (unix_ms >> 16) & 0xFFFFFFFF
+    time_low = unix_ms & 0xFFFF
+
+    rand_b = int.from_bytes(os.urandom(8), "big") & 0x3FFFFFFFFFFFFFFF  # 62 bits
+
+    value = (
+        (time_high << 96)
+        | (time_low << 80)
+        | (0x7 << 76)  # version 7
+        | (rand_a << 64)
+        | (0b10 << 62)  # variant
+        | rand_b
+    )
+    return uuid.UUID(int=value)
+
+
+def new_trace_id() -> str:
+    """Return a fresh trace id as a string."""
+    return str(uuid7())

gavio-0.1.0/gavio/context.py

@@ -0,0 +1,44 @@
+"""Per-request context passed through the interceptor pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class InterceptorContext:
+    """Mutable scratch space shared by all interceptors within one request.
+
+    One instance per request — never shared across requests or threads.
+    Interceptors stash signals here (PII findings, cache decisions, risk
+    scores) for the audit interceptor to collect at the end of the chain.
+    """
+
+    trace_id: str
+    agent_id: str | None = None
+    parent_trace_id: str | None = None
+    session_id: str | None = None
+    dry_run: bool = False
+
+    # Signals accumulated by interceptors during the request.
+    interceptors_fired: list[str] = field(default_factory=list)
+    pii_entity_types: list[str] = field(default_factory=list)
+    pii_entity_counts: dict[str, int] = field(default_factory=dict)
+    cache_hit: bool = False
+    cache_type: str | None = None
+    risk_score: float | None = None
+    guardrail_outcome: str | None = None
+
+    # Arbitrary inter-interceptor state (e.g. PII replacement map for restore).
+    state: dict[str, Any] = field(default_factory=dict)
+
+    def mark_fired(self, name: str) -> None:
+        if name not in self.interceptors_fired:
+            self.interceptors_fired.append(name)
+
+    def record_pii(self, entity_types: list[str]) -> None:
+        for et in entity_types:
+            self.pii_entity_counts[et] = self.pii_entity_counts.get(et, 0) + 1
+            if et not in self.pii_entity_types:
+                self.pii_entity_types.append(et)

gavio-0.1.0/gavio/exceptions.py

@@ -0,0 +1,53 @@
+"""Gavio exception hierarchy.
+
+All Gavio errors derive from :class:`GavioError` so callers can catch the
+whole family with a single ``except``.
+"""
+
+from __future__ import annotations
+
+
+class GavioError(Exception):
+    """Base class for every error raised by Gavio."""
+
+
+class ConfigurationError(GavioError):
+    """Raised when the gateway is misconfigured (e.g. no provider set)."""
+
+
+class ProviderError(GavioError):
+    """Base class for provider-adapter failures."""
+
+
+class ProviderUnavailableError(ProviderError):
+    """The provider could not be reached (network / health-check failure)."""
+
+
+class RateLimitError(ProviderError):
+    """The provider returned a rate-limit (HTTP 429) signal."""
+
+
+class ServerError(ProviderError):
+    """The provider returned a 5xx server error."""
+
+
+class TimeoutError(ProviderError):  # noqa: A001 - intentional domain name
+    """A request exceeded its configured timeout."""
+
+
+class PiiBlockedError(GavioError):
+    """PiiGuard is in BLOCK mode and detected PII in the request."""
+
+    def __init__(self, entity_types: list[str]) -> None:
+        self.entity_types = entity_types
+        super().__init__(
+            f"Request blocked: PII detected ({', '.join(sorted(set(entity_types)))})"
+        )
+
+
+class BudgetExceededError(GavioError):
+    """A hard budget cap was exceeded. Never swallow this — surface to user."""
+
+
+class GuardrailViolationError(GavioError):
+    """Output failed a guardrail validator with on_failure='error'."""