provekit 0.1.0__tar.gz → 0.2.0__tar.gz

provekit-0.2.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: provekit
+Version: 0.2.0
+Summary: Drop-in agent tracing — add one decorator, get a project key, review every run your agent makes.
+Author: ProveKit contributors
+License: MIT
+Project-URL: Homepage, https://github.com/MobirizerServices/ProveKit
+Project-URL: Repository, https://github.com/MobirizerServices/ProveKit
+Project-URL: Issues, https://github.com/MobirizerServices/ProveKit/issues
+Keywords: agent,llm,tracing,observability,opentelemetry,openai,anthropic,otel
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.28
+Provides-Extra: server
+Requires-Dist: fastapi<1,>=0.115; extra == "server"
+Requires-Dist: uvicorn[standard]<1,>=0.34; extra == "server"
+Requires-Dist: sqlalchemy<3,>=2.0; extra == "server"
+Requires-Dist: pydantic<3,>=2.10; extra == "server"
+Requires-Dist: pydantic-settings<3,>=2.7; extra == "server"
+Requires-Dist: cryptography<50,>=42; extra == "server"
+Requires-Dist: anyio<5,>=4; extra == "server"
+Requires-Dist: alembic<2,>=1.18; extra == "server"
+Requires-Dist: psycopg[binary]<4,>=3.3; extra == "server"
+Requires-Dist: email-validator<3,>=2.2; extra == "server"
+Requires-Dist: redis<6,>=5.2; extra == "server"
+Requires-Dist: sentry-sdk[fastapi]<3,>=2.20; extra == "server"
+Provides-Extra: trace
+Requires-Dist: opentelemetry-api<2,>=1.20; extra == "trace"
+Requires-Dist: opentelemetry-sdk<2,>=1.20; extra == "trace"
+Requires-Dist: openinference-instrumentation-openai>=0.1; extra == "trace"
+Requires-Dist: openinference-instrumentation-anthropic>=0.1; extra == "trace"
+Provides-Extra: dev
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Requires-Dist: pytest-cov==6.0.0; extra == "dev"
+Requires-Dist: ruff==0.9.2; extra == "dev"
+
+# ProveKit
+
+**One decorator. The whole agent flow.** Add one `@pk.trace` at your agent's entrypoint and
+review every run — the model calls, tools, and steps — as a nested flow in your ProveKit
+portal. OpenAI/Anthropic calls capture themselves. Open source, self-hostable, no framework
+lock-in.
+
+## Install
+
+```bash
+pip install "provekit[trace]"
+```
+
+## Use
+
+```python
+import provekit.trace as pk
+
+# .env
+#   PROVEKIT_API_KEY=pk_...        (create a project + key in the portal)
+#   PROVEKIT_ENDPOINT=https://your-provekit-host
+
+@pk.trace(name="support-agent")
+def run_agent(question: str) -> str:
+    docs = retrieve(question)          # wrap sub-steps with `with pk.span("retrieve"):`
+    return chat(question, docs)        # the OpenAI/Anthropic call captures itself
+```
+
+Run your agent, open **Traces** in the portal, and every run shows up as a nested waterfall
+with per-span input, output, and token usage.
+
+It's OpenTelemetry under the hood, so your data is portable and nothing is locked in — but
+you never have to touch OTel. Fail-open by design: if the key/endpoint are unset or the
+portal is unreachable, your app runs completely unaffected.
+
+## Run the portal (self-host)
+
+The web app + ingest server ship in the same package:
+
+```bash
+pip install "provekit[server]"
+uvicorn provekit.main:app --port 8100
+```
+
+See the [repo](https://github.com/MobirizerServices/ProveKit) for Docker/compose and the
+full [tracing guide](https://github.com/MobirizerServices/ProveKit/blob/main/docs/TRACING.md).
+
+- Repository: https://github.com/MobirizerServices/ProveKit
+- License: MIT

provekit-0.2.0/README.md

@@ -0,0 +1,49 @@
+# ProveKit
+
+**One decorator. The whole agent flow.** Add one `@pk.trace` at your agent's entrypoint and
+review every run — the model calls, tools, and steps — as a nested flow in your ProveKit
+portal. OpenAI/Anthropic calls capture themselves. Open source, self-hostable, no framework
+lock-in.
+
+## Install
+
+```bash
+pip install "provekit[trace]"
+```
+
+## Use
+
+```python
+import provekit.trace as pk
+
+# .env
+#   PROVEKIT_API_KEY=pk_...        (create a project + key in the portal)
+#   PROVEKIT_ENDPOINT=https://your-provekit-host
+
+@pk.trace(name="support-agent")
+def run_agent(question: str) -> str:
+    docs = retrieve(question)          # wrap sub-steps with `with pk.span("retrieve"):`
+    return chat(question, docs)        # the OpenAI/Anthropic call captures itself
+```
+
+Run your agent, open **Traces** in the portal, and every run shows up as a nested waterfall
+with per-span input, output, and token usage.
+
+It's OpenTelemetry under the hood, so your data is portable and nothing is locked in — but
+you never have to touch OTel. Fail-open by design: if the key/endpoint are unset or the
+portal is unreachable, your app runs completely unaffected.
+
+## Run the portal (self-host)
+
+The web app + ingest server ship in the same package:
+
+```bash
+pip install "provekit[server]"
+uvicorn provekit.main:app --port 8100
+```
+
+See the [repo](https://github.com/MobirizerServices/ProveKit) for Docker/compose and the
+full [tracing guide](https://github.com/MobirizerServices/ProveKit/blob/main/docs/TRACING.md).
+
+- Repository: https://github.com/MobirizerServices/ProveKit
+- License: MIT

{provekit-0.1.0 → provekit-0.2.0}/provekit/database.py

@@ -62,16 +62,6 @@ def init_db() -> None:
         _run_migrations()
 
 
-# Revision that first introduced each column, newest first — used to adopt a pre-migration
-# database (built by the old create_all path) at the revision matching its actual columns.
-_ADOPT_BY_COLUMN = [
-    ("users", "token_version", "a1b2c3d4e5f6"),
-    ("users", "email_verified", "323eb73d463c"),
-    ("workspaces", "ingest_key_hash", "819ed5ff183e"),
-]
-_BASELINE_REVISION = "49e8ab812556"
-
-
 # Postgres advisory-lock key ("AGMN") used to serialize migrations across uvicorn workers.
 _MIGRATION_LOCK_ID = 0x4147_4D4E
 
@@ -113,20 +103,4 @@ def _run_migrations() -> None:
 
 def _migrate_to_head(cfg) -> None:
     from alembic import command
-    from alembic.runtime.migration import MigrationContext
-    from sqlalchemy import inspect
-
-    insp = inspect(engine)
-    with engine.connect() as conn:
-        current = MigrationContext.configure(conn).get_current_revision()
-    if current is None and insp.has_table("users"):
-        # A database created by create_all before migrations existed has the tables but no
-        # alembic version. Stamp it at the revision matching its columns so `upgrade` applies
-        # only what's genuinely missing instead of trying to re-create existing tables.
-        stamp_at = _BASELINE_REVISION
-        for table, column, revision in _ADOPT_BY_COLUMN:
-            if any(c["name"] == column for c in insp.get_columns(table)):
-                stamp_at = revision
-                break
-        command.stamp(cfg, stamp_at)
     command.upgrade(cfg, "head")

{provekit-0.1.0 → provekit-0.2.0}/provekit/main.py

@@ -1,5 +1,5 @@
-"""ProveKit — a generic "Postman for agents": create, run, and debug prompts, MCP tools,
-and agent endpoints across any provider."""
+"""ProveKit — drop-in agent tracing. Add one decorator, get a project key, and review
+every run your agent makes. No connections to configure, no SDK to swap."""
 import logging
 from contextlib import asynccontextmanager
 
@@ -7,8 +7,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from .config import get_settings
-from .database import SessionLocal, init_db
-from .models import Connection
+from .database import init_db
 from .observability import (
     BodySizeLimitMiddleware,
     RequestIDMiddleware,
@@ -17,7 +16,7 @@ from .observability import (
     init_sentry,
     setup_logging,
 )
-from .routers import auth, connections, deployments, flows, library, prompts, run, runtime, traces, usage
+from .routers import apikeys, auth, traces
 
 logging.basicConfig(level=logging.INFO)
 settings = get_settings()
@@ -25,16 +24,6 @@ setup_logging()
 init_sentry()
 
 
-def _reseal_connections(db) -> None:
-    """Upgrade plaintext secrets from older databases to encrypted-at-rest: force each
-    config back through SealedJSON's bind processor (flag_modified beats SQLAlchemy's
-    equal-value change suppression). Idempotent — already-sealed values stay sealed."""
-    from sqlalchemy.orm.attributes import flag_modified
-    for c in db.query(Connection).all():
-        flag_modified(c, "config")
-    db.commit()
-
-
 _WEAK_KEYS = {"", "dev-only-change-me", "change-me", "changeme", "secret"}
 
 
@@ -67,11 +56,6 @@ async def lifespan(app: FastAPI):
     except Exception:
         pass
     init_db()
-    db = SessionLocal()
-    try:
-        _reseal_connections(db)  # per-workspace seeding happens on first workspace access
-    finally:
-        db.close()
     yield
 
 
@@ -93,16 +77,10 @@ app.add_middleware(
 )
 
 app.include_router(auth.router)
-app.include_router(connections.router)
-app.include_router(library.router)
-app.include_router(prompts.router)
-app.include_router(flows.router)
-app.include_router(run.router)
+app.include_router(apikeys.router)
 app.include_router(traces.router)
 app.include_router(traces.ws_router)
-app.include_router(deployments.router)
-app.include_router(runtime.router)
-app.include_router(usage.router)
+app.include_router(traces.runs_router)
 
 
 @app.get("/")

provekit-0.2.0/provekit/migrations/versions/9d2c06bfa4e6_baseline.py

@@ -0,0 +1,121 @@
+"""baseline
+
+Revision ID: 9d2c06bfa4e6
+Revises: 
+Create Date: 2026-07-18 22:58:47.035691
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = '9d2c06bfa4e6'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('users',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('email', sa.String(length=255), nullable=False),
+    sa.Column('name', sa.String(length=160), nullable=False),
+    sa.Column('password_hash', sa.String(length=255), nullable=False),
+    sa.Column('auth_provider', sa.String(length=32), nullable=False),
+    sa.Column('email_verified', sa.Boolean(), nullable=False),
+    sa.Column('token_version', sa.Integer(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_users')),
+    sa.UniqueConstraint('email', name=op.f('uq_users_email'))
+    )
+    op.create_table('workspaces',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('name', sa.String(length=160), nullable=False),
+    sa.Column('owner_user_id', sa.Integer(), nullable=False),
+    sa.Column('ingest_key_hash', sa.String(length=128), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['owner_user_id'], ['users.id'], name=op.f('fk_workspaces_owner_user_id_users')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_workspaces'))
+    )
+    with op.batch_alter_table('workspaces', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_workspaces_ingest_key_hash'), ['ingest_key_hash'], unique=False)
+        batch_op.create_index(batch_op.f('ix_workspaces_owner_user_id'), ['owner_user_id'], unique=False)
+
+    op.create_table('api_keys',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('workspace_id', sa.Integer(), nullable=True),
+    sa.Column('name', sa.String(length=120), nullable=False),
+    sa.Column('prefix', sa.String(length=16), nullable=False),
+    sa.Column('key_hash', sa.String(length=128), nullable=False),
+    sa.Column('last_used_at', sa.DateTime(), nullable=True),
+    sa.Column('revoked', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['workspace_id'], ['workspaces.id'], name=op.f('fk_api_keys_workspace_id_workspaces')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_api_keys'))
+    )
+    with op.batch_alter_table('api_keys', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_api_keys_key_hash'), ['key_hash'], unique=False)
+        batch_op.create_index(batch_op.f('ix_api_keys_workspace_id'), ['workspace_id'], unique=False)
+
+    op.create_table('runs',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('workspace_id', sa.Integer(), nullable=True),
+    sa.Column('type', sa.String(length=16), nullable=False),
+    sa.Column('label', sa.String(length=200), nullable=False),
+    sa.Column('request', sa.JSON(), nullable=False),
+    sa.Column('result', sa.JSON(), nullable=False),
+    sa.Column('status', sa.String(length=16), nullable=False),
+    sa.Column('duration_ms', sa.Integer(), nullable=False),
+    sa.Column('error', sa.Text(), nullable=False),
+    sa.Column('trace_id', sa.String(length=32), nullable=False),
+    sa.Column('span_id', sa.String(length=16), nullable=False),
+    sa.Column('parent_span_id', sa.String(length=16), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['workspace_id'], ['workspaces.id'], name=op.f('fk_runs_workspace_id_workspaces')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_runs'))
+    )
+    with op.batch_alter_table('runs', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_runs_trace_id'), ['trace_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_runs_workspace_id'), ['workspace_id'], unique=False)
+
+    op.create_table('workspace_members',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('workspace_id', sa.Integer(), nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=False),
+    sa.Column('role', sa.String(length=16), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], name=op.f('fk_workspace_members_user_id_users')),
+    sa.ForeignKeyConstraint(['workspace_id'], ['workspaces.id'], name=op.f('fk_workspace_members_workspace_id_workspaces')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_workspace_members')),
+    sa.UniqueConstraint('workspace_id', 'user_id', name='uq_member')
+    )
+    with op.batch_alter_table('workspace_members', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_workspace_members_user_id'), ['user_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_workspace_members_workspace_id'), ['workspace_id'], unique=False)
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('workspace_members', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_workspace_members_workspace_id'))
+        batch_op.drop_index(batch_op.f('ix_workspace_members_user_id'))
+
+    op.drop_table('workspace_members')
+    with op.batch_alter_table('runs', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_runs_workspace_id'))
+        batch_op.drop_index(batch_op.f('ix_runs_trace_id'))
+
+    op.drop_table('runs')
+    with op.batch_alter_table('api_keys', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_api_keys_workspace_id'))
+        batch_op.drop_index(batch_op.f('ix_api_keys_key_hash'))
+
+    op.drop_table('api_keys')
+    with op.batch_alter_table('workspaces', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_workspaces_owner_user_id'))
+        batch_op.drop_index(batch_op.f('ix_workspaces_ingest_key_hash'))
+
+    op.drop_table('workspaces')
+    op.drop_table('users')
+    # ### end Alembic commands ###

provekit-0.2.0/provekit/models.py

@@ -0,0 +1,100 @@
+"""ProveKit data model: accounts, projects (workspaces), project keys, and captured
+runs (the spans of an agent trace)."""
+from datetime import datetime, timezone
+
+from sqlalchemy import DateTime, ForeignKey, Integer, JSON, String, Text, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .database import Base
+
+
+def _ws_fk() -> Mapped[int]:
+    """Workspace FK shared by every tenant-scoped table (indexed for per-workspace queries)."""
+    return mapped_column(ForeignKey("workspaces.id"), index=True, nullable=True)
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def iso_utc(dt: datetime | None) -> str | None:
+    """Serialize a stored timestamp as ISO-8601 with an explicit UTC offset. Timestamps
+    are written in UTC (_now), but SQLite hands them back naive — without the offset the
+    browser would parse them as local time."""
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.isoformat()
+
+
+class User(Base):
+    """An account. password_hash is null for OAuth-only users."""
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(String(255), unique=True)
+    name: Mapped[str] = mapped_column(String(160), default="")
+    password_hash: Mapped[str] = mapped_column(String(255), default="")
+    auth_provider: Mapped[str] = mapped_column(String(32), default="password")  # password | github | local
+    email_verified: Mapped[bool] = mapped_column(default=False)
+    # Bumped on password reset to revoke every previously-issued token (sessions + the
+    # just-used reset link): tokens embed the version and are rejected once it moves on.
+    token_version: Mapped[int] = mapped_column(default=0)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_now)
+
+
+class Workspace(Base):
+    """A project — a tenant boundary. Every user gets a default one; teams share one later."""
+    __tablename__ = "workspaces"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(160), default="My project")
+    owner_user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    # Bearer token for unattended OTLP trace ingest (exporters can't send cookies).
+    ingest_key_hash: Mapped[str] = mapped_column(String(128), default="", index=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_now)
+
+
+class WorkspaceMember(Base):
+    __tablename__ = "workspace_members"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    workspace_id: Mapped[int] = mapped_column(ForeignKey("workspaces.id"), index=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
+    role: Mapped[str] = mapped_column(String(16), default="member")  # owner | member
+    __table_args__ = (UniqueConstraint("workspace_id", "user_id", name="uq_member"),)
+
+
+class ApiKey(Base):
+    """A named, revocable project key (a pk_ bearer key) for shipping traces.
+
+    Unlike the single per-workspace `ingest_key_hash`, a project can hold many of these —
+    one per app or environment — each revocable on its own. Only the SHA-256 hash is
+    stored; the plaintext (`pk_…`) is shown exactly once, at creation."""
+    __tablename__ = "api_keys"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    workspace_id: Mapped[int] = _ws_fk()
+    name: Mapped[str] = mapped_column(String(120), default="")
+    prefix: Mapped[str] = mapped_column(String(16), default="")   # e.g. "pk_A1b2C3d4" for display
+    key_hash: Mapped[str] = mapped_column(String(128), index=True)
+    last_used_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    revoked: Mapped[bool] = mapped_column(default=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_now)
+
+
+class Run(Base):
+    """One captured span. A trace's spans share a trace_id; the tree is rebuilt from
+    span_id / parent_span_id."""
+    __tablename__ = "runs"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    workspace_id: Mapped[int] = _ws_fk()
+    type: Mapped[str] = mapped_column(String(16))               # agent | llm | tool | step
+    label: Mapped[str] = mapped_column(String(200), default="")
+    request: Mapped[dict] = mapped_column(JSON, default=dict)   # {type, provider, model, operation, input}
+    result: Mapped[dict] = mapped_column(JSON, default=dict)    # {text, output, meta}
+    status: Mapped[str] = mapped_column(String(16), default="completed")
+    duration_ms: Mapped[int] = mapped_column(Integer, default=0)
+    error: Mapped[str] = mapped_column(Text, default="")
+    # OTel span identity — lets the portal rebuild spans of one run into a nested tree.
+    trace_id: Mapped[str] = mapped_column(String(32), default="", index=True)
+    span_id: Mapped[str] = mapped_column(String(16), default="")
+    parent_span_id: Mapped[str] = mapped_column(String(16), default="")
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=_now)

provekit-0.2.0/provekit/routers/apikeys.py

@@ -0,0 +1,57 @@
+"""API keys: named, revocable `pk_` bearer keys for machine access (trace ingest, CI, CLI).
+
+The plaintext key is returned exactly once, from POST — the portal shows it, the user drops
+it in their `.env`, and it's never retrievable again (only the SHA-256 hash is stored).
+Listing shows the display prefix + last-used so stale keys are obvious.
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import ApiKey, Workspace, iso_utc
+from ..services import apikey
+from ..services.workspace import current_workspace
+
+router = APIRouter(prefix="/api/api-keys", tags=["api-keys"])
+
+
+def _public(k: ApiKey) -> dict:
+    return {"id": k.id, "name": k.name, "prefix": k.prefix, "revoked": k.revoked,
+            "last_used_at": iso_utc(k.last_used_at), "created_at": iso_utc(k.created_at)}
+
+
+class KeyIn(BaseModel):
+    name: str = ""
+
+
+@router.get("")
+def list_keys(db: Session = Depends(get_db), ws: Workspace = Depends(current_workspace)):
+    keys = (db.query(ApiKey).filter(ApiKey.workspace_id == ws.id)
+            .order_by(ApiKey.created_at.desc()).all())
+    return [_public(k) for k in keys]
+
+
+@router.post("")
+def create_key(body: KeyIn, db: Session = Depends(get_db),
+               ws: Workspace = Depends(current_workspace)):
+    """Mint a key. The plaintext `key` in the response is shown once and never again."""
+    plaintext, key_hash, prefix = apikey.mint()
+    row = ApiKey(workspace_id=ws.id, name=(body.name or "").strip(),
+                 key_hash=key_hash, prefix=prefix)
+    db.add(row)
+    db.commit()
+    db.refresh(row)
+    return {**_public(row), "key": plaintext}
+
+
+@router.delete("/{key_id}")
+def revoke_key(key_id: int, db: Session = Depends(get_db),
+               ws: Workspace = Depends(current_workspace)):
+    """Revoke a key (soft — the row stays so last_used history survives). 404 across workspaces."""
+    row = db.get(ApiKey, key_id)
+    if not row or row.workspace_id != ws.id:
+        raise HTTPException(404, "API key not found")
+    row.revoked = True
+    db.commit()
+    return {"ok": True}

provekit-0.2.0/provekit/routers/traces.py

@@ -0,0 +1,125 @@
+"""OTLP/HTTP trace ingest — point any OpenTelemetry GenAI exporter at /v1/traces and
+its LLM/agent spans show up in ProveKit's history, no SDK swap required.
+
+Auth: a workspace ingest key via `Authorization: Bearer <key>` (what real exporters can
+send), or a session cookie for interactive/local use. Mint the key from
+POST /api/workspace/ingest-key."""
+from fastapi import APIRouter, Depends, Header, HTTPException, Request
+from pydantic import BaseModel
+from sqlalchemy import func
+from sqlalchemy.orm import Session
+
+from ..database import get_db
+from ..models import Run, Workspace, iso_utc
+from ..services import apikey, deploy, otel
+from ..services.workspace import current_workspace
+
+router = APIRouter(prefix="/v1", tags=["traces"])
+ws_router = APIRouter(prefix="/api/workspace", tags=["workspace"])
+runs_router = APIRouter(prefix="/api", tags=["runs"])
+
+
+def _resolve_ingest_ws(db: Session, request: Request, authorization: str | None) -> Workspace:
+    """Bearer ingest key first (exporters), else fall back to the session cookie."""
+    if authorization and authorization.lower().startswith("bearer "):
+        key = authorization[7:].strip()
+        # A named pk_ key (portal-issued, revocable) first, then the legacy per-workspace
+        # ingest key. Both are SHA-256 bearer keys; either resolves the same workspace.
+        ws = apikey.resolve_workspace(db, key)
+        if ws:
+            return ws
+        ws = db.query(Workspace).filter(Workspace.ingest_key_hash == deploy.hash_key(key)).first()
+        if ws:
+            return ws
+        raise HTTPException(403, "Invalid ingest key")
+    # No bearer key: only allowed via a logged-in session (or local mode's default user).
+    from ..services.auth import get_current_user
+    from ..services.workspace import get_or_create_default_workspace
+    user = get_current_user(request, db)
+    return get_or_create_default_workspace(db, user)
+
+
+@router.post("/traces")
+async def ingest_traces(request: Request, db: Session = Depends(get_db),
+                        authorization: str | None = Header(default=None)):
+    """Accept an OTLP ExportTraceServiceRequest (JSON) and persist gen_ai spans as runs.
+    Returns the OTLP success shape so standard exporters are satisfied."""
+    ws = _resolve_ingest_ws(db, request, authorization)
+    try:
+        payload = await request.json()
+    except Exception:
+        return {"partialSuccess": {"rejectedSpans": 0, "errorMessage": "invalid JSON"}}
+    rows = otel.ingest(payload)
+    for kw in rows:
+        db.add(Run(workspace_id=ws.id, **kw))
+    if rows:
+        db.commit()
+    return {"partialSuccess": {}}
+
+
+class _KeyOut(BaseModel):
+    ingest_key: str
+
+
+@ws_router.post("/ingest-key", response_model=_KeyOut)
+def rotate_ingest_key(db: Session = Depends(get_db), ws: Workspace = Depends(current_workspace)):
+    """Mint/rotate this workspace's OTLP ingest key (shown once; stored hashed)."""
+    plaintext, key_hash = deploy.new_api_key()
+    ws.ingest_key_hash = key_hash
+    db.commit()
+    return {"ingest_key": plaintext}
+
+
+# ---- captured runs (what the Traces view reads) ----
+@runs_router.get("/runs")
+def list_runs(limit: int = 50, db: Session = Depends(get_db),
+              ws: Workspace = Depends(current_workspace)):
+    limit = max(1, min(limit, 200))
+    rows = (db.query(Run).filter(Run.workspace_id == ws.id)
+            .order_by(Run.id.desc()).limit(limit).all())
+    return [{"id": r.id, "type": r.type, "label": r.label, "status": r.status,
+             "duration_ms": r.duration_ms, "created_at": iso_utc(r.created_at)} for r in rows]
+
+
+@runs_router.get("/runs/{rid}")
+def get_run(rid: int, db: Session = Depends(get_db), ws: Workspace = Depends(current_workspace)):
+    r = db.get(Run, rid)
+    if not r or r.workspace_id != ws.id:
+        raise HTTPException(404, "Run not found")
+    return {"id": r.id, "type": r.type, "label": r.label, "request": r.request,
+            "result": r.result, "status": r.status, "duration_ms": r.duration_ms,
+            "error": r.error, "created_at": iso_utc(r.created_at)}
+
+
+# ---- traces (spans grouped into a nested tree) ----
+@runs_router.get("/traces")
+def list_traces(limit: int = 50, db: Session = Depends(get_db),
+                ws: Workspace = Depends(current_workspace)):
+    """One row per trace: its root span (the decorated entrypoint), with a span count."""
+    limit = max(1, min(limit, 200))
+    roots = (db.query(Run)
+             .filter(Run.workspace_id == ws.id, Run.parent_span_id == "")
+             .order_by(Run.id.desc()).limit(limit).all())
+    counts = dict(db.query(Run.trace_id, func.count(Run.id))
+                  .filter(Run.workspace_id == ws.id)
+                  .group_by(Run.trace_id).all())
+    return [{"id": r.id, "trace_id": r.trace_id, "label": r.label, "type": r.type,
+             "status": r.status, "duration_ms": r.duration_ms,
+             "span_count": counts.get(r.trace_id, 1) if r.trace_id else 1,
+             "created_at": iso_utc(r.created_at)} for r in roots]
+
+
+@runs_router.get("/traces/{trace_id}")
+def get_trace(trace_id: str, db: Session = Depends(get_db),
+              ws: Workspace = Depends(current_workspace)):
+    """All spans of one trace, in start order — the client rebuilds the tree from
+    span_id / parent_span_id."""
+    spans = (db.query(Run)
+             .filter(Run.workspace_id == ws.id, Run.trace_id == trace_id)
+             .order_by(Run.id.asc()).all())
+    if not spans:
+        raise HTTPException(404, "Trace not found")
+    return [{"id": s.id, "span_id": s.span_id, "parent_span_id": s.parent_span_id,
+             "type": s.type, "label": s.label, "status": s.status, "duration_ms": s.duration_ms,
+             "request": s.request, "result": s.result, "error": s.error,
+             "created_at": iso_utc(s.created_at)} for s in spans]