kaizeval 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. kaizeval/__init__.py +3 -0
  2. kaizeval/agentkit.py +234 -0
  3. kaizeval/api/__init__.py +1 -0
  4. kaizeval/api/auth.py +179 -0
  5. kaizeval/api/deps.py +115 -0
  6. kaizeval/api/knowledge.py +313 -0
  7. kaizeval/api/runs.py +472 -0
  8. kaizeval/api/setup.py +356 -0
  9. kaizeval/app.py +131 -0
  10. kaizeval/audit.py +16 -0
  11. kaizeval/cli.py +420 -0
  12. kaizeval/client.py +51 -0
  13. kaizeval/config.py +91 -0
  14. kaizeval/connectors/__init__.py +78 -0
  15. kaizeval/connectors/base.py +115 -0
  16. kaizeval/connectors/http_chat.py +143 -0
  17. kaizeval/connectors/local_config.py +122 -0
  18. kaizeval/db.py +77 -0
  19. kaizeval/documents.py +221 -0
  20. kaizeval/gateway/__init__.py +7 -0
  21. kaizeval/gateway/core.py +406 -0
  22. kaizeval/gateway/fake.py +235 -0
  23. kaizeval/gateway/prompts.py +176 -0
  24. kaizeval/gateway/schemas.py +125 -0
  25. kaizeval/ground_truth.py +122 -0
  26. kaizeval/handlers.py +145 -0
  27. kaizeval/jobs.py +253 -0
  28. kaizeval/mcp_server.py +113 -0
  29. kaizeval/migrations/env.py +29 -0
  30. kaizeval/migrations/script.py.mako +22 -0
  31. kaizeval/migrations/versions/0001_initial_schema.py +632 -0
  32. kaizeval/models.py +395 -0
  33. kaizeval/netguard.py +108 -0
  34. kaizeval/project.py +701 -0
  35. kaizeval/py.typed +0 -0
  36. kaizeval/sample_agent/__init__.py +5 -0
  37. kaizeval/sample_agent/app.py +193 -0
  38. kaizeval/sample_agent/kb/returns-and-refunds.md +23 -0
  39. kaizeval/sample_agent/kb/shipping-and-delivery.md +23 -0
  40. kaizeval/sample_agent/kb/warranty-and-repairs.md +23 -0
  41. kaizeval/security.py +109 -0
  42. kaizeval/services/__init__.py +1 -0
  43. kaizeval/services/datasets.py +521 -0
  44. kaizeval/services/diagnostics.py +238 -0
  45. kaizeval/services/evaluation.py +557 -0
  46. kaizeval/services/holdout.py +58 -0
  47. kaizeval/services/optimization.py +676 -0
  48. kaizeval/services/reporting.py +223 -0
  49. kaizeval/services/specs.py +150 -0
  50. kaizeval/services/stats.py +122 -0
  51. kaizeval/storage.py +115 -0
  52. kaizeval/textutil.py +186 -0
  53. kaizeval/webui/README.txt +2 -0
  54. kaizeval/webui/assets/index-BIG40jck.css +1 -0
  55. kaizeval/webui/assets/index-D8bsydB0.js +72 -0
  56. kaizeval/webui/favicon.svg +1 -0
  57. kaizeval/webui/index.html +15 -0
  58. kaizeval-0.2.0.dist-info/METADATA +427 -0
  59. kaizeval-0.2.0.dist-info/RECORD +63 -0
  60. kaizeval-0.2.0.dist-info/WHEEL +4 -0
  61. kaizeval-0.2.0.dist-info/entry_points.txt +2 -0
  62. kaizeval-0.2.0.dist-info/licenses/LICENSE +202 -0
  63. kaizeval-0.2.0.dist-info/licenses/NOTICE +16 -0
kaizeval/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """Kaizeval: evaluate, diagnose and safely optimize AI agents."""
2
+
3
+ __version__ = "0.2.0"
kaizeval/agentkit.py ADDED
@@ -0,0 +1,234 @@
1
+ """Make your own agent optimizable in a few lines.
2
+
3
+ Kaizeval can only change an agent that gives it a safe way to do so. This module adds that way
4
+ (the "candidate protocol") to any FastAPI agent:
5
+
6
+ from fastapi import FastAPI
7
+ from kaizeval.agentkit import CandidateStore
8
+
9
+ store = CandidateStore(
10
+ defaults={"system_prompt": "You are a support assistant.", "top_k": 3, "cite_sources": False},
11
+ hints={"system_prompt": {"addresses": ["instruction_prompt", "citation"], "max_length": 4000},
12
+ "top_k": {"min": 1, "max": 8, "addresses": ["retrieval_grounding"]}},
13
+ state_file="agent-candidates.json",
14
+ )
15
+ app = FastAPI()
16
+ app.include_router(store.router(admin_token="choose-a-secret"))
17
+
18
+ @app.post("/chat")
19
+ def chat(body: dict):
20
+ version, settings = store.settings(body.get("version")) # baseline, a candidate, or production
21
+ answer = my_agent(body["message"], **settings)
22
+ return {"answer": answer, "citations": [], "version": version, "config_digest": store.digest(version)}
23
+
24
+ What it guarantees:
25
+
26
+ * the baseline (the `defaults` you pass) has no endpoint that can modify it;
27
+ * every candidate is an independent copy; patches are validated against the declared settings;
28
+ * promotion only moves a pointer and needs an approval reference, so going back to the
29
+ baseline is always possible.
30
+
31
+ Then register the agent in Kaizeval with `candidate_protocol: true` (project file) or the
32
+ "Local candidate protocol" adapter (console).
33
+ """
34
+
35
+ from __future__ import annotations
36
+
37
+ import hashlib
38
+ import json
39
+ import threading
40
+ import uuid
41
+ from datetime import datetime, timezone
42
+ from pathlib import Path
43
+ from typing import Any
44
+
45
+ from fastapi import APIRouter, Depends, Header, HTTPException
46
+ from pydantic import BaseModel
47
+
48
+ FAILURE_CATEGORIES = ("instruction_prompt", "retrieval_grounding", "missing_kb_evidence", "citation",
49
+ "output_formatting", "tool_calling", "orchestration")
50
+
51
+
52
+ def digest(config: dict[str, Any]) -> str:
53
+ return hashlib.sha256(json.dumps(config, sort_keys=True, default=str).encode()).hexdigest()
54
+
55
+
56
+ def _infer(value: Any) -> dict[str, Any]:
57
+ if isinstance(value, bool):
58
+ return {"type": "boolean"}
59
+ if isinstance(value, int):
60
+ return {"type": "integer"}
61
+ if isinstance(value, float):
62
+ return {"type": "number"}
63
+ if isinstance(value, str):
64
+ return {"type": "string", "max_length": 4000}
65
+ raise TypeError(f"unsupported setting type: {type(value).__name__} (use bool, int, float or str)")
66
+
67
+
68
+ class _Patch(BaseModel):
69
+ patch: dict[str, Any]
70
+
71
+
72
+ class _Config(BaseModel):
73
+ config: dict[str, Any]
74
+
75
+
76
+ class _Promote(BaseModel):
77
+ candidate_id: str
78
+ approval_id: str
79
+
80
+
81
+ class CandidateStore:
82
+ """Baseline settings, isolated candidate copies and the production pointer of one agent."""
83
+
84
+ def __init__(self, defaults: dict[str, Any], hints: dict[str, dict[str, Any]] | None = None, *,
85
+ description: str = "", state_file: str | Path | None = None):
86
+ if not defaults:
87
+ raise ValueError("defaults must contain at least one setting")
88
+ self._baseline = dict(defaults)
89
+ self.schema: dict[str, dict[str, Any]] = {}
90
+ for key, value in defaults.items():
91
+ self.schema[key] = {**_infer(value), **((hints or {}).get(key) or {})}
92
+ unknown = set(hints or {}) - set(defaults)
93
+ if unknown:
94
+ raise ValueError(f"hints for unknown settings: {sorted(unknown)}")
95
+ self.description = description
96
+ self.state_file = Path(state_file) if state_file else None
97
+ self.lock = threading.Lock()
98
+ self.candidates: dict[str, dict[str, Any]] = {}
99
+ self.production = "baseline"
100
+ self.promotions: list[dict[str, Any]] = []
101
+ if self.state_file and self.state_file.exists():
102
+ data = json.loads(self.state_file.read_text(encoding="utf-8"))
103
+ self.candidates = data.get("candidates", {})
104
+ self.production = data.get("production", "baseline")
105
+ self.promotions = data.get("promotions", [])
106
+
107
+ # -- reading ---------------------------------------------------------------------------
108
+
109
+ def settings(self, version: str | None = None) -> tuple[str, dict[str, Any]]:
110
+ """Return ``(version, settings)``. ``None`` means the production version."""
111
+ version = version or self.production
112
+ if version == "baseline":
113
+ return "baseline", dict(self._baseline)
114
+ if version not in self.candidates:
115
+ raise KeyError(version)
116
+ return version, dict(self.candidates[version])
117
+
118
+ def digest(self, version: str | None = None) -> str:
119
+ return digest(self.settings(version)[1])
120
+
121
+ # -- validation ------------------------------------------------------------------------
122
+
123
+ def validate(self, patch: dict[str, Any]) -> None:
124
+ for key, value in patch.items():
125
+ meta = self.schema.get(key)
126
+ if meta is None:
127
+ raise ValueError(f"'{key}' is not a patchable setting")
128
+ kind = meta["type"]
129
+ if kind == "boolean":
130
+ if not isinstance(value, bool):
131
+ raise ValueError(f"'{key}' must be true or false")
132
+ elif kind == "string":
133
+ if not isinstance(value, str):
134
+ raise ValueError(f"'{key}' must be text")
135
+ if len(value) > int(meta.get("max_length", 4000)):
136
+ raise ValueError(f"'{key}' is longer than {meta.get('max_length', 4000)} characters")
137
+ else:
138
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
139
+ raise ValueError(f"'{key}' must be a number")
140
+ if kind == "integer" and int(value) != value:
141
+ raise ValueError(f"'{key}' must be a whole number")
142
+ if (meta.get("min") is not None and value < meta["min"]) or (meta.get("max") is not None and value > meta["max"]):
143
+ raise ValueError(f"'{key}' must be between {meta.get('min')} and {meta.get('max')}")
144
+
145
+ def _save(self) -> None:
146
+ if self.state_file:
147
+ self.state_file.parent.mkdir(parents=True, exist_ok=True)
148
+ self.state_file.write_text(json.dumps({
149
+ "candidates": self.candidates, "production": self.production, "promotions": self.promotions,
150
+ }, indent=2), encoding="utf-8")
151
+
152
+ # -- the candidate protocol ------------------------------------------------------------
153
+
154
+ def router(self, admin_token: str | None) -> APIRouter:
155
+ """The ``/admin`` endpoints Kaizeval uses. Without a token the admin API answers 403."""
156
+ store = self
157
+
158
+ def admin(authorization: str | None = Header(default=None)) -> None:
159
+ if not admin_token:
160
+ raise HTTPException(403, "admin API is disabled: start the agent with an admin token")
161
+ if authorization != f"Bearer {admin_token}":
162
+ raise HTTPException(401, "invalid admin token")
163
+
164
+ router = APIRouter(prefix="/admin", dependencies=[Depends(admin)])
165
+
166
+ @router.get("/schema")
167
+ def schema() -> dict[str, Any]:
168
+ return {"schema": store.schema, "description": store.description}
169
+
170
+ @router.get("/config")
171
+ def get_config(version: str = "baseline") -> dict[str, Any]:
172
+ try:
173
+ name, config = store.settings(version)
174
+ except KeyError:
175
+ raise HTTPException(404, f"unknown version '{version}'") from None
176
+ return {"version": name, "config": config, "digest": digest(config)}
177
+
178
+ @router.post("/candidates")
179
+ def create_candidate() -> dict[str, Any]:
180
+ with store.lock:
181
+ candidate_id = f"cand-{uuid.uuid4().hex[:10]}"
182
+ store.candidates[candidate_id] = dict(store._baseline)
183
+ store._save()
184
+ return {"candidate_id": candidate_id, "config": dict(store._baseline)}
185
+
186
+ @router.patch("/candidates/{candidate_id}")
187
+ def patch_candidate(candidate_id: str, body: _Patch) -> dict[str, Any]:
188
+ if candidate_id == "baseline" or candidate_id not in store.candidates:
189
+ raise HTTPException(404, "unknown candidate (the baseline cannot be patched)")
190
+ try:
191
+ store.validate(body.patch)
192
+ except ValueError as exc:
193
+ raise HTTPException(422, str(exc)) from None
194
+ with store.lock:
195
+ before = dict(store.candidates[candidate_id])
196
+ store.candidates[candidate_id].update(body.patch)
197
+ after = dict(store.candidates[candidate_id])
198
+ store._save()
199
+ return {"candidate_id": candidate_id, "before": before, "after": after, "digest": digest(after)}
200
+
201
+ @router.put("/candidates/{candidate_id}/config")
202
+ def restore_candidate(candidate_id: str, body: _Config) -> dict[str, Any]:
203
+ if candidate_id == "baseline" or candidate_id not in store.candidates:
204
+ raise HTTPException(404, "unknown candidate (the baseline cannot be changed)")
205
+ if set(body.config) != set(store._baseline):
206
+ raise HTTPException(422, "a restored configuration must contain exactly the known settings")
207
+ try:
208
+ store.validate(body.config)
209
+ except ValueError as exc:
210
+ raise HTTPException(422, str(exc)) from None
211
+ with store.lock:
212
+ store.candidates[candidate_id] = dict(body.config)
213
+ store._save()
214
+ return {"candidate_id": candidate_id, "config": dict(body.config), "digest": digest(body.config)}
215
+
216
+ @router.post("/promote")
217
+ def promote(body: _Promote) -> dict[str, Any]:
218
+ if not body.approval_id.strip():
219
+ raise HTTPException(422, "promotion requires an approval reference")
220
+ if body.candidate_id != "baseline" and body.candidate_id not in store.candidates:
221
+ raise HTTPException(404, "unknown candidate")
222
+ with store.lock:
223
+ previous = store.production
224
+ store.production = body.candidate_id
225
+ store.promotions.append({"from": previous, "to": body.candidate_id, "approval_id": body.approval_id,
226
+ "at": datetime.now(timezone.utc).isoformat()})
227
+ store._save()
228
+ return {"production": store.production, "previous": previous}
229
+
230
+ @router.get("/production")
231
+ def production() -> dict[str, Any]:
232
+ return {"production": store.production, "promotions": store.promotions}
233
+
234
+ return router
@@ -0,0 +1 @@
1
+ """REST API routers (mounted under /api/v1)."""
kaizeval/api/auth.py ADDED
@@ -0,0 +1,179 @@
1
+ """Authentication, workspaces and membership."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Literal
6
+
7
+ from fastapi import APIRouter, Depends
8
+ from pydantic import BaseModel, Field
9
+ from sqlalchemy import func, select
10
+ from sqlalchemy.orm import Session
11
+
12
+ from .. import __version__, audit
13
+ from ..config import get_settings
14
+ from ..connectors import ADAPTER_INFO
15
+ from ..gateway import PROVIDER_KINDS, ROLES, effective_offline
16
+ from ..models import Membership, User, Workspace
17
+ from ..security import create_access_token, hash_password, verify_password
18
+ from .deps import Ctx, current_user, fail, get_db, ser, workspace_ctx
19
+
20
+ router = APIRouter()
21
+
22
+ EMAIL_PATTERN = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
23
+
24
+
25
+ class Signup(BaseModel):
26
+ email: str = Field(pattern=EMAIL_PATTERN, max_length=320)
27
+ password: str = Field(min_length=8, max_length=200)
28
+ name: str = Field(default="", max_length=200)
29
+
30
+
31
+ class Login(BaseModel):
32
+ email: str
33
+ password: str
34
+
35
+
36
+ class WorkspaceCreate(BaseModel):
37
+ name: str = Field(min_length=1, max_length=200)
38
+ mode: Literal["offline", "connected"] = "offline"
39
+
40
+
41
+ class WorkspaceUpdate(BaseModel):
42
+ name: str | None = Field(default=None, min_length=1, max_length=200)
43
+ mode: Literal["offline", "connected"] | None = None
44
+ settings: dict[str, Any] | None = None
45
+
46
+
47
+ class MemberUpsert(BaseModel):
48
+ email: str
49
+ role: Literal["owner", "editor", "reviewer", "viewer"]
50
+
51
+
52
+ def _workspace_dict(workspace: Workspace, role: str | None = None) -> dict[str, Any]:
53
+ return ser(workspace, extra={"role": role, "effective_offline": effective_offline(workspace),
54
+ "instance_offline": get_settings().offline})
55
+
56
+
57
+ @router.get("/system")
58
+ def system(db: Session = Depends(get_db)) -> dict[str, Any]:
59
+ settings = get_settings()
60
+ return {
61
+ "name": "Kaizeval", "version": __version__, "edition": "self-hosted",
62
+ "instance_offline": settings.offline,
63
+ "signup_open": settings.allow_signup or (db.scalar(select(func.count()).select_from(User)) or 0) == 0,
64
+ "model_roles": ROLES, "provider_kinds": PROVIDER_KINDS, "adapters": ADAPTER_INFO,
65
+ "roles": ["owner", "editor", "reviewer", "viewer"],
66
+ "telemetry": "none",
67
+ }
68
+
69
+
70
+ @router.post("/auth/signup", status_code=201)
71
+ def signup(body: Signup, db: Session = Depends(get_db)) -> dict[str, Any]:
72
+ settings = get_settings()
73
+ first_user = (db.scalar(select(func.count()).select_from(User)) or 0) == 0
74
+ if not settings.allow_signup and not first_user:
75
+ raise fail(403, "SIGNUP_DISABLED", "self-service sign-up is disabled on this instance")
76
+ email = body.email.strip().lower()
77
+ if db.scalar(select(User).where(User.email == email)) is not None:
78
+ raise fail(409, "EMAIL_TAKEN", "an account with this email already exists")
79
+ user = User(email=email, name=body.name.strip(), password_hash=hash_password(body.password))
80
+ db.add(user)
81
+ db.commit()
82
+ return {"token": create_access_token(user.id), "user": ser(user)}
83
+
84
+
85
+ @router.post("/auth/login")
86
+ def login(body: Login, db: Session = Depends(get_db)) -> dict[str, Any]:
87
+ user = db.scalar(select(User).where(User.email == body.email.strip().lower()))
88
+ if user is None or not user.is_active or not verify_password(body.password, user.password_hash):
89
+ raise fail(401, "INVALID_CREDENTIALS", "email or password is incorrect")
90
+ return {"token": create_access_token(user.id), "user": ser(user)}
91
+
92
+
93
+ @router.get("/auth/me")
94
+ def me(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict[str, Any]:
95
+ rows = db.execute(select(Workspace, Membership.role).join(Membership, Membership.workspace_id == Workspace.id)
96
+ .where(Membership.user_id == user.id).order_by(Workspace.created_at)).all()
97
+ return {"user": ser(user), "workspaces": [_workspace_dict(w, role) for w, role in rows]}
98
+
99
+
100
+ @router.post("/workspaces", status_code=201)
101
+ def create_workspace(body: WorkspaceCreate, user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict[str, Any]:
102
+ if body.mode == "connected" and get_settings().offline:
103
+ raise fail(409, "INSTANCE_OFFLINE", "this instance runs in strict offline mode (KAIZEVAL_OFFLINE=true); "
104
+ "connected workspaces are not allowed")
105
+ workspace = Workspace(name=body.name.strip(), mode=body.mode, settings={"allow_autonomous_optimization": False})
106
+ db.add(workspace)
107
+ db.flush()
108
+ db.add(Membership(user_id=user.id, workspace_id=workspace.id, role="owner"))
109
+ audit.record(db, workspace_id=workspace.id, user_id=user.id, action="workspace.created",
110
+ subject_type="workspace", subject_id=workspace.id, detail={"mode": body.mode})
111
+ db.commit()
112
+ return _workspace_dict(workspace, "owner")
113
+
114
+
115
+ @router.get("/workspaces/{workspace_id}")
116
+ def get_workspace(ctx: Ctx = Depends(workspace_ctx())) -> dict[str, Any]:
117
+ return _workspace_dict(ctx.workspace, ctx.role)
118
+
119
+
120
+ @router.patch("/workspaces/{workspace_id}")
121
+ def update_workspace(body: WorkspaceUpdate, ctx: Ctx = Depends(workspace_ctx("owner"))) -> dict[str, Any]:
122
+ if body.mode == "connected" and get_settings().offline:
123
+ raise fail(409, "INSTANCE_OFFLINE", "this instance runs in strict offline mode; it cannot be overridden per workspace")
124
+ changes: dict[str, Any] = {}
125
+ if body.name:
126
+ ctx.workspace.name = changes["name"] = body.name.strip()
127
+ if body.mode and body.mode != ctx.workspace.mode:
128
+ ctx.workspace.mode = changes["mode"] = body.mode
129
+ if body.settings is not None:
130
+ allowed = {k: v for k, v in body.settings.items() if k in ("allow_autonomous_optimization", "retention_days")}
131
+ ctx.workspace.settings = {**(ctx.workspace.settings or {}), **allowed}
132
+ changes["settings"] = allowed
133
+ audit.record(ctx.db, workspace_id=ctx.ws, user_id=ctx.user.id, action="workspace.updated",
134
+ subject_type="workspace", subject_id=ctx.ws, detail=changes)
135
+ ctx.db.commit()
136
+ return _workspace_dict(ctx.workspace, ctx.role)
137
+
138
+
139
+ @router.get("/workspaces/{workspace_id}/members")
140
+ def list_members(ctx: Ctx = Depends(workspace_ctx())) -> dict[str, Any]:
141
+ rows = ctx.db.execute(select(User, Membership.role).join(Membership, Membership.user_id == User.id)
142
+ .where(Membership.workspace_id == ctx.ws).order_by(User.email)).all()
143
+ return {"items": [{"user_id": u.id, "email": u.email, "name": u.name, "role": role} for u, role in rows]}
144
+
145
+
146
+ @router.put("/workspaces/{workspace_id}/members")
147
+ def upsert_member(body: MemberUpsert, ctx: Ctx = Depends(workspace_ctx("owner"))) -> dict[str, Any]:
148
+ user = ctx.db.scalar(select(User).where(User.email == body.email.strip().lower()))
149
+ if user is None:
150
+ raise fail(404, "USER_NOT_FOUND", "no account with this email; the person must sign up first")
151
+ membership = ctx.db.scalar(select(Membership).where(Membership.workspace_id == ctx.ws, Membership.user_id == user.id))
152
+ if membership is None:
153
+ membership = Membership(user_id=user.id, workspace_id=ctx.ws, role=body.role)
154
+ ctx.db.add(membership)
155
+ else:
156
+ owners = ctx.db.scalar(select(func.count()).select_from(Membership).where(
157
+ Membership.workspace_id == ctx.ws, Membership.role == "owner")) or 0
158
+ if membership.role == "owner" and body.role != "owner" and owners <= 1:
159
+ raise fail(409, "LAST_OWNER", "a workspace must keep at least one owner")
160
+ membership.role = body.role
161
+ audit.record(ctx.db, workspace_id=ctx.ws, user_id=ctx.user.id, action="member.role_set",
162
+ subject_type="user", subject_id=user.id, detail={"role": body.role})
163
+ ctx.db.commit()
164
+ return {"user_id": user.id, "email": user.email, "role": membership.role}
165
+
166
+
167
+ @router.delete("/workspaces/{workspace_id}/members/{user_id}", status_code=204)
168
+ def remove_member(user_id: str, ctx: Ctx = Depends(workspace_ctx("owner"))) -> None:
169
+ membership = ctx.db.scalar(select(Membership).where(Membership.workspace_id == ctx.ws, Membership.user_id == user_id))
170
+ if membership is None:
171
+ raise fail(404, "NOT_FOUND", "member not found")
172
+ owners = ctx.db.scalar(select(func.count()).select_from(Membership).where(
173
+ Membership.workspace_id == ctx.ws, Membership.role == "owner")) or 0
174
+ if membership.role == "owner" and owners <= 1:
175
+ raise fail(409, "LAST_OWNER", "a workspace must keep at least one owner")
176
+ ctx.db.delete(membership)
177
+ audit.record(ctx.db, workspace_id=ctx.ws, user_id=ctx.user.id, action="member.removed",
178
+ subject_type="user", subject_id=user_id)
179
+ ctx.db.commit()
kaizeval/api/deps.py ADDED
@@ -0,0 +1,115 @@
1
+ """Shared API dependencies: sessions, authentication, workspace-scoped authorization, serialization."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterator
6
+ from dataclasses import dataclass
7
+ from datetime import datetime
8
+ from typing import Any
9
+
10
+ from fastapi import Depends, Header, HTTPException, Path, Request
11
+ from sqlalchemy import func, select
12
+ from sqlalchemy.inspection import inspect as sa_inspect
13
+ from sqlalchemy.orm import Session
14
+
15
+ from ..db import session_factory
16
+ from ..models import Job, Membership, User, Workspace, iso
17
+ from ..security import decode_access_token
18
+
19
+ ROLE_RANK = {"viewer": 0, "reviewer": 1, "editor": 2, "owner": 3}
20
+ HIDDEN = {"password_hash", "ciphertext"}
21
+
22
+
23
+ def get_db() -> Iterator[Session]:
24
+ db = session_factory()()
25
+ try:
26
+ yield db
27
+ finally:
28
+ db.close()
29
+
30
+
31
+ def current_user(authorization: str | None = Header(default=None), db: Session = Depends(get_db)) -> User:
32
+ token = authorization[7:] if authorization and authorization.lower().startswith("bearer ") else None
33
+ user_id = decode_access_token(token) if token else None
34
+ user = db.get(User, user_id) if user_id else None
35
+ if user is None or not user.is_active:
36
+ raise HTTPException(401, detail={"code": "UNAUTHENTICATED", "message": "sign in to continue"})
37
+ return user
38
+
39
+
40
+ @dataclass
41
+ class Ctx:
42
+ db: Session
43
+ user: User
44
+ workspace: Workspace
45
+ role: str
46
+
47
+ @property
48
+ def ws(self) -> str:
49
+ return self.workspace.id
50
+
51
+ def require(self, role: str) -> None:
52
+ if ROLE_RANK[self.role] < ROLE_RANK[role]:
53
+ raise HTTPException(403, detail={"code": "ACCESS_DENIED",
54
+ "message": f"this action needs the '{role}' role; you are '{self.role}'"})
55
+
56
+
57
+ def workspace_ctx(min_role: str = "viewer"):
58
+ """Dependency factory. Non-members get 404 so that workspace ids are not confirmed to outsiders."""
59
+
60
+ def dependency(workspace_id: str = Path(...), user: User = Depends(current_user),
61
+ db: Session = Depends(get_db)) -> Ctx:
62
+ membership = db.scalar(select(Membership).where(Membership.workspace_id == workspace_id,
63
+ Membership.user_id == user.id))
64
+ workspace = db.get(Workspace, workspace_id) if membership else None
65
+ if membership is None or workspace is None:
66
+ raise HTTPException(404, detail={"code": "NOT_FOUND", "message": "workspace not found"})
67
+ ctx = Ctx(db=db, user=user, workspace=workspace, role=membership.role)
68
+ ctx.require(min_role)
69
+ return ctx
70
+
71
+ return dependency
72
+
73
+
74
+ def scoped(ctx: Ctx, model: type, object_id: str) -> Any:
75
+ """Load a row and guarantee it belongs to the caller's workspace."""
76
+ row = ctx.db.get(model, object_id)
77
+ if row is None or getattr(row, "workspace_id", None) != ctx.ws:
78
+ raise HTTPException(404, detail={"code": "NOT_FOUND", "message": f"{model.__name__} not found"})
79
+ return row
80
+
81
+
82
+ def ser(row: Any, *, exclude: set[str] | None = None, extra: dict[str, Any] | None = None) -> dict[str, Any]:
83
+ out: dict[str, Any] = {}
84
+ for column in sa_inspect(type(row)).columns:
85
+ key = column.key
86
+ if key in HIDDEN or (exclude and key in exclude):
87
+ continue
88
+ value = getattr(row, key)
89
+ if key == "secret_id":
90
+ out["has_credential"] = bool(value)
91
+ continue
92
+ out[key] = iso(value) if isinstance(value, datetime) else value
93
+ if extra:
94
+ out.update(extra)
95
+ return out
96
+
97
+
98
+ def page(db: Session, query, *, limit: int, offset: int, transform=ser) -> dict[str, Any]:
99
+ limit = max(1, min(200, limit))
100
+ total = db.scalar(select(func.count()).select_from(query.order_by(None).subquery()))
101
+ items = [transform(row) for row in db.scalars(query.limit(limit).offset(max(0, offset)))]
102
+ return {"items": items, "total": total or 0, "limit": limit, "offset": max(0, offset)}
103
+
104
+
105
+ def job_dict(job: Job) -> dict[str, Any]:
106
+ return ser(job, exclude={"payload", "idempotency_key"})
107
+
108
+
109
+ def idempotency_key(request: Request) -> str | None:
110
+ key = request.headers.get("Idempotency-Key")
111
+ return key[:120] if key else None
112
+
113
+
114
+ def fail(status: int, code: str, message: str) -> HTTPException:
115
+ return HTTPException(status, detail={"code": code, "message": message})