swiftpy-framework 0.1.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 (211) hide show
  1. swiftpy/.gitignore +0 -0
  2. swiftpy/__init__.py +572 -0
  3. swiftpy/admin/__init__.py +50 -0
  4. swiftpy/admin/auth.py +522 -0
  5. swiftpy/admin/registry.py +567 -0
  6. swiftpy/admin/views.py +1583 -0
  7. swiftpy/ai/__init__.py +199 -0
  8. swiftpy/ai/_deterministic.py +40 -0
  9. swiftpy/ai/_fake.py +604 -0
  10. swiftpy/ai/agents/__init__.py +30 -0
  11. swiftpy/ai/agents/base_agent.py +506 -0
  12. swiftpy/ai/agents/memory.py +864 -0
  13. swiftpy/ai/client.py +1011 -0
  14. swiftpy/ai/conversation.py +171 -0
  15. swiftpy/ai/embeddings.py +321 -0
  16. swiftpy/ai/exceptions.py +75 -0
  17. swiftpy/ai/history_strategies.py +157 -0
  18. swiftpy/ai/middleware.py +918 -0
  19. swiftpy/ai/observability/__init__.py +28 -0
  20. swiftpy/ai/observability/drivers.py +763 -0
  21. swiftpy/ai/observability/observer.py +364 -0
  22. swiftpy/ai/pool.py +102 -0
  23. swiftpy/ai/pricing.py +101 -0
  24. swiftpy/ai/prompts/__init__.py +6 -0
  25. swiftpy/ai/prompts/loader.py +343 -0
  26. swiftpy/ai/providers/__init__.py +22 -0
  27. swiftpy/ai/providers/anthropic_provider.py +353 -0
  28. swiftpy/ai/providers/base.py +273 -0
  29. swiftpy/ai/providers/openai_provider.py +275 -0
  30. swiftpy/ai/rag/__init__.py +53 -0
  31. swiftpy/ai/rag/context_formatter.py +263 -0
  32. swiftpy/ai/rag/pipeline_builder.py +544 -0
  33. swiftpy/ai/rag/reranker.py +484 -0
  34. swiftpy/ai/rag/result.py +78 -0
  35. swiftpy/ai/rag/retriever.py +315 -0
  36. swiftpy/ai/redis_store.py +227 -0
  37. swiftpy/ai/streaming.py +115 -0
  38. swiftpy/ai/tools/__init__.py +22 -0
  39. swiftpy/ai/tools/base_tool.py +489 -0
  40. swiftpy/ai/tools/first_party.py +384 -0
  41. swiftpy/ai/tools/tool_loop.py +417 -0
  42. swiftpy/ai/vectorstore/__init__.py +46 -0
  43. swiftpy/ai/vectorstore/base.py +542 -0
  44. swiftpy/ai/vectorstore/chroma_adapter.py +435 -0
  45. swiftpy/ai/vectorstore/in_memory_adapter.py +321 -0
  46. swiftpy/ai/vectorstore/lancedb_adapter.py +370 -0
  47. swiftpy/ai/vectorstore/pgvector_adapter.py +496 -0
  48. swiftpy/ai/vectorstore/pinecone_adapter.py +445 -0
  49. swiftpy/ai/vectorstore/qdrant_adapter.py +418 -0
  50. swiftpy/auth/__init__.py +50 -0
  51. swiftpy/auth/api_key_guard.py +544 -0
  52. swiftpy/auth/auth_manager.py +259 -0
  53. swiftpy/auth/exceptions.py +71 -0
  54. swiftpy/auth/jwt_guard.py +230 -0
  55. swiftpy/auth/jwt_issuer.py +658 -0
  56. swiftpy/auth/token_blacklist.py +300 -0
  57. swiftpy/cache/__init__.py +14 -0
  58. swiftpy/cache/cache.py +251 -0
  59. swiftpy/cache/driver.py +216 -0
  60. swiftpy/cache/drivers/memory.py +199 -0
  61. swiftpy/cache/drivers/redis.py +421 -0
  62. swiftpy/console/__init__.py +0 -0
  63. swiftpy/console/cli.py +68 -0
  64. swiftpy/console/commands/__init__.py +0 -0
  65. swiftpy/console/commands/cache.py +164 -0
  66. swiftpy/console/commands/make.py +935 -0
  67. swiftpy/console/commands/migrate.py +280 -0
  68. swiftpy/console/commands/new.py +1806 -0
  69. swiftpy/console/commands/queue.py +306 -0
  70. swiftpy/console/commands/seed.py +252 -0
  71. swiftpy/console/commands/start.py +171 -0
  72. swiftpy/console/commands/storage.py +104 -0
  73. swiftpy/console/loader.py +21 -0
  74. swiftpy/console/stubs/__init__.py +26 -0
  75. swiftpy/console/stubs/controller.stub +14 -0
  76. swiftpy/console/stubs/event.stub +14 -0
  77. swiftpy/console/stubs/job.stub +22 -0
  78. swiftpy/console/stubs/listener.stub +14 -0
  79. swiftpy/console/stubs/mail.stub +20 -0
  80. swiftpy/console/stubs/middleware.stub +16 -0
  81. swiftpy/console/stubs/migration.alter.stub +17 -0
  82. swiftpy/console/stubs/migration.api_keys.stub +22 -0
  83. swiftpy/console/stubs/migration.blank.stub +11 -0
  84. swiftpy/console/stubs/migration.create.stub +15 -0
  85. swiftpy/console/stubs/migration.stub +11 -0
  86. swiftpy/console/stubs/migration.update.stub +17 -0
  87. swiftpy/console/stubs/model.stub +17 -0
  88. swiftpy/console/stubs/provider.stub +18 -0
  89. swiftpy/console/stubs/repository.stub +10 -0
  90. swiftpy/console/stubs/request.stub +16 -0
  91. swiftpy/console/stubs/resource.stub +21 -0
  92. swiftpy/console/stubs/schema.stub +12 -0
  93. swiftpy/console/stubs/seeder.stub +14 -0
  94. swiftpy/console/stubs/service.stub +10 -0
  95. swiftpy/core/__init__.py +0 -0
  96. swiftpy/core/application.py +1306 -0
  97. swiftpy/core/bootstrap.py +30 -0
  98. swiftpy/core/config.py +432 -0
  99. swiftpy/core/container.py +596 -0
  100. swiftpy/core/container_exceptions.py +18 -0
  101. swiftpy/core/context.py +148 -0
  102. swiftpy/core/exceptions.py +352 -0
  103. swiftpy/core/providers/base.py +35 -0
  104. swiftpy/database/__init__.py +41 -0
  105. swiftpy/database/exceptions.py +42 -0
  106. swiftpy/database/identifiers.py +105 -0
  107. swiftpy/database/migrations/__init__.py +36 -0
  108. swiftpy/database/migrations/blueprint.py +431 -0
  109. swiftpy/database/migrations/lock.py +104 -0
  110. swiftpy/database/migrations/migration.py +22 -0
  111. swiftpy/database/migrations/migrator.py +507 -0
  112. swiftpy/database/migrations/schema.py +435 -0
  113. swiftpy/database/orm/__init__.py +33 -0
  114. swiftpy/database/orm/fields.py +92 -0
  115. swiftpy/database/orm/model.py +2034 -0
  116. swiftpy/database/orm/registry.py +33 -0
  117. swiftpy/database/orm/relationships.py +836 -0
  118. swiftpy/database/pagination/__init__.py +16 -0
  119. swiftpy/database/pagination/contracts.py +60 -0
  120. swiftpy/database/pagination/paginator.py +112 -0
  121. swiftpy/database/pagination/simple_paginator.py +97 -0
  122. swiftpy/database/pool.py +218 -0
  123. swiftpy/database/query_builder.py +1803 -0
  124. swiftpy/database/seeder.py +39 -0
  125. swiftpy/database/transaction.py +276 -0
  126. swiftpy/events/__init__.py +10 -0
  127. swiftpy/events/dispatcher.py +308 -0
  128. swiftpy/events/redis_bus.py +552 -0
  129. swiftpy/filesystem/__init__.py +227 -0
  130. swiftpy/filesystem/disk.py +378 -0
  131. swiftpy/filesystem/drivers/__init__.py +11 -0
  132. swiftpy/filesystem/drivers/base.py +156 -0
  133. swiftpy/filesystem/drivers/local.py +559 -0
  134. swiftpy/filesystem/drivers/s3.py +655 -0
  135. swiftpy/filesystem/events.py +37 -0
  136. swiftpy/filesystem/exceptions.py +127 -0
  137. swiftpy/filesystem/manager.py +138 -0
  138. swiftpy/filesystem/metadata.py +22 -0
  139. swiftpy/filesystem/paths.py +99 -0
  140. swiftpy/filesystem/service_provider.py +17 -0
  141. swiftpy/filesystem/uploads/__init__.py +13 -0
  142. swiftpy/filesystem/uploads/handlers.py +362 -0
  143. swiftpy/filesystem/uploads/uploaded_file.py +222 -0
  144. swiftpy/filesystem/uploads/validators.py +186 -0
  145. swiftpy/filesystem/visibility.py +22 -0
  146. swiftpy/helpers/__init__.py +42 -0
  147. swiftpy/helpers/helper.py +180 -0
  148. swiftpy/http/exceptions.py +41 -0
  149. swiftpy/http/middleware.py +307 -0
  150. swiftpy/http/request.py +375 -0
  151. swiftpy/http/response.py +442 -0
  152. swiftpy/http/router.py +1050 -0
  153. swiftpy/mail/__init__.py +58 -0
  154. swiftpy/mail/attachments.py +255 -0
  155. swiftpy/mail/config.py +71 -0
  156. swiftpy/mail/envelope.py +183 -0
  157. swiftpy/mail/exceptions.py +90 -0
  158. swiftpy/mail/facade.py +312 -0
  159. swiftpy/mail/mailable.py +53 -0
  160. swiftpy/mail/manager.py +240 -0
  161. swiftpy/mail/message.py +186 -0
  162. swiftpy/mail/models.py +19 -0
  163. swiftpy/mail/queue/__init__.py +5 -0
  164. swiftpy/mail/queue/job.py +279 -0
  165. swiftpy/mail/service_provider.py +19 -0
  166. swiftpy/mail/templates/__init__.py +5 -0
  167. swiftpy/mail/templates/renderer.py +173 -0
  168. swiftpy/mail/transports/__init__.py +21 -0
  169. swiftpy/mail/transports/api/__init__.py +13 -0
  170. swiftpy/mail/transports/api/base.py +194 -0
  171. swiftpy/mail/transports/api/mailgun.py +158 -0
  172. swiftpy/mail/transports/api/resend.py +156 -0
  173. swiftpy/mail/transports/api/sendgrid.py +172 -0
  174. swiftpy/mail/transports/base.py +24 -0
  175. swiftpy/mail/transports/console.py +91 -0
  176. swiftpy/mail/transports/sendmail.py +128 -0
  177. swiftpy/mail/transports/smtp.py +466 -0
  178. swiftpy/queue/__init__.py +13 -0
  179. swiftpy/queue/dispatcher.py +813 -0
  180. swiftpy/queue/job.py +541 -0
  181. swiftpy/queue/worker.py +556 -0
  182. swiftpy/support/__init__.py +12 -0
  183. swiftpy/support/keys.py +108 -0
  184. swiftpy/support/redis_config.py +223 -0
  185. swiftpy/support/strings.py +114 -0
  186. swiftpy/testing/__init__.py +20 -0
  187. swiftpy/testing/fakes/__init__.py +11 -0
  188. swiftpy/testing/fakes/ai_fake.py +21 -0
  189. swiftpy/testing/fakes/vectorstore_fake.py +194 -0
  190. swiftpy/testing/fixtures.py +124 -0
  191. swiftpy/testing/http_client.py +730 -0
  192. swiftpy/testing/test_case.py +126 -0
  193. swiftpy/validation/__init__.py +97 -0
  194. swiftpy/validation/exceptions.py +26 -0
  195. swiftpy/validation/form_request.py +302 -0
  196. swiftpy/validation/protocols.py +33 -0
  197. swiftpy/validation/rules/__init__.py +89 -0
  198. swiftpy/validation/rules/builtin.py +391 -0
  199. swiftpy/validation/rules/exists.py +86 -0
  200. swiftpy/validation/rules/registry.py +290 -0
  201. swiftpy/validation/rules/required.py +55 -0
  202. swiftpy/validation/rules/unique.py +138 -0
  203. swiftpy/validation/validator.py +612 -0
  204. swiftpy/websockets/__init__.py +19 -0
  205. swiftpy/websockets/connection.py +317 -0
  206. swiftpy/websockets/manager.py +271 -0
  207. swiftpy_framework-0.1.0.dist-info/METADATA +603 -0
  208. swiftpy_framework-0.1.0.dist-info/RECORD +211 -0
  209. swiftpy_framework-0.1.0.dist-info/WHEEL +4 -0
  210. swiftpy_framework-0.1.0.dist-info/entry_points.txt +2 -0
  211. swiftpy_framework-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,763 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import json
5
+ from abc import ABC, abstractmethod
6
+ from dataclasses import asdict, dataclass, field
7
+ from datetime import UTC, datetime
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ import asyncpg
12
+
13
+ from swiftpy.ai.providers.base import redact_sensitive_text
14
+ from swiftpy.core.container import get_container
15
+ from swiftpy.database.identifiers import quote_identifier, validate_identifier
16
+ from swiftpy.database.pool import DatabasePool
17
+
18
+ _SECRET_METADATA_TOKENS: tuple[str, ...] = (
19
+ "api_key",
20
+ "apikey",
21
+ "x_api_key",
22
+ "password",
23
+ "secret",
24
+ "token",
25
+ "authorization",
26
+ "private_key",
27
+ )
28
+
29
+
30
+ def _sanitize_metadata_value(value: Any) -> Any:
31
+ """Recursively redact sensitive keys/values inside metadata containers."""
32
+ if isinstance(value, dict):
33
+ return sanitize_metadata(value)
34
+ if isinstance(value, list):
35
+ return [_sanitize_metadata_value(item) for item in value]
36
+ if isinstance(value, tuple):
37
+ return tuple(_sanitize_metadata_value(item) for item in value)
38
+ if isinstance(value, str):
39
+ return redact_sensitive_text(value)
40
+ return value
41
+
42
+
43
+ def sanitize_metadata(metadata: dict[str, Any]) -> dict[str, Any]:
44
+ """Strip sensitive secrets, tokens, passwords, and credentials from observation metadata."""
45
+ redacted: dict[str, Any] = {}
46
+ for k, v in metadata.items():
47
+ norm_k = str(k).lower().replace("-", "_")
48
+ if any(secret in norm_k for secret in _SECRET_METADATA_TOKENS):
49
+ redacted[k] = "[REDACTED]"
50
+ else:
51
+ redacted[k] = _sanitize_metadata_value(v)
52
+ return redacted
53
+
54
+
55
+ @dataclass
56
+ class AIObservation:
57
+ """Represents a single telemetry observation for an LLM call."""
58
+
59
+ id: str
60
+ timestamp: datetime
61
+ model: str
62
+ provider: str
63
+ input_tokens: int
64
+ output_tokens: int
65
+ total_tokens: int
66
+ latency_ms: float
67
+ cost: float
68
+ prompt_hash: str
69
+ status: str = "success"
70
+ error_message: str | None = None
71
+ ttft_ms: float | None = None
72
+ duration_ms: float | None = None
73
+ metadata: dict[str, Any] = field(default_factory=dict)
74
+
75
+ def __post_init__(self) -> None:
76
+ if self.error_message:
77
+ self.error_message = redact_sensitive_text(self.error_message)
78
+ if self.metadata:
79
+ self.metadata = sanitize_metadata(self.metadata)
80
+
81
+ def to_dict(self) -> dict[str, Any]:
82
+ """Convert observation to a JSON-serializable dictionary."""
83
+ d = asdict(self)
84
+ d["timestamp"] = self.timestamp.isoformat()
85
+ return d
86
+
87
+ @classmethod
88
+ def from_dict(cls, data: dict[str, Any]) -> AIObservation:
89
+ """Construct observation from a dictionary."""
90
+ raw_ts = data.get("timestamp")
91
+ if isinstance(raw_ts, str):
92
+ ts = datetime.fromisoformat(raw_ts)
93
+ elif isinstance(raw_ts, datetime):
94
+ ts = raw_ts
95
+ else:
96
+ ts = datetime.now(UTC)
97
+
98
+ raw_ttft = data.get("ttft_ms")
99
+ ttft_ms = float(raw_ttft) if raw_ttft is not None else None
100
+
101
+ raw_duration = data.get("duration_ms")
102
+ duration_ms = float(raw_duration) if raw_duration is not None else None
103
+
104
+ return cls(
105
+ id=str(data.get("id", "")),
106
+ timestamp=ts,
107
+ model=str(data.get("model", "")),
108
+ provider=str(data.get("provider", "")),
109
+ input_tokens=int(data.get("input_tokens", 0)),
110
+ output_tokens=int(data.get("output_tokens", 0)),
111
+ total_tokens=int(data.get("total_tokens", 0)),
112
+ latency_ms=float(data.get("latency_ms", 0.0)),
113
+ cost=float(data.get("cost", 0.0)),
114
+ prompt_hash=str(data.get("prompt_hash", "")),
115
+ status=str(data.get("status", "success")),
116
+ error_message=data.get("error_message"),
117
+ ttft_ms=ttft_ms,
118
+ duration_ms=duration_ms,
119
+ metadata=dict(data.get("metadata", {})),
120
+ )
121
+
122
+
123
+ class BaseObservabilityDriver(ABC):
124
+ """Abstract base class for all AI observability storage drivers."""
125
+
126
+ @abstractmethod
127
+ async def record(self, observation: AIObservation) -> None:
128
+ """Persist a single AI observation record."""
129
+
130
+ @abstractmethod
131
+ async def get_observations(
132
+ self,
133
+ limit: int = 100,
134
+ offset: int = 0,
135
+ *,
136
+ start_date: datetime | str | None = None,
137
+ end_date: datetime | str | None = None,
138
+ provider: str | None = None,
139
+ model: str | None = None,
140
+ status: str | None = None,
141
+ ) -> list[AIObservation]:
142
+ """Retrieve recent AI observations matching optional filters, ordered by timestamp descending."""
143
+
144
+ @abstractmethod
145
+ async def get_stats(self) -> dict[str, Any]:
146
+ """Retrieve aggregated telemetry statistics across all recorded observations."""
147
+
148
+ @abstractmethod
149
+ async def clear(self) -> None:
150
+ """Clear all stored observations (useful in test teardown)."""
151
+
152
+
153
+ def _parse_ts(val: datetime | str | None) -> datetime | None:
154
+ if val is None or isinstance(val, datetime):
155
+ return val
156
+ try:
157
+ return datetime.fromisoformat(val)
158
+ except ValueError:
159
+ return None
160
+
161
+
162
+ def _matches_filters(
163
+ obs: AIObservation,
164
+ start_date: datetime | str | None = None,
165
+ end_date: datetime | str | None = None,
166
+ provider: str | None = None,
167
+ model: str | None = None,
168
+ status: str | None = None,
169
+ ) -> bool:
170
+ ts_start = _parse_ts(start_date)
171
+ ts_end = _parse_ts(end_date)
172
+
173
+ # Normalize tz awareness if needed
174
+ obs_ts = obs.timestamp
175
+ if ts_start is not None:
176
+ if ts_start.tzinfo is None and obs_ts.tzinfo is not None:
177
+ ts_start = ts_start.replace(tzinfo=UTC)
178
+ elif ts_start.tzinfo is not None and obs_ts.tzinfo is None:
179
+ obs_ts = obs_ts.replace(tzinfo=UTC)
180
+ if obs_ts < ts_start:
181
+ return False
182
+
183
+ if ts_end is not None:
184
+ if ts_end.tzinfo is None and obs_ts.tzinfo is not None:
185
+ ts_end = ts_end.replace(tzinfo=UTC)
186
+ elif ts_end.tzinfo is not None and obs_ts.tzinfo is None:
187
+ obs_ts = obs_ts.replace(tzinfo=UTC)
188
+ if obs_ts > ts_end:
189
+ return False
190
+
191
+ if provider is not None and obs.provider.lower() != provider.lower():
192
+ return False
193
+ if model is not None and obs.model.lower() != model.lower():
194
+ return False
195
+
196
+ return not (status is not None and obs.status.lower() != status.lower())
197
+
198
+
199
+ class InMemoryObservabilityDriver(BaseObservabilityDriver):
200
+ """
201
+ In-memory observability driver storing telemetry records in memory.
202
+ Ideal for unit tests and local development without external dependencies.
203
+ """
204
+
205
+ def __init__(self) -> None:
206
+ self._records: list[AIObservation] = []
207
+ self._lock = asyncio.Lock()
208
+
209
+ async def record(self, observation: AIObservation) -> None:
210
+ async with self._lock:
211
+ self._records.append(observation)
212
+
213
+ async def get_observations(
214
+ self,
215
+ limit: int = 100,
216
+ offset: int = 0,
217
+ *,
218
+ start_date: datetime | str | None = None,
219
+ end_date: datetime | str | None = None,
220
+ provider: str | None = None,
221
+ model: str | None = None,
222
+ status: str | None = None,
223
+ ) -> list[AIObservation]:
224
+ async with self._lock:
225
+ filtered = [
226
+ r
227
+ for r in reversed(self._records)
228
+ if _matches_filters(
229
+ r,
230
+ start_date=start_date,
231
+ end_date=end_date,
232
+ provider=provider,
233
+ model=model,
234
+ status=status,
235
+ )
236
+ ]
237
+ return filtered[offset : offset + limit]
238
+
239
+ async def get_stats(self) -> dict[str, Any]:
240
+ async with self._lock:
241
+ records = list(self._records)
242
+
243
+ total_calls = len(records)
244
+ total_input_tokens = sum(r.input_tokens for r in records)
245
+ total_output_tokens = sum(r.output_tokens for r in records)
246
+ total_tokens = sum(r.total_tokens for r in records)
247
+ total_cost = sum(r.cost for r in records)
248
+ avg_latency_ms = (
249
+ sum(r.latency_ms for r in records) / total_calls if total_calls > 0 else 0.0
250
+ )
251
+ successful_calls = sum(1 for r in records if r.status == "success")
252
+ failed_calls = sum(1 for r in records if r.status != "success")
253
+
254
+ by_provider: dict[str, dict[str, Any]] = {}
255
+ by_model: dict[str, dict[str, Any]] = {}
256
+
257
+ for r in records:
258
+ p = r.provider or "unknown"
259
+ if p not in by_provider:
260
+ by_provider[p] = {"calls": 0, "tokens": 0, "cost": 0.0}
261
+ by_provider[p]["calls"] += 1
262
+ by_provider[p]["tokens"] += r.total_tokens
263
+ by_provider[p]["cost"] = round(by_provider[p]["cost"] + r.cost, 6)
264
+
265
+ m = r.model or "unknown"
266
+ if m not in by_model:
267
+ by_model[m] = {"calls": 0, "tokens": 0, "cost": 0.0}
268
+ by_model[m]["calls"] += 1
269
+ by_model[m]["tokens"] += r.total_tokens
270
+ by_model[m]["cost"] = round(by_model[m]["cost"] + r.cost, 6)
271
+
272
+ return {
273
+ "total_calls": total_calls,
274
+ "successful_calls": successful_calls,
275
+ "failed_calls": failed_calls,
276
+ "total_tokens": total_tokens,
277
+ "total_input_tokens": total_input_tokens,
278
+ "total_output_tokens": total_output_tokens,
279
+ "total_cost": round(total_cost, 6),
280
+ "avg_latency_ms": round(avg_latency_ms, 2),
281
+ "by_provider": by_provider,
282
+ "by_model": by_model,
283
+ }
284
+
285
+ async def clear(self) -> None:
286
+ async with self._lock:
287
+ self._records.clear()
288
+
289
+
290
+ def _append_file_sync(file_path: Path, content: str) -> None:
291
+ """Synchronous file append helper offloaded to thread executor."""
292
+ file_path.parent.mkdir(parents=True, exist_ok=True)
293
+ with file_path.open("a", encoding="utf-8") as f:
294
+ f.write(content + "\n")
295
+
296
+
297
+ def _read_file_sync(file_path: Path) -> list[str]:
298
+ """Synchronous file lines reader helper offloaded to thread executor."""
299
+ if not file_path.is_file():
300
+ return []
301
+ with file_path.open("r", encoding="utf-8") as f:
302
+ return [line.strip() for line in f if line.strip()]
303
+
304
+
305
+ def _truncate_file_sync(file_path: Path) -> None:
306
+ """Synchronous file truncate helper offloaded to thread executor."""
307
+ if file_path.is_file():
308
+ with file_path.open("w", encoding="utf-8") as f:
309
+ f.truncate(0)
310
+
311
+
312
+ def _read_tail_observations_sync(
313
+ file_path: Path,
314
+ limit: int,
315
+ offset: int,
316
+ start_date: datetime | str | None,
317
+ end_date: datetime | str | None,
318
+ provider: str | None,
319
+ model: str | None,
320
+ status: str | None,
321
+ ) -> list[AIObservation]:
322
+ """Read filtered observations newest-first and stop once offset+limit rows are matched."""
323
+ lines = _read_file_sync(file_path)
324
+ target = offset + limit
325
+ observations: list[AIObservation] = []
326
+ for line in reversed(lines):
327
+ try:
328
+ data = json.loads(line)
329
+ obs = AIObservation.from_dict(data)
330
+ if _matches_filters(
331
+ obs,
332
+ start_date=start_date,
333
+ end_date=end_date,
334
+ provider=provider,
335
+ model=model,
336
+ status=status,
337
+ ):
338
+ observations.append(obs)
339
+ if target > 0 and len(observations) >= target:
340
+ break
341
+ except (json.JSONDecodeError, ValueError):
342
+ continue
343
+ return observations[offset : offset + limit]
344
+
345
+
346
+ def _compute_file_stats_sync(file_path: Path) -> dict[str, Any]:
347
+ """Stream JSONL observations line-by-line to compute stats in bounded memory."""
348
+ total_calls = 0
349
+ successful_calls = 0
350
+ failed_calls = 0
351
+ total_input_tokens = 0
352
+ total_output_tokens = 0
353
+ total_tokens = 0
354
+ total_cost = 0.0
355
+ total_latency_ms = 0.0
356
+ by_provider: dict[str, dict[str, Any]] = {}
357
+ by_model: dict[str, dict[str, Any]] = {}
358
+
359
+ if file_path.is_file():
360
+ with file_path.open("r", encoding="utf-8") as f:
361
+ for raw_line in f:
362
+ line = raw_line.strip()
363
+ if not line:
364
+ continue
365
+ try:
366
+ data = json.loads(line)
367
+ obs = AIObservation.from_dict(data)
368
+ except (json.JSONDecodeError, ValueError):
369
+ continue
370
+ total_calls += 1
371
+ if obs.status == "success":
372
+ successful_calls += 1
373
+ else:
374
+ failed_calls += 1
375
+ total_input_tokens += obs.input_tokens
376
+ total_output_tokens += obs.output_tokens
377
+ total_tokens += obs.total_tokens
378
+ total_cost += obs.cost
379
+ total_latency_ms += obs.latency_ms
380
+
381
+ p = obs.provider or "unknown"
382
+ if p not in by_provider:
383
+ by_provider[p] = {"calls": 0, "tokens": 0, "cost": 0.0}
384
+ by_provider[p]["calls"] += 1
385
+ by_provider[p]["tokens"] += obs.total_tokens
386
+ by_provider[p]["cost"] = round(by_provider[p]["cost"] + obs.cost, 6)
387
+
388
+ m = obs.model or "unknown"
389
+ if m not in by_model:
390
+ by_model[m] = {"calls": 0, "tokens": 0, "cost": 0.0}
391
+ by_model[m]["calls"] += 1
392
+ by_model[m]["tokens"] += obs.total_tokens
393
+ by_model[m]["cost"] = round(by_model[m]["cost"] + obs.cost, 6)
394
+
395
+ avg_latency_ms = total_latency_ms / total_calls if total_calls > 0 else 0.0
396
+ return {
397
+ "total_calls": total_calls,
398
+ "successful_calls": successful_calls,
399
+ "failed_calls": failed_calls,
400
+ "total_tokens": total_tokens,
401
+ "total_input_tokens": total_input_tokens,
402
+ "total_output_tokens": total_output_tokens,
403
+ "total_cost": round(total_cost, 6),
404
+ "avg_latency_ms": round(avg_latency_ms, 2),
405
+ "by_provider": by_provider,
406
+ "by_model": by_model,
407
+ }
408
+
409
+
410
+ class FileObservabilityDriver(BaseObservabilityDriver):
411
+ """
412
+ File-based observability driver writing structured JSON lines to storage/logs/ai.log.
413
+ Non-blocking: offloads sync file I/O to background threads via asyncio.to_thread.
414
+ """
415
+
416
+ def __init__(self, log_path: str | Path = "storage/logs/ai.log") -> None:
417
+ self.log_path = Path(log_path)
418
+ self._lock = asyncio.Lock()
419
+
420
+ async def record(self, observation: AIObservation) -> None:
421
+ line = json.dumps(observation.to_dict())
422
+ async with self._lock:
423
+ await asyncio.to_thread(_append_file_sync, self.log_path, line)
424
+
425
+ async def get_observations(
426
+ self,
427
+ limit: int = 100,
428
+ offset: int = 0,
429
+ *,
430
+ start_date: datetime | str | None = None,
431
+ end_date: datetime | str | None = None,
432
+ provider: str | None = None,
433
+ model: str | None = None,
434
+ status: str | None = None,
435
+ ) -> list[AIObservation]:
436
+ async with self._lock:
437
+ return await asyncio.to_thread(
438
+ _read_tail_observations_sync,
439
+ self.log_path,
440
+ limit,
441
+ offset,
442
+ start_date,
443
+ end_date,
444
+ provider,
445
+ model,
446
+ status,
447
+ )
448
+
449
+ async def get_stats(self) -> dict[str, Any]:
450
+ async with self._lock:
451
+ return await asyncio.to_thread(_compute_file_stats_sync, self.log_path)
452
+
453
+ async def clear(self) -> None:
454
+ async with self._lock:
455
+ await asyncio.to_thread(_truncate_file_sync, self.log_path)
456
+
457
+
458
+ class DatabaseObservabilityDriver(BaseObservabilityDriver):
459
+ """
460
+ Database observability driver writing structured telemetry rows
461
+ to the PostgreSQL 'ai_observations' relational table.
462
+ """
463
+
464
+ def __init__(
465
+ self,
466
+ pool: DatabasePool | asyncpg.Pool | None = None,
467
+ table_name: str = "ai_observations",
468
+ ) -> None:
469
+ self._raw_pool = pool
470
+ self.table_name = validate_identifier(table_name)
471
+ self._table_checked = False
472
+ self._lock = asyncio.Lock()
473
+
474
+ async def _get_pool(self) -> asyncpg.Pool:
475
+ if isinstance(self._raw_pool, asyncpg.Pool):
476
+ return self._raw_pool
477
+ if isinstance(self._raw_pool, DatabasePool):
478
+ return await self._raw_pool.init()
479
+ try:
480
+ container = get_container()
481
+ db_pool = container.resolve(DatabasePool)
482
+ return await db_pool.init()
483
+ except Exception as exc:
484
+ raise RuntimeError(
485
+ f"DatabasePool could not be resolved for AI observability: {exc}"
486
+ ) from exc
487
+
488
+ def get_ddl(self) -> str:
489
+ """Return PostgreSQL DDL statements required to provision the observations table."""
490
+ table_q = quote_identifier(self.table_name)
491
+ idx_ts_q = quote_identifier(f"idx_{self.table_name}_timestamp")
492
+ idx_prompt_q = quote_identifier(f"idx_{self.table_name}_prompt_hash")
493
+ return f"""
494
+ CREATE TABLE IF NOT EXISTS {table_q} (
495
+ id VARCHAR(64) PRIMARY KEY,
496
+ timestamp TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
497
+ model VARCHAR(255) NOT NULL,
498
+ provider VARCHAR(64) NOT NULL,
499
+ input_tokens INTEGER NOT NULL DEFAULT 0,
500
+ output_tokens INTEGER NOT NULL DEFAULT 0,
501
+ total_tokens INTEGER NOT NULL DEFAULT 0,
502
+ latency_ms DOUBLE PRECISION NOT NULL DEFAULT 0.0,
503
+ cost DOUBLE PRECISION NOT NULL DEFAULT 0.0,
504
+ prompt_hash VARCHAR(64) NOT NULL,
505
+ status VARCHAR(32) NOT NULL DEFAULT 'success',
506
+ error_message TEXT,
507
+ ttft_ms DOUBLE PRECISION,
508
+ duration_ms DOUBLE PRECISION,
509
+ metadata JSONB
510
+ );
511
+ ALTER TABLE {table_q} ADD COLUMN IF NOT EXISTS ttft_ms DOUBLE PRECISION;
512
+ ALTER TABLE {table_q} ADD COLUMN IF NOT EXISTS duration_ms DOUBLE PRECISION;
513
+ CREATE INDEX IF NOT EXISTS {idx_ts_q} ON {table_q} (timestamp DESC);
514
+ CREATE INDEX IF NOT EXISTS {idx_prompt_q} ON {table_q} (prompt_hash);
515
+ """
516
+
517
+ async def ensure_table(self) -> None:
518
+ """Explicit schema setup helper to provision the ai_observations table and indexes."""
519
+ if self._table_checked:
520
+ return
521
+
522
+ async with self._lock:
523
+ if self._table_checked:
524
+ return
525
+
526
+ pool = await self._get_pool()
527
+ ddl = self.get_ddl()
528
+ async with pool.acquire() as conn:
529
+ await conn.execute(ddl)
530
+ self._table_checked = True
531
+
532
+ async def record(self, observation: AIObservation) -> None:
533
+ pool = await self._get_pool()
534
+ sql = f"""
535
+ INSERT INTO {quote_identifier(self.table_name)} (
536
+ id, timestamp, model, provider, input_tokens, output_tokens,
537
+ total_tokens, latency_ms, cost, prompt_hash, status, error_message,
538
+ ttft_ms, duration_ms, metadata
539
+ ) VALUES (
540
+ $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15
541
+ )
542
+ ON CONFLICT (id) DO UPDATE SET
543
+ status = EXCLUDED.status,
544
+ error_message = EXCLUDED.error_message,
545
+ ttft_ms = EXCLUDED.ttft_ms,
546
+ duration_ms = EXCLUDED.duration_ms,
547
+ metadata = EXCLUDED.metadata;
548
+ """
549
+ meta_json = json.dumps(observation.metadata) if observation.metadata else "{}"
550
+ async with pool.acquire() as conn:
551
+ await conn.execute(
552
+ sql,
553
+ observation.id,
554
+ observation.timestamp,
555
+ observation.model,
556
+ observation.provider,
557
+ observation.input_tokens,
558
+ observation.output_tokens,
559
+ observation.total_tokens,
560
+ observation.latency_ms,
561
+ observation.cost,
562
+ observation.prompt_hash,
563
+ observation.status,
564
+ observation.error_message,
565
+ observation.ttft_ms,
566
+ observation.duration_ms,
567
+ meta_json,
568
+ )
569
+
570
+ async def get_observations(
571
+ self,
572
+ limit: int = 100,
573
+ offset: int = 0,
574
+ *,
575
+ start_date: datetime | str | None = None,
576
+ end_date: datetime | str | None = None,
577
+ provider: str | None = None,
578
+ model: str | None = None,
579
+ status: str | None = None,
580
+ ) -> list[AIObservation]:
581
+ pool = await self._get_pool()
582
+
583
+ where_clauses: list[str] = []
584
+ params: list[Any] = []
585
+ idx = 1
586
+
587
+ if start_date is not None:
588
+ ts_start = (
589
+ datetime.fromisoformat(start_date)
590
+ if isinstance(start_date, str)
591
+ else start_date
592
+ )
593
+ where_clauses.append(f"timestamp >= ${idx}")
594
+ params.append(ts_start)
595
+ idx += 1
596
+
597
+ if end_date is not None:
598
+ ts_end = (
599
+ datetime.fromisoformat(end_date)
600
+ if isinstance(end_date, str)
601
+ else end_date
602
+ )
603
+ where_clauses.append(f"timestamp <= ${idx}")
604
+ params.append(ts_end)
605
+ idx += 1
606
+
607
+ if provider is not None:
608
+ where_clauses.append(f"LOWER(provider) = LOWER(${idx})")
609
+ params.append(provider)
610
+ idx += 1
611
+
612
+ if model is not None:
613
+ where_clauses.append(f"LOWER(model) = LOWER(${idx})")
614
+ params.append(model)
615
+ idx += 1
616
+
617
+ if status is not None:
618
+ where_clauses.append(f"LOWER(status) = LOWER(${idx})")
619
+ params.append(status)
620
+ idx += 1
621
+
622
+ where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
623
+ sql = f"""
624
+ SELECT id, timestamp, model, provider, input_tokens, output_tokens,
625
+ total_tokens, latency_ms, cost, prompt_hash, status, error_message,
626
+ ttft_ms, duration_ms, metadata
627
+ FROM {quote_identifier(self.table_name)}
628
+ {where_sql}
629
+ ORDER BY timestamp DESC
630
+ LIMIT ${idx} OFFSET ${idx + 1};
631
+ """
632
+ params.extend([limit, offset])
633
+
634
+ async with pool.acquire() as conn:
635
+ rows = await conn.fetch(sql, *params)
636
+
637
+ results: list[AIObservation] = []
638
+ for r in rows:
639
+ meta = r["metadata"]
640
+ if isinstance(meta, str):
641
+ try:
642
+ meta_dict = json.loads(meta)
643
+ except (json.JSONDecodeError, TypeError, ValueError):
644
+ meta_dict = {}
645
+ elif isinstance(meta, dict):
646
+ meta_dict = meta
647
+ else:
648
+ meta_dict = {}
649
+
650
+ results.append(
651
+ AIObservation(
652
+ id=r["id"],
653
+ timestamp=r["timestamp"],
654
+ model=r["model"],
655
+ provider=r["provider"],
656
+ input_tokens=r["input_tokens"],
657
+ output_tokens=r["output_tokens"],
658
+ total_tokens=r["total_tokens"],
659
+ latency_ms=r["latency_ms"],
660
+ cost=r["cost"],
661
+ prompt_hash=r["prompt_hash"],
662
+ status=r["status"],
663
+ error_message=r["error_message"],
664
+ ttft_ms=r["ttft_ms"],
665
+ duration_ms=r["duration_ms"],
666
+ metadata=meta_dict,
667
+ )
668
+ )
669
+ return results
670
+
671
+ async def get_stats(self) -> dict[str, Any]:
672
+ pool = await self._get_pool()
673
+ table_q = quote_identifier(self.table_name)
674
+ sql_summary = f"""
675
+ SELECT
676
+ COUNT(*) as total_calls,
677
+ COUNT(*) FILTER (WHERE status = 'success') as successful_calls,
678
+ COUNT(*) FILTER (WHERE status != 'success') as failed_calls,
679
+ COALESCE(SUM(total_tokens), 0) as total_tokens,
680
+ COALESCE(SUM(input_tokens), 0) as total_input_tokens,
681
+ COALESCE(SUM(output_tokens), 0) as total_output_tokens,
682
+ COALESCE(SUM(cost), 0.0) as total_cost,
683
+ COALESCE(AVG(latency_ms), 0.0) as avg_latency_ms
684
+ FROM {table_q};
685
+ """
686
+ sql_provider = f"""
687
+ SELECT
688
+ provider,
689
+ COUNT(*) as calls,
690
+ COALESCE(SUM(total_tokens), 0) as tokens,
691
+ COALESCE(SUM(cost), 0.0) as cost
692
+ FROM {table_q}
693
+ GROUP BY provider;
694
+ """
695
+ sql_model = f"""
696
+ SELECT
697
+ model,
698
+ COUNT(*) as calls,
699
+ COALESCE(SUM(total_tokens), 0) as tokens,
700
+ COALESCE(SUM(cost), 0.0) as cost
701
+ FROM {table_q}
702
+ GROUP BY model;
703
+ """
704
+
705
+ async with pool.acquire() as conn:
706
+ summary_row = await conn.fetchrow(sql_summary)
707
+ provider_rows = await conn.fetch(sql_provider)
708
+ model_rows = await conn.fetch(sql_model)
709
+
710
+ by_provider: dict[str, dict[str, Any]] = {}
711
+ for r in provider_rows:
712
+ p = r["provider"] or "unknown"
713
+ by_provider[p] = {
714
+ "calls": int(r["calls"]),
715
+ "tokens": int(r["tokens"]),
716
+ "cost": round(float(r["cost"]), 6),
717
+ }
718
+
719
+ by_model: dict[str, dict[str, Any]] = {}
720
+ for r in model_rows:
721
+ m = r["model"] or "unknown"
722
+ by_model[m] = {
723
+ "calls": int(r["calls"]),
724
+ "tokens": int(r["tokens"]),
725
+ "cost": round(float(r["cost"]), 6),
726
+ }
727
+
728
+ if summary_row:
729
+ total_calls = int(summary_row["total_calls"])
730
+ successful_calls = int(summary_row["successful_calls"])
731
+ failed_calls = int(summary_row["failed_calls"])
732
+ total_tokens = int(summary_row["total_tokens"])
733
+ total_input_tokens = int(summary_row["total_input_tokens"])
734
+ total_output_tokens = int(summary_row["total_output_tokens"])
735
+ total_cost = round(float(summary_row["total_cost"]), 6)
736
+ avg_latency_ms = round(float(summary_row["avg_latency_ms"]), 2)
737
+ else:
738
+ total_calls = 0
739
+ successful_calls = 0
740
+ failed_calls = 0
741
+ total_tokens = 0
742
+ total_input_tokens = 0
743
+ total_output_tokens = 0
744
+ total_cost = 0.0
745
+ avg_latency_ms = 0.0
746
+
747
+ return {
748
+ "total_calls": total_calls,
749
+ "successful_calls": successful_calls,
750
+ "failed_calls": failed_calls,
751
+ "total_tokens": total_tokens,
752
+ "total_input_tokens": total_input_tokens,
753
+ "total_output_tokens": total_output_tokens,
754
+ "total_cost": total_cost,
755
+ "avg_latency_ms": avg_latency_ms,
756
+ "by_provider": by_provider,
757
+ "by_model": by_model,
758
+ }
759
+
760
+ async def clear(self) -> None:
761
+ pool = await self._get_pool()
762
+ async with pool.acquire() as conn:
763
+ await conn.execute(f"TRUNCATE TABLE {quote_identifier(self.table_name)};")