mesedi 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.
mesedi/__init__.py ADDED
@@ -0,0 +1,81 @@
1
+ """
2
+ Mesedi SDK — Guardians for Autonomous AI.
3
+
4
+ Public API:
5
+
6
+ mesedi.configure(api_key=..., base_url=...)
7
+ Configure the module-level default client.
8
+
9
+ @mesedi.wrap # bare form
10
+ @mesedi.wrap(budget=Budget(...)) # with hard-halt budget
11
+ Decorator: records a function call as an agent execution.
12
+ Optional `budget` enforces wall-clock / step / token limits
13
+ at safe boundaries; on exceedance, raises MesediHalt which
14
+ @wrap catches and converts to status=halted.
15
+
16
+ @mesedi.tool
17
+ Decorator: records a tool_call event linked to the
18
+ surrounding @mesedi.wrap execution.
19
+
20
+ mesedi.instrument_anthropic()
21
+ Patch the Anthropic SDK to auto-emit llm_call events.
22
+
23
+ mesedi.checkpoint(name, **metadata)
24
+ Mark a notable point in agent execution.
25
+
26
+ mesedi.validator_result(name, passed, message="", severity="error")
27
+ Report a validator outcome.
28
+
29
+ mesedi.Budget(max_wall_clock_seconds=..., max_steps=...,
30
+ max_tokens_in=..., max_tokens_out=...)
31
+ Hard-halt policy. Pass to @wrap to enforce local budgets.
32
+
33
+ mesedi.MesediHalt
34
+ Exception class raised when a budget is exceeded. Inherits
35
+ BaseException (not Exception) so broad `except Exception:`
36
+ handlers don't swallow it. Normally caught by @wrap itself
37
+ — user code rarely needs to see it.
38
+
39
+ mesedi.flush(timeout=5.0)
40
+ Block until the background shipper drains.
41
+
42
+ mesedi.MesediClient, mesedi.Event, mesedi.Execution,
43
+ mesedi.EventType, mesedi.Status — building blocks for advanced use.
44
+ """
45
+
46
+ from mesedi.anthropic_integration import instrument_anthropic
47
+ from mesedi.client import MesediClient, configure, flush, get_client
48
+ from mesedi.events import (
49
+ Event,
50
+ EventType,
51
+ Execution,
52
+ Status,
53
+ utcnow_rfc3339,
54
+ )
55
+ from mesedi.halt import Budget, MesediHalt
56
+ from mesedi.observe import checkpoint, emit_llm_call, validator_result
57
+ from mesedi.tool import tool
58
+ from mesedi.wrap import wrap
59
+
60
+ __version__ = "0.0.8"
61
+
62
+ __all__ = [
63
+ "Budget",
64
+ "MesediClient",
65
+ "MesediHalt",
66
+ "Event",
67
+ "EventType",
68
+ "Execution",
69
+ "Status",
70
+ "checkpoint",
71
+ "configure",
72
+ "emit_llm_call",
73
+ "flush",
74
+ "get_client",
75
+ "instrument_anthropic",
76
+ "tool",
77
+ "utcnow_rfc3339",
78
+ "validator_result",
79
+ "wrap",
80
+ "__version__",
81
+ ]
mesedi/_context.py ADDED
@@ -0,0 +1,115 @@
1
+ """
2
+ Execution-context tracking via ``contextvars``.
3
+
4
+ When ``@mesedi.wrap`` decorates a function, it sets a context variable
5
+ to identify the currently-executing run. Inside that function, any
6
+ ``@mesedi.tool``-decorated tool call reads the same variable to learn
7
+ which execution it belongs to — so tool_call events can attach to the
8
+ right Execution at the backend.
9
+
10
+ Why ``contextvars`` and not threading.local or a global dict:
11
+
12
+ - ``contextvars`` is the standard library primitive for "ambient
13
+ state that's logical-call-stack-scoped, not thread-scoped." It
14
+ behaves correctly in async code (each Task gets its own copy) and
15
+ in nested calls (set/reset returns a token, so popping a nested
16
+ context restores the outer one automatically).
17
+
18
+ - threading.local works for sync code but fails in async; we want
19
+ @wrap and @tool to work in both. asyncio support comes in a
20
+ later slice but the foundation is already async-friendly.
21
+
22
+ - A module-level dict keyed by thread_id is hand-rolled state with
23
+ none of the above guarantees.
24
+
25
+ Sequence numbering: events within an execution are numbered 1, 2, 3, …
26
+ The context object holds a monotonic counter so concurrent tool calls
27
+ within the same execution can request distinct sequence numbers
28
+ without coordinating.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ import threading
34
+ import time
35
+ from contextvars import ContextVar, Token
36
+ from dataclasses import dataclass, field
37
+ from typing import Optional
38
+
39
+ from mesedi.halt import Budget, BudgetTracker
40
+
41
+
42
+ @dataclass
43
+ class ExecutionContext:
44
+ """Per-execution scratch state shared between @wrap, @tool,
45
+ @anthropic, @checkpoint, and validator_result.
46
+
47
+ Holds the execution_id (so events know which Execution to attach
48
+ to), a sequence counter (so each emitted event gets a monotonically
49
+ increasing sequence number within the execution), and an optional
50
+ BudgetTracker for hard-halt enforcement.
51
+ """
52
+
53
+ execution_id: str
54
+ _seq_lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
55
+ _seq: int = 0
56
+ budget_tracker: Optional[BudgetTracker] = None
57
+
58
+ def next_sequence(self) -> int:
59
+ """Return the next sequence number for this execution.
60
+
61
+ Thread-safe — two tool calls fired concurrently from different
62
+ threads in the same execution still get distinct sequence
63
+ numbers.
64
+ """
65
+ with self._seq_lock:
66
+ self._seq += 1
67
+ return self._seq
68
+
69
+ def check_budget(self) -> None:
70
+ """Inspect the budget; raise MesediHalt if any limit is exceeded.
71
+
72
+ Cheap no-op if no budget was configured (or all limits are
73
+ unbounded). Called from @tool/@checkpoint/anthropic-patch at
74
+ the function-call boundary BEFORE the inner work runs, so a
75
+ halt fires at a safe checkpoint rather than mid-tool.
76
+ """
77
+ if self.budget_tracker is not None:
78
+ self.budget_tracker.check_or_halt()
79
+
80
+
81
+ _current: ContextVar[Optional[ExecutionContext]] = ContextVar(
82
+ "mesedi_current_execution",
83
+ default=None,
84
+ )
85
+
86
+
87
+ def current_execution_context() -> Optional[ExecutionContext]:
88
+ """Return the currently-active execution context, or None if outside @wrap."""
89
+ return _current.get()
90
+
91
+
92
+ def push_execution_context(
93
+ execution_id: str,
94
+ budget: Optional[Budget] = None,
95
+ ) -> Token[Optional[ExecutionContext]]:
96
+ """Set the current execution context.
97
+
98
+ Returns a token that must be passed to ``pop_execution_context()``
99
+ to restore the previous value. Nested wraps (a @wrap function
100
+ calling another @wrap function) work naturally: each call pushes,
101
+ each return pops, the outer context is restored automatically.
102
+
103
+ If `budget` is provided, a fresh BudgetTracker is attached for
104
+ halt enforcement within this execution.
105
+ """
106
+ tracker: Optional[BudgetTracker] = None
107
+ if budget is not None and not budget.is_unbounded():
108
+ tracker = BudgetTracker(budget=budget, started_at_monotonic=time.perf_counter())
109
+ ctx = ExecutionContext(execution_id=execution_id, budget_tracker=tracker)
110
+ return _current.set(ctx)
111
+
112
+
113
+ def pop_execution_context(token: Token[Optional[ExecutionContext]]) -> None:
114
+ """Restore the execution context to its prior value."""
115
+ _current.reset(token)
mesedi/_shipper.py ADDED
@@ -0,0 +1,296 @@
1
+ """
2
+ Background event shipper — async, ordered, retry-on-transient-failure.
3
+
4
+ The shipper owns a single daemon thread that pulls items from a thread-
5
+ safe queue and dispatches them to the Mesedi backend. Items come in
6
+ three flavors:
7
+
8
+ - ``create_execution``: POST /executions
9
+ - ``update_execution``: PATCH /executions/{id}
10
+ - ``event``: buffered and POSTed as a JSON array when the
11
+ batch fills or a flush interval elapses
12
+
13
+ **Ordering guarantee.** Items are processed in FIFO order. To preserve
14
+ the invariant that PATCH /executions/{id} never arrives before its
15
+ corresponding POST /executions (which would 404 on the backend), any
16
+ events pending in the batch are flushed whenever a non-event item is
17
+ about to be dispatched. This means a worst-case "fire 100 events then
18
+ a PATCH" produces 2 HTTP calls (one batched events, one PATCH); a
19
+ best-case "fire 100 events" produces 1 HTTP call.
20
+
21
+ **Retry.** Transient failures (network errors, 5xx) retry up to 3 times
22
+ with exponential backoff (0.1s, 0.5s, 2.0s). Permanent failures (4xx)
23
+ drop the item with a warning log — retrying a malformed request never
24
+ helps.
25
+
26
+ **Shutdown.** ``atexit`` registers a shutdown handler that flushes the
27
+ queue with a timeout (default 5s). Daemon thread would otherwise die
28
+ with the interpreter if the shutdown handler doesn't run (e.g., kill -9,
29
+ unhandled crash before atexit can fire) — at that point unflushed events
30
+ are lost. In normal operation, queue-to-flush latency is single-digit
31
+ milliseconds, so the loss window is small.
32
+
33
+ **Backpressure.** The queue is bounded (default 10,000 items). When
34
+ full, new submissions silently drop with a periodic warning log. Better
35
+ to drop a few events than to leak unbounded memory on a backend outage.
36
+ """
37
+
38
+ from __future__ import annotations
39
+
40
+ import atexit
41
+ import logging
42
+ import queue
43
+ import threading
44
+ import time
45
+ from dataclasses import dataclass
46
+ from typing import Any, List, Optional, Union
47
+
48
+ import httpx
49
+
50
+ from mesedi.events import Event, Execution
51
+
52
+ logger = logging.getLogger("mesedi.shipper")
53
+
54
+
55
+ @dataclass
56
+ class _Item:
57
+ """Internal envelope flowing through the shipper queue.
58
+
59
+ The ``body`` field type depends on ``kind``:
60
+ - ``create_execution`` / ``update_execution`` → Execution
61
+ - ``event`` → Event
62
+ - ``barrier`` → threading.Event (signaled when the shipper has
63
+ drained everything queued before this item; used by flush())
64
+ """
65
+
66
+ kind: str
67
+ body: Any # Execution | Event | threading.Event
68
+
69
+
70
+ class EventShipper:
71
+ """Background async shipper for backend events and executions.
72
+
73
+ One shipper per MesediClient. Owns one daemon thread. Thread-safe
74
+ for concurrent ``submit_*()`` calls from any number of producer
75
+ threads.
76
+ """
77
+
78
+ def __init__(
79
+ self,
80
+ http: httpx.Client,
81
+ flush_interval_ms: int = 250,
82
+ batch_size: int = 100,
83
+ max_queue: int = 10_000,
84
+ max_retries: int = 3,
85
+ ):
86
+ self._http = http
87
+ self._flush_interval = flush_interval_ms / 1000.0
88
+ self._batch_size = batch_size
89
+ self._max_queue = max_queue
90
+ self._max_retries = max_retries
91
+
92
+ self._queue: "queue.Queue[_Item]" = queue.Queue(maxsize=max_queue)
93
+ self._stop = threading.Event()
94
+ self._dropped_count = 0 # for diagnostics
95
+
96
+ self._thread = threading.Thread(
97
+ target=self._run,
98
+ name="mesedi-shipper",
99
+ daemon=True,
100
+ )
101
+ self._thread.start()
102
+ atexit.register(self.shutdown)
103
+
104
+ # ── producer-side API ────────────────────────────────────────────
105
+
106
+ def submit_execution_start(self, execution: Execution) -> None:
107
+ self._submit(_Item(kind="create_execution", body=execution))
108
+
109
+ def submit_execution_end(self, execution: Execution) -> None:
110
+ self._submit(_Item(kind="update_execution", body=execution))
111
+
112
+ def submit_event(self, event: Event) -> None:
113
+ self._submit(_Item(kind="event", body=event))
114
+
115
+ def _submit(self, item: _Item) -> None:
116
+ try:
117
+ self._queue.put_nowait(item)
118
+ except queue.Full:
119
+ self._dropped_count += 1
120
+ # Log only the first drop and every 100th drop afterward, to
121
+ # avoid log-spam under sustained pressure.
122
+ if self._dropped_count == 1 or self._dropped_count % 100 == 0:
123
+ logger.warning(
124
+ "mesedi: shipper queue full, dropped %d items so far",
125
+ self._dropped_count,
126
+ )
127
+
128
+ def flush(self, timeout: float = 5.0) -> bool:
129
+ """Block until the shipper has drained everything queued so far.
130
+
131
+ Inserts a barrier item; returns True if the barrier was reached
132
+ within ``timeout`` seconds, False otherwise. Useful in tests and
133
+ before-exit synchronization where you want to ensure events have
134
+ actually landed at the backend before the caller proceeds.
135
+ """
136
+ signal = threading.Event()
137
+ try:
138
+ self._queue.put_nowait(_Item(kind="barrier", body=signal))
139
+ except queue.Full:
140
+ return False
141
+ return signal.wait(timeout=timeout)
142
+
143
+ # ── shutdown ──────────────────────────────────────────────────────
144
+
145
+ def shutdown(self, timeout: float = 5.0) -> None:
146
+ """Stop the worker thread; flush remaining items with timeout.
147
+
148
+ Safe to call multiple times. Registered with ``atexit`` at
149
+ construction time, so an explicit call is normally unnecessary —
150
+ but explicit ``client.close()`` will trigger this immediately
151
+ rather than waiting for interpreter shutdown.
152
+ """
153
+ if self._stop.is_set():
154
+ return
155
+ self._stop.set()
156
+ # The worker may be blocked on queue.get() with a timeout up to
157
+ # flush_interval; just join() with a generous timeout and let
158
+ # the daemon-thread fallback handle the unlikely case where the
159
+ # worker is stuck mid-retry on a slow backend.
160
+ self._thread.join(timeout=timeout)
161
+
162
+ # ── worker thread ─────────────────────────────────────────────────
163
+
164
+ def _run(self) -> None:
165
+ """Main loop: drain queue, batch events, dispatch."""
166
+ pending_events: List[Event] = []
167
+ last_flush = time.monotonic()
168
+
169
+ while True:
170
+ # Termination condition: stop flag is set AND queue is empty.
171
+ # We do NOT stop the instant stop_set is true — we keep
172
+ # draining whatever is already queued, so an explicit
173
+ # shutdown() doesn't drop in-flight work.
174
+ if self._stop.is_set() and self._queue.empty():
175
+ break
176
+
177
+ timeout = max(
178
+ 0.0,
179
+ self._flush_interval - (time.monotonic() - last_flush),
180
+ )
181
+ try:
182
+ item = self._queue.get(timeout=timeout)
183
+ except queue.Empty:
184
+ # Time-based flush window elapsed; flush any pending events.
185
+ if pending_events:
186
+ self._send_events(pending_events)
187
+ pending_events = []
188
+ last_flush = time.monotonic()
189
+ continue
190
+
191
+ if item.kind == "event":
192
+ assert isinstance(item.body, Event)
193
+ pending_events.append(item.body)
194
+ if len(pending_events) >= self._batch_size:
195
+ self._send_events(pending_events)
196
+ pending_events = []
197
+ last_flush = time.monotonic()
198
+ elif item.kind == "barrier":
199
+ # Flush any pending events FIRST so the barrier represents
200
+ # "everything submitted before me is done".
201
+ if pending_events:
202
+ self._send_events(pending_events)
203
+ pending_events = []
204
+ last_flush = time.monotonic()
205
+ assert isinstance(item.body, threading.Event)
206
+ item.body.set()
207
+ else:
208
+ # Non-event item — flush pending events FIRST to preserve
209
+ # ordering (a PATCH must not arrive before its preceding
210
+ # events for the same execution).
211
+ if pending_events:
212
+ self._send_events(pending_events)
213
+ pending_events = []
214
+ last_flush = time.monotonic()
215
+
216
+ assert isinstance(item.body, Execution)
217
+ if item.kind == "create_execution":
218
+ self._send_create_execution(item.body)
219
+ elif item.kind == "update_execution":
220
+ self._send_update_execution(item.body)
221
+ else:
222
+ logger.warning("mesedi: unknown item kind %r", item.kind)
223
+
224
+ # Final flush on shutdown.
225
+ if pending_events:
226
+ self._send_events(pending_events)
227
+
228
+ # ── dispatchers with retry ────────────────────────────────────────
229
+
230
+ def _send_create_execution(self, execution: Execution) -> None:
231
+ self._send_with_retry(
232
+ method="POST",
233
+ url="/executions",
234
+ json_body=execution.start_payload(),
235
+ description=f"create_execution {execution.execution_id}",
236
+ )
237
+
238
+ def _send_update_execution(self, execution: Execution) -> None:
239
+ self._send_with_retry(
240
+ method="PATCH",
241
+ url=f"/executions/{execution.execution_id}",
242
+ json_body=execution.end_payload(),
243
+ description=f"update_execution {execution.execution_id}",
244
+ )
245
+
246
+ def _send_events(self, events: List[Event]) -> None:
247
+ body = [e.to_dict() for e in events]
248
+ self._send_with_retry(
249
+ method="POST",
250
+ url="/events",
251
+ json_body=body,
252
+ description=f"send_events batch of {len(events)}",
253
+ )
254
+
255
+ def _send_with_retry(
256
+ self,
257
+ method: str,
258
+ url: str,
259
+ json_body: Any,
260
+ description: str,
261
+ ) -> None:
262
+ """Issue one HTTP call with up-to-3 retries on transient failure.
263
+
264
+ Returns silently on success or on permanent failure (4xx); logs
265
+ a warning on permanent failure or exhausted retries.
266
+ """
267
+ backoffs = [0.1, 0.5, 2.0]
268
+ last_err: Any = None
269
+ for attempt in range(self._max_retries + 1):
270
+ try:
271
+ r = self._http.request(method, url, json=json_body)
272
+ if r.status_code < 400:
273
+ return # success
274
+ if 400 <= r.status_code < 500:
275
+ # Permanent failure: retrying won't help.
276
+ logger.warning(
277
+ "mesedi: %s rejected with %d: %s",
278
+ description,
279
+ r.status_code,
280
+ r.text[:200],
281
+ )
282
+ return
283
+ # 5xx — transient, retry.
284
+ last_err = f"HTTP {r.status_code}"
285
+ except Exception as exc:
286
+ last_err = exc
287
+
288
+ if attempt < self._max_retries:
289
+ time.sleep(backoffs[attempt])
290
+
291
+ logger.warning(
292
+ "mesedi: %s failed after %d attempts: %s",
293
+ description,
294
+ self._max_retries + 1,
295
+ last_err,
296
+ )