mesedi 0.1.0__tar.gz

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.
@@ -0,0 +1,52 @@
1
+ # Build artifacts
2
+ *.exe
3
+ *.dll
4
+ *.so
5
+ *.dylib
6
+
7
+ # Go
8
+ backend/mesedi-dev.db
9
+ backend/mesedi-dev.db-*
10
+ backend/*.test
11
+ backend/coverage.out
12
+
13
+ # Editor / OS
14
+ .DS_Store
15
+ .idea/
16
+ .vscode/
17
+ *.swp
18
+
19
+ # Env
20
+ .env
21
+ .env.local
22
+ backend/.env
23
+
24
+ # Future subdirs
25
+ sdk-python/__pycache__/
26
+ sdk-python/.venv/
27
+ sdk-python/dist/
28
+ sdk-python/*.egg-info/
29
+ sdk-typescript/node_modules/
30
+ sdk-typescript/dist/
31
+ sdk-typescript/dist-sandbox/
32
+ dashboard/node_modules/
33
+ dashboard/.next/
34
+
35
+ # Nested __pycache__ caches (any package directory)
36
+ **/__pycache__/
37
+
38
+ # In-place sed backup files
39
+ *.bak
40
+
41
+ # Synthetic-org local runtime state
42
+ synthetic-org/.venv/
43
+ synthetic-org/session-*.json
44
+ synthetic-org/continuous_traffic.log
45
+ synthetic-org/continuous_traffic.log.*
46
+
47
+ # Internal-only docs — pricing strategy, roadmap timelines,
48
+ # competitive notes. Never commit these to a public repo.
49
+ ROADMAP.md
50
+ NOTES.md
51
+ PRICING.md
52
+ INTERNAL_*.md
mesedi-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Robert J. Canario
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
mesedi-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,169 @@
1
+ Metadata-Version: 2.4
2
+ Name: mesedi
3
+ Version: 0.1.0
4
+ Summary: Mesedi SDK — guardians for autonomous AI agents. Detect failures, halt runaways, escalate first occurrence.
5
+ Project-URL: Homepage, https://mesedi.ai
6
+ Project-URL: Repository, https://github.com/mesedi-ai/mesedi
7
+ Project-URL: Issues, https://github.com/mesedi-ai/mesedi/issues
8
+ Project-URL: Documentation, https://github.com/mesedi-ai/mesedi/tree/main/sdk-python#readme
9
+ Author-email: "Robert J. Canario" <mesediai@gmail.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agent-monitoring,agents,ai,anthropic,crewai,langchain,llm,mesedi,observability,openai
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Requires-Python: >=3.9
24
+ Requires-Dist: httpx>=0.24
25
+ Provides-Extra: crewai
26
+ Requires-Dist: crewai>=0.30; extra == 'crewai'
27
+ Provides-Extra: dev
28
+ Requires-Dist: mypy>=1.0; extra == 'dev'
29
+ Requires-Dist: pytest>=7.0; extra == 'dev'
30
+ Provides-Extra: langchain
31
+ Requires-Dist: langchain-core>=0.1; extra == 'langchain'
32
+ Description-Content-Type: text/markdown
33
+
34
+ # Mesedi Python SDK
35
+
36
+ **Status:** Phase 2 alpha (v0.0.1). Local-only development; not yet on PyPI.
37
+
38
+ The Mesedi SDK observes autonomous AI agent runs and ships them to the Mesedi
39
+ backend for detection and analysis. Today's surface is intentionally tiny:
40
+
41
+ - `mesedi.configure(api_key=...)` — set up the module-level client
42
+ - `@mesedi.wrap` — decorate any function as an "agent execution"; the SDK
43
+ records start, completion (or crash), wall-clock duration, and a stable
44
+ crash signature suitable for grouping identical exceptions.
45
+
46
+ The `@tool` decorator, Anthropic SDK monkey-patch, async event buffer, and
47
+ PyPI release land in later sub-slices.
48
+
49
+ ## Quickstart (local development)
50
+
51
+ Prerequisites: Mesedi backend running on `localhost:8080` with the bootstrap
52
+ dev project. See `../backend/README.md` if not yet running.
53
+
54
+ ```bash
55
+ cd ~/mesedi/sdk-python
56
+ python3 -m pip install -e .
57
+
58
+ cd sandbox
59
+ python3 real_agent.py
60
+ ```
61
+
62
+ Or use it programmatically:
63
+
64
+ ```python
65
+ import mesedi
66
+
67
+ mesedi.configure(
68
+ api_key="mesedi_sk_dev_local_only",
69
+ base_url="http://localhost:8080",
70
+ )
71
+
72
+ @mesedi.wrap
73
+ def run_my_agent(query: str) -> str:
74
+ # ... your agent logic here ...
75
+ return "answer"
76
+
77
+ run_my_agent("hello")
78
+ ```
79
+
80
+ ## What lands in the backend
81
+
82
+ For each `@wrap`-decorated call:
83
+
84
+ - **On entry:** `POST /executions` with `execution_id`, `status="started"`,
85
+ `sdk_language="python"`, `sdk_version="0.0.1"`.
86
+ - **On normal return:** `PATCH /executions/{id}` with `status="completed"`,
87
+ `ended_at`, `duration_ms`.
88
+ - **On exception:** `PATCH /executions/{id}` with `status="crashed"`,
89
+ `crash_signature` (SHA-256-derived stable hash of exception type + top
90
+ of traceback), then the original exception is re-raised.
91
+
92
+ Network failures during observation NEVER block the wrapped function. The
93
+ SDK is fail-open: a Mesedi outage degrades to invisibility, not to broken
94
+ production code.
95
+
96
+ ## Framework integrations
97
+
98
+ If your agent is built on LangChain or CrewAI, you don't have to wrap every
99
+ function with `@mesedi.tool` by hand. Adapter modules under
100
+ `mesedi.integrations.*` translate each framework's native callback or hook
101
+ surface into Mesedi telemetry. They're **optional**: importing `mesedi`
102
+ itself never requires any framework to be installed.
103
+
104
+ The pattern is the same across frameworks: your function gets `@mesedi.wrap`
105
+ for the execution boundary, and a one-line adapter does the in-execution
106
+ event emission.
107
+
108
+ ### LangChain
109
+
110
+ ```bash
111
+ pip install mesedi[langchain]
112
+ ```
113
+
114
+ ```python
115
+ import mesedi
116
+ from mesedi.integrations.langchain import MesediCallbackHandler
117
+
118
+ @mesedi.wrap
119
+ def run_agent(question: str) -> str:
120
+ chain = build_chain()
121
+ result = chain.invoke(
122
+ {"input": question},
123
+ config={"callbacks": [MesediCallbackHandler()]},
124
+ )
125
+ return result["output"]
126
+ ```
127
+
128
+ The callback handler subscribes to LangChain's standard `on_llm_start` /
129
+ `on_llm_end` / `on_tool_start` / `on_tool_end` (etc.) hooks and emits
130
+ `llm_call` and `tool_call` events with the same wire format as a
131
+ hand-written `mesedi.emit_llm_call()` + `@mesedi.tool` pair. Detectors —
132
+ drift, identical / similar-call loops, tool-failures, cost-velocity,
133
+ prompt-injection — see no difference.
134
+
135
+ ### CrewAI
136
+
137
+ ```bash
138
+ pip install mesedi[crewai]
139
+ ```
140
+
141
+ ```python
142
+ import mesedi
143
+ from mesedi.integrations.crewai import instrument_crew
144
+
145
+ @mesedi.wrap
146
+ def run_my_crew(question: str) -> str:
147
+ crew = build_crew()
148
+ instrument_crew(crew)
149
+ return str(crew.kickoff(inputs={"question": question}))
150
+ ```
151
+
152
+ `instrument_crew` is one line that does three things, all idempotent:
153
+
154
+ 1. Attaches a Mesedi `MesediCallbackHandler` to each agent's LLM — same
155
+ LLM/tool telemetry as the LangChain integration above, because CrewAI
156
+ uses LangChain under the hood.
157
+ 2. Sets `crew.step_callback` to emit `crewai.agent_action` /
158
+ `crewai.agent_finish` checkpoint events per agent step.
159
+ 3. Sets `crew.task_callback` to emit `crewai.task_completed` checkpoint
160
+ events per finished task.
161
+
162
+ Result: the dashboard timeline shows LLM/tool detail interleaved with
163
+ CrewAI's higher-level reasoning rhythm.
164
+
165
+ ## Posture
166
+
167
+ This SDK ships from the same monorepo as the backend during the local-only
168
+ development window. PyPI publication via Trusted Publishing (PEP 740) is
169
+ deferred to the post-LOI sequence in `../docs/DEVELOPMENT_CHECKLIST.md`.
mesedi-0.1.0/README.md ADDED
@@ -0,0 +1,136 @@
1
+ # Mesedi Python SDK
2
+
3
+ **Status:** Phase 2 alpha (v0.0.1). Local-only development; not yet on PyPI.
4
+
5
+ The Mesedi SDK observes autonomous AI agent runs and ships them to the Mesedi
6
+ backend for detection and analysis. Today's surface is intentionally tiny:
7
+
8
+ - `mesedi.configure(api_key=...)` — set up the module-level client
9
+ - `@mesedi.wrap` — decorate any function as an "agent execution"; the SDK
10
+ records start, completion (or crash), wall-clock duration, and a stable
11
+ crash signature suitable for grouping identical exceptions.
12
+
13
+ The `@tool` decorator, Anthropic SDK monkey-patch, async event buffer, and
14
+ PyPI release land in later sub-slices.
15
+
16
+ ## Quickstart (local development)
17
+
18
+ Prerequisites: Mesedi backend running on `localhost:8080` with the bootstrap
19
+ dev project. See `../backend/README.md` if not yet running.
20
+
21
+ ```bash
22
+ cd ~/mesedi/sdk-python
23
+ python3 -m pip install -e .
24
+
25
+ cd sandbox
26
+ python3 real_agent.py
27
+ ```
28
+
29
+ Or use it programmatically:
30
+
31
+ ```python
32
+ import mesedi
33
+
34
+ mesedi.configure(
35
+ api_key="mesedi_sk_dev_local_only",
36
+ base_url="http://localhost:8080",
37
+ )
38
+
39
+ @mesedi.wrap
40
+ def run_my_agent(query: str) -> str:
41
+ # ... your agent logic here ...
42
+ return "answer"
43
+
44
+ run_my_agent("hello")
45
+ ```
46
+
47
+ ## What lands in the backend
48
+
49
+ For each `@wrap`-decorated call:
50
+
51
+ - **On entry:** `POST /executions` with `execution_id`, `status="started"`,
52
+ `sdk_language="python"`, `sdk_version="0.0.1"`.
53
+ - **On normal return:** `PATCH /executions/{id}` with `status="completed"`,
54
+ `ended_at`, `duration_ms`.
55
+ - **On exception:** `PATCH /executions/{id}` with `status="crashed"`,
56
+ `crash_signature` (SHA-256-derived stable hash of exception type + top
57
+ of traceback), then the original exception is re-raised.
58
+
59
+ Network failures during observation NEVER block the wrapped function. The
60
+ SDK is fail-open: a Mesedi outage degrades to invisibility, not to broken
61
+ production code.
62
+
63
+ ## Framework integrations
64
+
65
+ If your agent is built on LangChain or CrewAI, you don't have to wrap every
66
+ function with `@mesedi.tool` by hand. Adapter modules under
67
+ `mesedi.integrations.*` translate each framework's native callback or hook
68
+ surface into Mesedi telemetry. They're **optional**: importing `mesedi`
69
+ itself never requires any framework to be installed.
70
+
71
+ The pattern is the same across frameworks: your function gets `@mesedi.wrap`
72
+ for the execution boundary, and a one-line adapter does the in-execution
73
+ event emission.
74
+
75
+ ### LangChain
76
+
77
+ ```bash
78
+ pip install mesedi[langchain]
79
+ ```
80
+
81
+ ```python
82
+ import mesedi
83
+ from mesedi.integrations.langchain import MesediCallbackHandler
84
+
85
+ @mesedi.wrap
86
+ def run_agent(question: str) -> str:
87
+ chain = build_chain()
88
+ result = chain.invoke(
89
+ {"input": question},
90
+ config={"callbacks": [MesediCallbackHandler()]},
91
+ )
92
+ return result["output"]
93
+ ```
94
+
95
+ The callback handler subscribes to LangChain's standard `on_llm_start` /
96
+ `on_llm_end` / `on_tool_start` / `on_tool_end` (etc.) hooks and emits
97
+ `llm_call` and `tool_call` events with the same wire format as a
98
+ hand-written `mesedi.emit_llm_call()` + `@mesedi.tool` pair. Detectors —
99
+ drift, identical / similar-call loops, tool-failures, cost-velocity,
100
+ prompt-injection — see no difference.
101
+
102
+ ### CrewAI
103
+
104
+ ```bash
105
+ pip install mesedi[crewai]
106
+ ```
107
+
108
+ ```python
109
+ import mesedi
110
+ from mesedi.integrations.crewai import instrument_crew
111
+
112
+ @mesedi.wrap
113
+ def run_my_crew(question: str) -> str:
114
+ crew = build_crew()
115
+ instrument_crew(crew)
116
+ return str(crew.kickoff(inputs={"question": question}))
117
+ ```
118
+
119
+ `instrument_crew` is one line that does three things, all idempotent:
120
+
121
+ 1. Attaches a Mesedi `MesediCallbackHandler` to each agent's LLM — same
122
+ LLM/tool telemetry as the LangChain integration above, because CrewAI
123
+ uses LangChain under the hood.
124
+ 2. Sets `crew.step_callback` to emit `crewai.agent_action` /
125
+ `crewai.agent_finish` checkpoint events per agent step.
126
+ 3. Sets `crew.task_callback` to emit `crewai.task_completed` checkpoint
127
+ events per finished task.
128
+
129
+ Result: the dashboard timeline shows LLM/tool detail interleaved with
130
+ CrewAI's higher-level reasoning rhythm.
131
+
132
+ ## Posture
133
+
134
+ This SDK ships from the same monorepo as the backend during the local-only
135
+ development window. PyPI publication via Trusted Publishing (PEP 740) is
136
+ deferred to the post-LOI sequence in `../docs/DEVELOPMENT_CHECKLIST.md`.
@@ -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
+ ]
@@ -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)