Coverage for astrocyte/__init__.py: 100%
15 statements
« prev ^ index » next coverage.py v7.15.0, created at 2026-10-29 22:10 +0000
1"""Astrocyte — open-source memory framework for AI agents.
3Public API surface. Import from here, not from submodules.
4"""
6from __future__ import annotations
8from importlib import import_module
9from typing import TYPE_CHECKING, Any
11# Every public name is imported on first use (PEP 562), not when the package
12# is: importing it eagerly pulls in httpx, the providers and every type, ~0.15
13# s that each agent hook process (a fresh interpreter per prompt) paid before
14# doing anything. Type checkers and API tools read the imports below.
15if TYPE_CHECKING:
16 from astrocyte._astrocyte import Astrocyte
18 # Promoted internals: symbols external packages (e.g. the HTTP gateway)
19 # legitimately need. Exported here so consumers never import astrocyte._*
20 # modules directly — enforced by import-linter contracts.
21 from astrocyte._discovery import resolve_provider
22 from astrocyte._log_safety import safe as log_safe
23 from astrocyte.config import IdentityConfig
24 from astrocyte.errors import (
25 AccessDenied,
26 AstrocyteError,
27 CapabilityNotSupported,
28 ConfigError,
29 CrossBorderViolation,
30 IngestError,
31 LegalHoldActive,
32 MipRoutingError,
33 PiiRejected,
34 ProviderUnavailable,
35 RateLimited,
36 )
37 from astrocyte.hybrid import HybridEngineProvider
38 from astrocyte.identity import (
39 BankResolver,
40 accessible_read_banks,
41 effective_permissions,
42 format_principal,
43 parse_principal,
44 resolve_actor,
45 )
46 from astrocyte.pipeline import (
47 PreparedRetainInput,
48 extraction_profile_for_source,
49 merged_extraction_profiles,
50 prepare_retain_input,
51 )
52 from astrocyte.provider import (
53 DocumentStore,
54 EngineProvider,
55 GraphStore,
56 LLMProvider,
57 OutboundTransportProvider,
58 VectorStore,
59 )
60 from astrocyte.recall import (
61 PLACE_BANK,
62 PLACE_QUERY,
63 auth_with_oauth_cache_namespace,
64 build_proxy_headers,
65 clear_oauth2_token_cache_for_tests,
66 exchange_oauth2_authorization_code,
67 fetch_oauth2_client_credentials_token,
68 fetch_oauth2_refresh_access_token,
69 fetch_proxy_recall_hits,
70 gather_proxy_hits_for_bank,
71 merge_external_into_recall_result,
72 merge_manual_and_proxy_hits,
73 post_oauth2_token_endpoint,
74 validate_proxy_recall_dns,
75 validate_proxy_recall_url,
76 )
77 from astrocyte.types import (
78 AccessGrant,
79 ActorIdentity,
80 AstrocyteContext,
81 AuditEvent,
82 BankHealth,
83 Completion,
84 ContentPart,
85 DataClassification,
86 Dispositions,
87 Document,
88 DocumentFilters,
89 DocumentHit,
90 EngineCapabilities,
91 Entity,
92 EntityLink,
93 EvalMetrics,
94 EvalResult,
95 ForgetRequest,
96 ForgetResult,
97 ForgetSelector,
98 GraphHit,
99 HealthIssue,
100 HealthStatus,
101 HookEvent,
102 HttpClientContext,
103 LegalHold,
104 LifecycleAction,
105 LifecycleRunResult,
106 LLMCapabilities,
107 MemoryChange,
108 MemoryChangePage,
109 MemoryEntityAssociation,
110 MemoryHit,
111 MemoryUsage,
112 Message,
113 Metadata,
114 MetadataValue,
115 MultiBankStrategy,
116 PiiMatch,
117 QualityDataPoint,
118 QueryResult,
119 RecallRequest,
120 RecallResult,
121 RecallTrace,
122 ReflectRequest,
123 ReflectResult,
124 RegressionAlert,
125 RetainRequest,
126 RetainResult,
127 RoutingDecision,
128 SyncPushRecord,
129 SyncPushResult,
130 TokenUsage,
131 TransportCapabilities,
132 VectorFilters,
133 VectorHit,
134 VectorItem,
135 )
137_EXPORTS: dict[str, tuple[str, str]] = {
138 "Astrocyte": ("astrocyte._astrocyte", "Astrocyte"),
139 "resolve_provider": ("astrocyte._discovery", "resolve_provider"),
140 "log_safe": ("astrocyte._log_safety", "safe"),
141 "IdentityConfig": ("astrocyte.config", "IdentityConfig"),
142 "AccessDenied": ("astrocyte.errors", "AccessDenied"),
143 "AstrocyteError": ("astrocyte.errors", "AstrocyteError"),
144 "CapabilityNotSupported": ("astrocyte.errors", "CapabilityNotSupported"),
145 "ConfigError": ("astrocyte.errors", "ConfigError"),
146 "CrossBorderViolation": ("astrocyte.errors", "CrossBorderViolation"),
147 "IngestError": ("astrocyte.errors", "IngestError"),
148 "LegalHoldActive": ("astrocyte.errors", "LegalHoldActive"),
149 "MipRoutingError": ("astrocyte.errors", "MipRoutingError"),
150 "PiiRejected": ("astrocyte.errors", "PiiRejected"),
151 "ProviderUnavailable": ("astrocyte.errors", "ProviderUnavailable"),
152 "RateLimited": ("astrocyte.errors", "RateLimited"),
153 "HybridEngineProvider": ("astrocyte.hybrid", "HybridEngineProvider"),
154 "BankResolver": ("astrocyte.identity", "BankResolver"),
155 "accessible_read_banks": ("astrocyte.identity", "accessible_read_banks"),
156 "effective_permissions": ("astrocyte.identity", "effective_permissions"),
157 "format_principal": ("astrocyte.identity", "format_principal"),
158 "parse_principal": ("astrocyte.identity", "parse_principal"),
159 "resolve_actor": ("astrocyte.identity", "resolve_actor"),
160 "PreparedRetainInput": ("astrocyte.pipeline", "PreparedRetainInput"),
161 "extraction_profile_for_source": ("astrocyte.pipeline", "extraction_profile_for_source"),
162 "merged_extraction_profiles": ("astrocyte.pipeline", "merged_extraction_profiles"),
163 "prepare_retain_input": ("astrocyte.pipeline", "prepare_retain_input"),
164 "DocumentStore": ("astrocyte.provider", "DocumentStore"),
165 "EngineProvider": ("astrocyte.provider", "EngineProvider"),
166 "GraphStore": ("astrocyte.provider", "GraphStore"),
167 "LLMProvider": ("astrocyte.provider", "LLMProvider"),
168 "OutboundTransportProvider": ("astrocyte.provider", "OutboundTransportProvider"),
169 "VectorStore": ("astrocyte.provider", "VectorStore"),
170 "PLACE_BANK": ("astrocyte.recall", "PLACE_BANK"),
171 "PLACE_QUERY": ("astrocyte.recall", "PLACE_QUERY"),
172 "auth_with_oauth_cache_namespace": ("astrocyte.recall", "auth_with_oauth_cache_namespace"),
173 "build_proxy_headers": ("astrocyte.recall", "build_proxy_headers"),
174 "clear_oauth2_token_cache_for_tests": ("astrocyte.recall", "clear_oauth2_token_cache_for_tests"),
175 "exchange_oauth2_authorization_code": ("astrocyte.recall", "exchange_oauth2_authorization_code"),
176 "fetch_oauth2_client_credentials_token": ("astrocyte.recall", "fetch_oauth2_client_credentials_token"),
177 "fetch_oauth2_refresh_access_token": ("astrocyte.recall", "fetch_oauth2_refresh_access_token"),
178 "fetch_proxy_recall_hits": ("astrocyte.recall", "fetch_proxy_recall_hits"),
179 "gather_proxy_hits_for_bank": ("astrocyte.recall", "gather_proxy_hits_for_bank"),
180 "merge_external_into_recall_result": ("astrocyte.recall", "merge_external_into_recall_result"),
181 "merge_manual_and_proxy_hits": ("astrocyte.recall", "merge_manual_and_proxy_hits"),
182 "post_oauth2_token_endpoint": ("astrocyte.recall", "post_oauth2_token_endpoint"),
183 "validate_proxy_recall_dns": ("astrocyte.recall", "validate_proxy_recall_dns"),
184 "validate_proxy_recall_url": ("astrocyte.recall", "validate_proxy_recall_url"),
185 "AccessGrant": ("astrocyte.types", "AccessGrant"),
186 "ActorIdentity": ("astrocyte.types", "ActorIdentity"),
187 "AstrocyteContext": ("astrocyte.types", "AstrocyteContext"),
188 "AuditEvent": ("astrocyte.types", "AuditEvent"),
189 "BankHealth": ("astrocyte.types", "BankHealth"),
190 "Completion": ("astrocyte.types", "Completion"),
191 "ContentPart": ("astrocyte.types", "ContentPart"),
192 "DataClassification": ("astrocyte.types", "DataClassification"),
193 "Dispositions": ("astrocyte.types", "Dispositions"),
194 "Document": ("astrocyte.types", "Document"),
195 "DocumentFilters": ("astrocyte.types", "DocumentFilters"),
196 "DocumentHit": ("astrocyte.types", "DocumentHit"),
197 "EngineCapabilities": ("astrocyte.types", "EngineCapabilities"),
198 "Entity": ("astrocyte.types", "Entity"),
199 "EntityLink": ("astrocyte.types", "EntityLink"),
200 "EvalMetrics": ("astrocyte.types", "EvalMetrics"),
201 "EvalResult": ("astrocyte.types", "EvalResult"),
202 "ForgetRequest": ("astrocyte.types", "ForgetRequest"),
203 "ForgetResult": ("astrocyte.types", "ForgetResult"),
204 "ForgetSelector": ("astrocyte.types", "ForgetSelector"),
205 "GraphHit": ("astrocyte.types", "GraphHit"),
206 "HealthIssue": ("astrocyte.types", "HealthIssue"),
207 "HealthStatus": ("astrocyte.types", "HealthStatus"),
208 "HookEvent": ("astrocyte.types", "HookEvent"),
209 "HttpClientContext": ("astrocyte.types", "HttpClientContext"),
210 "LegalHold": ("astrocyte.types", "LegalHold"),
211 "LifecycleAction": ("astrocyte.types", "LifecycleAction"),
212 "LifecycleRunResult": ("astrocyte.types", "LifecycleRunResult"),
213 "LLMCapabilities": ("astrocyte.types", "LLMCapabilities"),
214 "MemoryChange": ("astrocyte.types", "MemoryChange"),
215 "MemoryChangePage": ("astrocyte.types", "MemoryChangePage"),
216 "MemoryEntityAssociation": ("astrocyte.types", "MemoryEntityAssociation"),
217 "MemoryHit": ("astrocyte.types", "MemoryHit"),
218 "MemoryUsage": ("astrocyte.types", "MemoryUsage"),
219 "Message": ("astrocyte.types", "Message"),
220 "Metadata": ("astrocyte.types", "Metadata"),
221 "MetadataValue": ("astrocyte.types", "MetadataValue"),
222 "MultiBankStrategy": ("astrocyte.types", "MultiBankStrategy"),
223 "PiiMatch": ("astrocyte.types", "PiiMatch"),
224 "QualityDataPoint": ("astrocyte.types", "QualityDataPoint"),
225 "QueryResult": ("astrocyte.types", "QueryResult"),
226 "RecallRequest": ("astrocyte.types", "RecallRequest"),
227 "RecallResult": ("astrocyte.types", "RecallResult"),
228 "RecallTrace": ("astrocyte.types", "RecallTrace"),
229 "ReflectRequest": ("astrocyte.types", "ReflectRequest"),
230 "ReflectResult": ("astrocyte.types", "ReflectResult"),
231 "RegressionAlert": ("astrocyte.types", "RegressionAlert"),
232 "RetainRequest": ("astrocyte.types", "RetainRequest"),
233 "RetainResult": ("astrocyte.types", "RetainResult"),
234 "RoutingDecision": ("astrocyte.types", "RoutingDecision"),
235 "SyncPushRecord": ("astrocyte.types", "SyncPushRecord"),
236 "SyncPushResult": ("astrocyte.types", "SyncPushResult"),
237 "TokenUsage": ("astrocyte.types", "TokenUsage"),
238 "TransportCapabilities": ("astrocyte.types", "TransportCapabilities"),
239 "VectorFilters": ("astrocyte.types", "VectorFilters"),
240 "VectorHit": ("astrocyte.types", "VectorHit"),
241 "VectorItem": ("astrocyte.types", "VectorItem"),
242}
245def __getattr__(name: str) -> Any:
246 try:
247 module, attr = _EXPORTS[name]
248 except KeyError:
249 raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
250 value = getattr(import_module(module), attr)
251 globals()[name] = value
252 return value
255def __dir__() -> list[str]:
256 return sorted({*globals(), *_EXPORTS})
259__all__ = [ # noqa: RUF022 — grouped by category, not alphabetically
260 # Main class
261 "Astrocyte",
262 "HybridEngineProvider",
263 # Promoted internals (SPI discovery, log-injection scrubbing)
264 "resolve_provider",
265 "log_safe",
266 # M3 extraction (stable imports)
267 "prepare_retain_input",
268 "merged_extraction_profiles",
269 "extraction_profile_for_source",
270 "PreparedRetainInput",
271 # M4.1 federated recall
272 "PLACE_QUERY",
273 "PLACE_BANK",
274 "auth_with_oauth_cache_namespace",
275 "build_proxy_headers",
276 "clear_oauth2_token_cache_for_tests",
277 "exchange_oauth2_authorization_code",
278 "fetch_oauth2_client_credentials_token",
279 "fetch_oauth2_refresh_access_token",
280 "fetch_proxy_recall_hits",
281 "gather_proxy_hits_for_bank",
282 "merge_manual_and_proxy_hits",
283 "merge_external_into_recall_result",
284 "post_oauth2_token_endpoint",
285 "validate_proxy_recall_dns",
286 "validate_proxy_recall_url",
287 # Errors
288 "AstrocyteError",
289 "ConfigError",
290 "IngestError",
291 "CapabilityNotSupported",
292 "AccessDenied",
293 "RateLimited",
294 "ProviderUnavailable",
295 "PiiRejected",
296 "CrossBorderViolation",
297 "LegalHoldActive",
298 "MipRoutingError",
299 # Protocols
300 "VectorStore",
301 "GraphStore",
302 "DocumentStore",
303 "EngineProvider",
304 "LLMProvider",
305 "OutboundTransportProvider",
306 # Types — common
307 "HealthStatus",
308 "Metadata",
309 "MetadataValue",
310 # Types — vector store
311 "VectorItem",
312 "VectorFilters",
313 "VectorHit",
314 "MemoryChange",
315 "MemoryChangePage",
316 "SyncPushRecord",
317 "SyncPushResult",
318 # Types — graph store
319 "Entity",
320 "EntityLink",
321 "MemoryEntityAssociation",
322 "GraphHit",
323 # Types — document store
324 "Document",
325 "DocumentFilters",
326 "DocumentHit",
327 # Types — engine
328 "RetainRequest",
329 "RetainResult",
330 "RecallRequest",
331 "RecallResult",
332 "MemoryHit",
333 "RecallTrace",
334 "ReflectRequest",
335 "ReflectResult",
336 "Dispositions",
337 "ForgetRequest",
338 "ForgetResult",
339 "EngineCapabilities",
340 # Types — LLM
341 "Message",
342 "ContentPart",
343 "Completion",
344 "TokenUsage",
345 "LLMCapabilities",
346 # Types — transport
347 "HttpClientContext",
348 "TransportCapabilities",
349 # Types — multi-bank
350 "MultiBankStrategy",
351 # Types — access control
352 "AccessGrant",
353 "ActorIdentity",
354 "AstrocyteContext",
355 "IdentityConfig",
356 # Identity (M1)
357 "BankResolver",
358 "resolve_actor",
359 "format_principal",
360 "parse_principal",
361 "effective_permissions",
362 "accessible_read_banks",
363 # Types — hooks
364 "HookEvent",
365 # Types — governance
366 "DataClassification",
367 # Types — lifecycle
368 "AuditEvent",
369 "ForgetSelector",
370 "LegalHold",
371 "LifecycleAction",
372 "LifecycleRunResult",
373 # Types — MIP
374 "RoutingDecision",
375 # Types — analytics
376 "BankHealth",
377 "HealthIssue",
378 "MemoryUsage",
379 "QualityDataPoint",
380 # Types — evaluation
381 "EvalMetrics",
382 "EvalResult",
383 "QueryResult",
384 "RegressionAlert",
385 # Types — PII
386 "PiiMatch",
387]