pycaber 0.2.416__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 (44) hide show
  1. pycaber/__init__.py +119 -0
  2. pycaber/auto/__init__.py +327 -0
  3. pycaber/auto/_api_map.py +428 -0
  4. pycaber/auto/_bootstrap.py +205 -0
  5. pycaber/auto/_circuit_breaker.py +88 -0
  6. pycaber/auto/_cli/__init__.py +0 -0
  7. pycaber/auto/_cli/caber_run.py +42 -0
  8. pycaber/auto/_content_typer.py +139 -0
  9. pycaber/auto/_context.py +72 -0
  10. pycaber/auto/_gating.py +161 -0
  11. pycaber/auto/_helpers.py +385 -0
  12. pycaber/auto/_middleware/__init__.py +10 -0
  13. pycaber/auto/_middleware/_asgi.py +560 -0
  14. pycaber/auto/_middleware/_wsgi.py +252 -0
  15. pycaber/auto/_patches/__init__.py +6 -0
  16. pycaber/auto/_patches/_aiohttp.py +278 -0
  17. pycaber/auto/_patches/_httpx_async.py +43 -0
  18. pycaber/auto/_patches/_httpx_sync.py +45 -0
  19. pycaber/auto/_patches/_requests.py +48 -0
  20. pycaber/auto/_patches/_tornado_ws.py +488 -0
  21. pycaber/auto/_patches/_urllib3.py +92 -0
  22. pycaber/auto/_patches/_websocket_client.py +186 -0
  23. pycaber/auto/_patches/_websockets.py +216 -0
  24. pycaber/auto/_processing.py +973 -0
  25. pycaber/auto/_registry.py +44 -0
  26. pycaber/auto/_state_resolvers.py +115 -0
  27. pycaber/auto/_streamlit_proto.py +599 -0
  28. pycaber/auto/_user_extract.py +171 -0
  29. pycaber/auto/_ws_connection.py +111 -0
  30. pycaber/auto/_ws_exchange.py +128 -0
  31. pycaber/auto/_ws_processing.py +691 -0
  32. pycaber/connector/__init__.py +40 -0
  33. pycaber/connector/api.py +16 -0
  34. pycaber/connector/demo.py +16 -0
  35. pycaber/connector/filesystem.py +16 -0
  36. pycaber/connector/s3.py +16 -0
  37. pycaber/connector/sql.py +16 -0
  38. pycaber/graph/__init__.py +14 -0
  39. pycaber/py.typed +1 -0
  40. pycaber-0.2.416.dist-info/METADATA +20 -0
  41. pycaber-0.2.416.dist-info/RECORD +44 -0
  42. pycaber-0.2.416.dist-info/WHEEL +5 -0
  43. pycaber-0.2.416.dist-info/entry_points.txt +2 -0
  44. pycaber-0.2.416.dist-info/top_level.txt +1 -0
pycaber/__init__.py ADDED
@@ -0,0 +1,119 @@
1
+ """
2
+ PyCaber -- Caber DREAM: Deterministic Attribution and Control of AI Data Use
3
+
4
+ This package re-exports the Rust-native extension module so that existing code
5
+ using ``import pycaber`` continues to work unchanged.
6
+ """
7
+
8
+ # Import from whichever cdylib is installed.
9
+ # pycaber_ingest is a superset; pycaber_wrap is the minimum.
10
+ try:
11
+ from pycaber_ingest import * # noqa: F401,F403
12
+ except ImportError:
13
+ from pycaber_wrap import * # noqa: F401,F403
14
+
15
+ # Re-export pycaber_graph symbols when the graph wheel is installed.
16
+ # This list must be kept in sync with add_class/add_function calls in
17
+ # packages/pycaber_graph/src/lib.rs and register_link_data_module().
18
+ try:
19
+ from pycaber_graph import (
20
+ # Roaring index classes
21
+ RustIntersector,
22
+ DocMetadata,
23
+ RegionMetadata,
24
+ DocumentIndex,
25
+ # Graph builder / analyzer classes
26
+ PyGraphBuilder,
27
+ PyCypherGenerator,
28
+ PyGraphAnalyzer,
29
+ # LightRAG retriever classes
30
+ LightRAGConfig,
31
+ LightRAGRetriever,
32
+ # RBIX / roaring helper functions
33
+ read_rbix_chunk_ids,
34
+ # Intersector pipeline functions
35
+ intersector_build_incremental,
36
+ standalone_step2_intersector,
37
+ standalone_step3_event_mapper,
38
+ intersector_get_version,
39
+ intersector_validate_index,
40
+ intersector_get_index_info,
41
+ # Link data functions
42
+ link_data_create_engine,
43
+ link_data_process_intersector_output,
44
+ link_data_build_incremental,
45
+ event_mapper_3_process,
46
+ # Atomic intersector management
47
+ atomic_intersector_query_kmers,
48
+ atomic_intersector_load_cqf_indices,
49
+ atomic_intersector_build_incremental,
50
+ atomic_intersector_get_current_build,
51
+ atomic_intersector_list_builds,
52
+ atomic_intersector_get_build_status,
53
+ atomic_intersector_cleanup_workspace,
54
+ atomic_intersector_run_retention,
55
+ atomic_intersector_get_workspace_stats,
56
+ )
57
+
58
+ # Feature-gated functions (rust-intersector) -- may not be present in all builds
59
+ try:
60
+ from pycaber_graph import build_roaring_from_rbix # noqa: F401
61
+ except ImportError:
62
+ pass
63
+ try:
64
+ from pycaber_graph import build_roaring_and_process # noqa: F401
65
+ except ImportError:
66
+ pass
67
+
68
+ # Alias graph-specific build_info to avoid shadowing core build_info
69
+ from pycaber_graph import build_info as graph_build_info # noqa: F401
70
+ except ImportError:
71
+ pass # pycaber-graph not installed; graph symbols unavailable
72
+
73
+
74
+ # ── Component version visibility ─────────────────────────────────────────────
75
+
76
+ # Capture the native configure function before wrapping
77
+ _native_configure = configure # noqa: F821 (imported via star-import above)
78
+
79
+
80
+ def component_versions() -> dict:
81
+ """Return build info for all installed PyCaber components.
82
+
83
+ Returns a dict mapping package name to its build_info() dict.
84
+ Only installed components are included.
85
+ """
86
+ versions = {}
87
+ try:
88
+ info = build_info() # noqa: F821
89
+ versions[info.get("package", "pycaber_wrap")] = info
90
+ except Exception:
91
+ pass
92
+ try:
93
+ versions["pycaber_graph"] = graph_build_info() # noqa: F821
94
+ except (NameError, Exception):
95
+ pass
96
+ return versions
97
+
98
+
99
+ def configure(*args, **kwargs):
100
+ """Configure PyCaber and log all component versions."""
101
+ import logging
102
+
103
+ result = _native_configure(*args, **kwargs)
104
+
105
+ try:
106
+ versions = component_versions()
107
+ parts = [f"{n}={i.get('version', '?')}" for n, i in sorted(versions.items())]
108
+ logging.getLogger("pycaber").info("components: %s", ", ".join(parts))
109
+ except Exception:
110
+ pass
111
+
112
+ global _caber_auto_configured
113
+ _caber_auto_configured = True
114
+
115
+ return result
116
+
117
+
118
+ # Track whether configure() has been called (used by pycaber.auto._bootstrap)
119
+ _caber_auto_configured: bool = False
@@ -0,0 +1,327 @@
1
+ """Transparent API interception for PyCaber.
2
+
3
+ ``import pycaber.auto`` bootstraps PyCaber configuration and installs
4
+ deferred patches on supported HTTP libraries. Patches are applied lazily
5
+ via ``wrapt.when_imported()`` so only libraries the application actually
6
+ imports are patched.
7
+
8
+ Supported outbound libraries:
9
+ - requests (Session.send)
10
+ - httpx sync (Client.send) and async (AsyncClient.send)
11
+ - aiohttp (ClientSession._request)
12
+ - urllib3 (HTTPConnectionPool.urlopen)
13
+
14
+ Supported outbound WebSocket libraries:
15
+ - aiohttp (ClientSession.ws_connect)
16
+ - websockets (asyncio connect, ClientConnection.send/recv)
17
+ - websocket-client (WebSocket.connect/send/recv)
18
+
19
+ Supported inbound middleware:
20
+ - Flask / Django via CaberWSGIMiddleware
21
+ - FastAPI / Starlette via CaberASGIMiddleware (HTTP + WebSocket)
22
+
23
+ WebSocket support:
24
+ The ASGI middleware automatically intercepts WebSocket connections
25
+ on FastAPI/Starlette. Each WS message is fingerprinted, OBO-tracked,
26
+ and optionally redacted as an independent record with R.ID format
27
+ ``ATAP-<connection_id>-<msg_seq>-{P,G}``.
28
+
29
+ WebSocket env vars:
30
+ CABER_WS_ENABLED=true Master switch (default: true)
31
+ CABER_WS_MAX_MESSAGE_SIZE Max payload bytes (default: 16MB)
32
+ CABER_WS_MIN_MESSAGE_SIZE Min payload bytes (default: 1)
33
+ CABER_WS_SAMPLE_RATE Fraction to process (default: 1.0)
34
+ CABER_WS_MAX_MESSAGES Per-connection cap (default: 10000)
35
+ CABER_WS_POST_EVENTS=true Post events vs fingerprint-only
36
+
37
+ Configuration:
38
+ By default, PyCaber is auto-configured from ``CSI_API_KEY`` and
39
+ ``CSI_CABER_HOST`` environment variables. To configure manually,
40
+ call ``pycaber.configure(...)`` **before** ``import pycaber.auto``.
41
+
42
+ Skip patching specific modules via ``CABER_NOPATCH_MODULES`` (comma-separated):
43
+ CABER_NOPATCH_MODULES=urllib3,flask # patch everything except these
44
+ Disable redaction (dry-run mode, fingerprint + post but don't modify bodies):
45
+ CABER_REDACT_ENABLED=false
46
+ Disable completely:
47
+ CABER_AUTO_INSTRUMENT=false
48
+ """
49
+
50
+ import logging
51
+ import os
52
+
53
+ logger = logging.getLogger("pycaber.auto")
54
+
55
+ # Re-export middleware for manual installation (always available)
56
+ from ._middleware import CaberWSGIMiddleware, CaberASGIMiddleware # noqa: E402, F401
57
+
58
+ # ---------------------------------------------------------------------------
59
+ # Kill switch check
60
+ # ---------------------------------------------------------------------------
61
+
62
+ _INSTRUMENT_DISABLED = (
63
+ os.environ.get("CABER_AUTO_INSTRUMENT", "true").lower() == "false"
64
+ )
65
+
66
+ # ---------------------------------------------------------------------------
67
+ # Determine which modules to patch
68
+ # ---------------------------------------------------------------------------
69
+
70
+ _nopatch_filter = os.environ.get("CABER_NOPATCH_MODULES", "")
71
+ _EXCLUDED_MODULES = frozenset(
72
+ m.strip().lower() for m in _nopatch_filter.split(",") if m.strip()
73
+ ) if _nopatch_filter else frozenset()
74
+
75
+
76
+ def _should_patch(name: str) -> bool:
77
+ return name not in _EXCLUDED_MODULES
78
+
79
+
80
+ # ---------------------------------------------------------------------------
81
+ # Framework auto-install helpers (Flask, FastAPI)
82
+ # Must be defined before _install_patches() because wrapt.when_imported()
83
+ # fires immediately if the library is already imported.
84
+ # ---------------------------------------------------------------------------
85
+
86
+ def _patch_flask(flask_module):
87
+ """Wrap Flask.__init__ to auto-install CaberWSGIMiddleware."""
88
+ from ._middleware._wsgi import CaberWSGIMiddleware
89
+ from ._registry import is_patched, mark_patched, store_original
90
+ import functools
91
+
92
+ if is_patched("flask"):
93
+ return
94
+
95
+ original_init = flask_module.Flask.__init__
96
+
97
+ @functools.wraps(original_init)
98
+ def caber_flask_init(self, *args, **kwargs):
99
+ original_init(self, *args, **kwargs)
100
+ self.wsgi_app = CaberWSGIMiddleware(self.wsgi_app)
101
+
102
+ flask_module.Flask.__init__ = caber_flask_init
103
+ store_original("flask", "Flask.__init__", original_init)
104
+ mark_patched("flask")
105
+
106
+
107
+ def _patch_fastapi(fastapi_module):
108
+ """Wrap FastAPI.__init__ to auto-install CaberASGIMiddleware."""
109
+ from ._middleware._asgi import CaberASGIMiddleware
110
+ from ._registry import is_patched, mark_patched, store_original
111
+ import functools
112
+
113
+ if is_patched("fastapi"):
114
+ return
115
+
116
+ original_init = fastapi_module.FastAPI.__init__
117
+
118
+ @functools.wraps(original_init)
119
+ def caber_fastapi_init(self, *args, **kwargs):
120
+ original_init(self, *args, **kwargs)
121
+ self.add_middleware(CaberASGIMiddleware)
122
+
123
+ fastapi_module.FastAPI.__init__ = caber_fastapi_init
124
+ store_original("fastapi", "FastAPI.__init__", original_init)
125
+ mark_patched("fastapi")
126
+
127
+
128
+ # ---------------------------------------------------------------------------
129
+ # Bootstrap and patch registration
130
+ # ---------------------------------------------------------------------------
131
+
132
+ def _install_patches() -> None:
133
+ """Bootstrap PyCaber and register deferred patches.
134
+
135
+ Separated into a function so the kill switch can skip it entirely.
136
+ """
137
+ from ._bootstrap import bootstrap as _bootstrap
138
+
139
+ ready = _bootstrap()
140
+ if not ready:
141
+ logger.info(
142
+ "PyCaber bootstrap returned False; patches will be installed "
143
+ "but processing may be limited."
144
+ )
145
+
146
+ try:
147
+ import wrapt
148
+ except ImportError:
149
+ raise ImportError(
150
+ "pycaber.auto requires the 'wrapt' package. "
151
+ "Install it with: pip install pycaber[auto]"
152
+ )
153
+
154
+ def _on_requests_import(module):
155
+ if _should_patch("requests"):
156
+ from ._patches._requests import patch_requests
157
+ patch_requests(module)
158
+ logger.debug("Patched: requests.Session.send")
159
+
160
+ def _on_httpx_import(module):
161
+ if _should_patch("httpx"):
162
+ from ._patches._httpx_sync import patch_httpx_sync
163
+ from ._patches._httpx_async import patch_httpx_async
164
+ from ._registry import mark_patched
165
+ patch_httpx_sync(module)
166
+ patch_httpx_async(module)
167
+ mark_patched("httpx")
168
+ logger.debug("Patched: httpx.Client.send + AsyncClient.send")
169
+
170
+ def _on_aiohttp_import(module):
171
+ if _should_patch("aiohttp"):
172
+ from ._patches._aiohttp import patch_aiohttp, patch_aiohttp_ws
173
+ patch_aiohttp(module)
174
+ patch_aiohttp_ws(module)
175
+ logger.debug("Patched: aiohttp.ClientSession._request + ws_connect")
176
+
177
+ def _on_urllib3_import(module):
178
+ if _should_patch("urllib3"):
179
+ from ._patches._urllib3 import patch_urllib3
180
+ patch_urllib3(module)
181
+ logger.debug("Patched: urllib3.HTTPConnectionPool.urlopen")
182
+
183
+ def _on_flask_import(module):
184
+ if _should_patch("flask"):
185
+ _patch_flask(module)
186
+ logger.debug("Patched: Flask.wsgi_app via CaberWSGIMiddleware")
187
+
188
+ def _on_fastapi_import(module):
189
+ if _should_patch("fastapi"):
190
+ _patch_fastapi(module)
191
+ logger.debug("Patched: FastAPI via CaberASGIMiddleware")
192
+
193
+ def _on_websockets_import(module):
194
+ if _should_patch("websockets"):
195
+ from ._patches._websockets import patch_websockets
196
+ patch_websockets(module)
197
+ logger.debug("Patched: websockets.ClientConnection.send/recv")
198
+
199
+ def _on_websocket_import(module):
200
+ if _should_patch("websocket"):
201
+ from ._patches._websocket_client import patch_websocket_client
202
+ patch_websocket_client(module)
203
+ logger.debug("Patched: websocket.WebSocket.connect/send/recv")
204
+
205
+ def _on_tornado_ws_import(module):
206
+ if _should_patch("tornado"):
207
+ from ._patches._tornado_ws import patch_tornado_websocket
208
+ patch_tornado_websocket(module)
209
+ logger.debug("Patched: tornado.websocket.WebSocketHandler")
210
+ try:
211
+ from ._streamlit_proto import register_streamlit_resolver
212
+ register_streamlit_resolver()
213
+ except Exception:
214
+ pass
215
+
216
+ # Register deferred callbacks -- patches fire only when the library is imported
217
+ wrapt.when_imported("requests")(_on_requests_import)
218
+ wrapt.when_imported("httpx")(_on_httpx_import)
219
+ wrapt.when_imported("aiohttp")(_on_aiohttp_import)
220
+ wrapt.when_imported("urllib3")(_on_urllib3_import)
221
+ wrapt.when_imported("flask")(_on_flask_import)
222
+ wrapt.when_imported("fastapi")(_on_fastapi_import)
223
+ wrapt.when_imported("websockets")(_on_websockets_import)
224
+ wrapt.when_imported("websocket")(_on_websocket_import)
225
+ wrapt.when_imported("tornado.websocket")(_on_tornado_ws_import)
226
+
227
+
228
+ if _INSTRUMENT_DISABLED:
229
+ logger.info("CABER_AUTO_INSTRUMENT=false; no patches installed.")
230
+ else:
231
+ _install_patches()
232
+
233
+
234
+ # ---------------------------------------------------------------------------
235
+ # Public API
236
+ # ---------------------------------------------------------------------------
237
+
238
+ def uninstrument():
239
+ """Remove all Caber patches and restore original functions.
240
+
241
+ Call this to cleanly disable pycaber.auto at runtime.
242
+ """
243
+ from ._patches._requests import unpatch_requests
244
+ from ._patches._httpx_sync import unpatch_httpx_sync
245
+ from ._patches._httpx_async import unpatch_httpx_async
246
+ from ._patches._aiohttp import unpatch_aiohttp, unpatch_aiohttp_ws
247
+ from ._patches._urllib3 import unpatch_urllib3
248
+ from ._patches._websockets import unpatch_websockets
249
+ from ._patches._websocket_client import unpatch_websocket_client
250
+ from ._registry import clear_all
251
+
252
+ unpatch_requests()
253
+ unpatch_httpx_sync()
254
+ unpatch_httpx_async()
255
+ unpatch_aiohttp()
256
+ unpatch_aiohttp_ws()
257
+ unpatch_urllib3()
258
+ unpatch_websockets()
259
+ unpatch_websocket_client()
260
+ _unpatch_flask()
261
+ _unpatch_fastapi()
262
+ _unpatch_tornado()
263
+ clear_all()
264
+ logger.info("PyCaber auto-instrumentation removed")
265
+
266
+
267
+ def get_patched_modules() -> set:
268
+ """Return the set of currently patched module names."""
269
+ from ._registry import _PATCHED_MODULES
270
+ return set(_PATCHED_MODULES)
271
+
272
+
273
+ # ---------------------------------------------------------------------------
274
+ # Framework unpatch helpers
275
+ # ---------------------------------------------------------------------------
276
+
277
+ def _unpatch_flask():
278
+ try:
279
+ import flask
280
+ except ImportError:
281
+ return
282
+ from ._registry import get_original
283
+ original = get_original("flask", "Flask.__init__")
284
+ if original is not None:
285
+ flask.Flask.__init__ = original
286
+ logger.debug("Unpatched: Flask")
287
+
288
+
289
+ def _unpatch_fastapi():
290
+ try:
291
+ import fastapi
292
+ except ImportError:
293
+ return
294
+ from ._registry import get_original
295
+ original = get_original("fastapi", "FastAPI.__init__")
296
+ if original is not None:
297
+ fastapi.FastAPI.__init__ = original
298
+ logger.debug("Unpatched: FastAPI")
299
+
300
+
301
+ def _unpatch_tornado():
302
+ from ._patches._tornado_ws import unpatch_tornado_websocket
303
+ unpatch_tornado_websocket()
304
+
305
+
306
+ from ._processing import ( # noqa: E402, F401
307
+ set_redact_enabled,
308
+ reset_redact_enabled,
309
+ )
310
+
311
+ from ._state_resolvers import ( # noqa: E402, F401
312
+ register_state_resolver,
313
+ unregister_state_resolver,
314
+ ResolvedState,
315
+ )
316
+
317
+ __all__ = [
318
+ "uninstrument",
319
+ "get_patched_modules",
320
+ "CaberWSGIMiddleware",
321
+ "CaberASGIMiddleware",
322
+ "set_redact_enabled",
323
+ "reset_redact_enabled",
324
+ "register_state_resolver",
325
+ "unregister_state_resolver",
326
+ "ResolvedState",
327
+ ]