agent-snr 0.1.1__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.
Files changed (37) hide show
  1. agent_snr-0.1.1/LICENSE +17 -0
  2. agent_snr-0.1.1/PKG-INFO +288 -0
  3. agent_snr-0.1.1/README.md +247 -0
  4. agent_snr-0.1.1/pyproject.toml +106 -0
  5. agent_snr-0.1.1/setup.cfg +4 -0
  6. agent_snr-0.1.1/src/agent_snr/__init__.py +60 -0
  7. agent_snr-0.1.1/src/agent_snr/adapters/__init__.py +12 -0
  8. agent_snr-0.1.1/src/agent_snr/adapters/crewai.py +147 -0
  9. agent_snr-0.1.1/src/agent_snr/adapters/langgraph.py +293 -0
  10. agent_snr-0.1.1/src/agent_snr/adapters/openai.py +241 -0
  11. agent_snr-0.1.1/src/agent_snr/cli.py +282 -0
  12. agent_snr-0.1.1/src/agent_snr/core/__init__.py +39 -0
  13. agent_snr-0.1.1/src/agent_snr/core/embedder.py +224 -0
  14. agent_snr-0.1.1/src/agent_snr/core/firewall.py +234 -0
  15. agent_snr-0.1.1/src/agent_snr/core/frames.py +231 -0
  16. agent_snr-0.1.1/src/agent_snr/core/telemetry.py +490 -0
  17. agent_snr-0.1.1/src/agent_snr/modules/__init__.py +14 -0
  18. agent_snr-0.1.1/src/agent_snr/modules/budgeter.py +118 -0
  19. agent_snr-0.1.1/src/agent_snr/modules/compactor.py +226 -0
  20. agent_snr-0.1.1/src/agent_snr/modules/entropy.py +141 -0
  21. agent_snr-0.1.1/src/agent_snr/modules/router.py +101 -0
  22. agent_snr-0.1.1/src/agent_snr/py.typed +0 -0
  23. agent_snr-0.1.1/src/agent_snr.egg-info/PKG-INFO +288 -0
  24. agent_snr-0.1.1/src/agent_snr.egg-info/SOURCES.txt +35 -0
  25. agent_snr-0.1.1/src/agent_snr.egg-info/dependency_links.txt +1 -0
  26. agent_snr-0.1.1/src/agent_snr.egg-info/entry_points.txt +2 -0
  27. agent_snr-0.1.1/src/agent_snr.egg-info/requires.txt +15 -0
  28. agent_snr-0.1.1/src/agent_snr.egg-info/top_level.txt +1 -0
  29. agent_snr-0.1.1/tests/test_adapters.py +410 -0
  30. agent_snr-0.1.1/tests/test_benchmarks.py +111 -0
  31. agent_snr-0.1.1/tests/test_budgeter.py +200 -0
  32. agent_snr-0.1.1/tests/test_compactor.py +238 -0
  33. agent_snr-0.1.1/tests/test_entropy.py +256 -0
  34. agent_snr-0.1.1/tests/test_firewall.py +190 -0
  35. agent_snr-0.1.1/tests/test_frames.py +456 -0
  36. agent_snr-0.1.1/tests/test_router.py +164 -0
  37. agent_snr-0.1.1/tests/test_telemetry.py +422 -0
@@ -0,0 +1,17 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ Copyright 2026 Agent SNR Contributors
6
+
7
+ Licensed under the Apache License, Version 2.0 (the "License");
8
+ you may not use this file except in compliance with the License.
9
+ You may obtain a copy of the License at
10
+
11
+ http://www.apache.org/licenses/LICENSE-2.0
12
+
13
+ Unless required by applicable law or agreed to in writing, software
14
+ distributed under the License is distributed on an "AS IS" BASIS,
15
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
+ See the License for the specific language governing permissions and
17
+ limitations under the License.
@@ -0,0 +1,288 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-snr
3
+ Version: 0.1.1
4
+ Summary: An L4/L5 Signal Firewall for AI Agents: context compression, loop entropy circuit breaking, attention budgeting, and skip-level routing.
5
+ Author: Sandeep Hipparagi
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/Sandeep-Hipparagi/agent-snr
8
+ Project-URL: Documentation, https://github.com/Sandeep-Hipparagi/agent-snr#readme
9
+ Project-URL: Repository, https://github.com/Sandeep-Hipparagi/agent-snr
10
+ Project-URL: Issues, https://github.com/Sandeep-Hipparagi/agent-snr/issues
11
+ Project-URL: Changelog, https://github.com/Sandeep-Hipparagi/agent-snr/releases
12
+ Keywords: agents,firewall,llm,snr,signal-to-noise,compression,langgraph,crewai,circuit-breaker,entropy,routing
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: License :: OSI Approved :: Apache Software License
17
+ Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Requires-Python: >=3.10
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: numpy
29
+ Requires-Dist: pydantic>=2.0
30
+ Requires-Dist: rich
31
+ Provides-Extra: embeddings
32
+ Requires-Dist: fastembed>=0.3.0; extra == "embeddings"
33
+ Provides-Extra: langgraph
34
+ Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
35
+ Provides-Extra: dev
36
+ Requires-Dist: pytest; extra == "dev"
37
+ Requires-Dist: pytest-asyncio; extra == "dev"
38
+ Requires-Dist: ruff; extra == "dev"
39
+ Requires-Dist: mypy; extra == "dev"
40
+ Dynamic: license-file
41
+
42
+ # agent-snr: The Agent Signal Firewall
43
+
44
+ [![CI](https://github.com/Sandeep-Hipparagi/agent-snr/actions/workflows/ci.yml/badge.svg)](https://github.com/Sandeep-Hipparagi/agent-snr/actions/workflows/ci.yml)
45
+ [![PyPI version](https://img.shields.io/pypi/v/agent-snr.svg)](https://pypi.org/project/agent-snr/)
46
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/agent-snr/)
47
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
48
+ [![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
49
+ [![Type Checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)
50
+
51
+ > **An L4/L5 Signal Firewall for AI Agents**: *Treat agent memory and graph states like a high-efficiency organization.*
52
+
53
+ `agent-snr` is an ultra-fast, zero-lock-in Python firewall that sits between your agent loops and upstream LLM providers (OpenAI, Anthropic, LiteLLM, LangGraph, CrewAI). It continuously computes the **Signal-to-Noise Ratio (SNR)** of every message, prunes bloated metadata, detects non-convergent retry loops and silent goal drift, and dynamically bypasses unnecessary DAG critique hops.
54
+
55
+ ---
56
+
57
+ ## The Problem: Corporate Bureaucracy in Multi-Agent Graphs
58
+
59
+ As autonomous agent workflows scale beyond 5–10 steps, they invariably fall victim to three computational bottlenecks:
60
+
61
+ 1. **Context Rot & Token Bloat**: Multi-step tool calls return 15KB–40KB of nested JSON metadata (`request_id`, `trace_id`, `_links`, null headers) and repetitive 40-line `site-packages` Python stack traces. As context accumulates, tokens grow quadratically ($O(N^2)$), degrading LLM reasoning and inflating cost.
62
+ 2. **Silent Retry Loops & Goal Drift**: When an agent hits an error, it often enters a loop—mutating query keywords slightly or bouncing the unresolved sub-task back and forth between `Planner` and `Executor` while appearing "busy". Alternatively, reasoning subtly drifts away from the user's root goal over successive turns.
63
+ 3. **Unnecessary Hierarchical Hops**: Static agent graphs enforce rigid review cycles (e.g. `Researcher` $\rightarrow$ `ManagerReviewer` $\rightarrow$ `FinalSynthesizer`) even when early nodes produce unambiguous, schema-validated outputs with high confidence.
64
+
65
+ `agent-snr` solves this with an in-memory, deterministic **Signal Firewall** adding **$< 1.5\text{ ms}$ overhead** per step.
66
+
67
+ ---
68
+
69
+ ## Architecture
70
+
71
+ ```mermaid
72
+ flowchart LR
73
+ A["Raw Agent Messages\n(Tools, Prompts, History)"] --> B["StateCompactor\n(SNR Scoring & Pruning)"]
74
+ B --> C["LoopEntropyDetector\n(Shannon H & Goal Drift)"]
75
+ C -->|Loop / Drift| CB["🚨 Circuit Breaker\n(SNRCircuitBreakError)"]
76
+ C -->|Warning| IC["⚠️ Inject Correction\n(Nudge Prompt)"]
77
+ C -->|Healthy| D["DynamicAttentionBudgeter\n(Knapsack Utility Packing)"]
78
+ D --> E["SkipLevelRouter\n(Schema & SNR Bypass)"]
79
+ E --> F["Optimized Context Window\n(to LLM Provider)"]
80
+ ```
81
+
82
+ 1. **`StateCompactor`**: Computes lexical and semantic novelty scores. Prunes noise keys, collapses whitespace, folds repetitive internal tracebacks, and deduplicates idempotent tool reads.
83
+ 2. **`LoopEntropyDetector`**: Tracks discrete action entropy ($H_{\text{discrete}}$) and semantic stagnation ($S_t$) across trailing execution frames, combined with EMA Goal Drift ($D_t$) against initial user intents.
84
+ 3. **`DynamicAttentionBudgeter`**: Knapsack utility density allocation that preserves pinned constraints (system prompt, root goal) and recency windows while respecting strict token ceilings.
85
+ 4. **`SkipLevelRouter`**: Dynamically evaluates intermediate outputs against Pydantic schemas and SNR thresholds, bypassing redundant evaluation hops.
86
+
87
+ ---
88
+
89
+ ## Empirical Benchmark Results
90
+
91
+ Measured across **50 trials per scenario** (`seed=42`) comparing unprotected baseline execution against `AgentSNRFirewall`. Reproduced via [`benchmarks/run_all.py`](benchmarks/run_all.py).
92
+
93
+ ### 1. Adversarial Loop & Context Bloat Stress Suite
94
+
95
+ | Scenario | Baseline Tokens | SNR Tokens | Token Reduction | Baseline Steps | SNR Steps | Loop Intercept Rate | False Positive Break Rate |
96
+ |:---|---:|---:|---:|---:|---:|---:|---:|
97
+ | **Argument-Mutation Tool Retry Loop** | 24,950 | 242 | **99.0%** | 25.0 | 3.0 | **100.0%** | 0.0% |
98
+ | **Ping-Pong Multi-Agent Delegation Loop** | 12,674 | 417 | **96.7%** | 25.0 | 5.0 | **100.0%** | 0.0% |
99
+ | **Bloated JSON & Stack-Trace Explosion** | 119,900 | 15,148 | **87.4%** | 10.0 | 10.0 | *N/A (Bloat)* | 0.0% |
100
+ | **Silent Semantic Goal Drift** | 4,186 | 166 | **96.0%** | 12.0 | 3.0 | **100.0%** | 0.0% |
101
+ | **Control Group (Valid SE Workflow)** | 2,963 | 2,165 | **26.9%** | 11.0 | 11.0 | *N/A (Valid)* | **0.0%** |
102
+ | **Overall Stress Benchmark Average** | **8,234,700** | **906,900** | **89.0%** | — | — | **100.0%** | **0.0%** |
103
+
104
+ ### 2. Trajectory Replay A/B Evaluation (20 Representative Workflows)
105
+
106
+ Replayed across 20 representative real-world workflows (coding, API orchestration, research):
107
+
108
+ | Metric | Baseline Agent | AgentSNRFirewall | Optimization Impact |
109
+ |:---|---:|---:|:---|
110
+ | **Total Prompt Tokens Consumed** | 25,305 | 19,376 | **-23.4% prompt tokens** |
111
+ | **Mean Peak Context Window** | 317.5 tokens | 216.5 tokens | **-31.8% peak window** |
112
+ | **LLM Hops Saved via SkipLevelRouter** | 0 hops (0.0%) | 20 / 20 hops | **100.0% eligible skips saved** |
113
+ | **Critical Fact Retention Recall** | 100.0% | 100.0% | **Zero constraint amnesia** |
114
+ | **Per-Step Firewall Latency Overhead** | 0.00 ms | **p50: 0.76 ms \| p95: 1.43 ms** | **Sub-10ms latency confirmed** |
115
+
116
+ To reproduce these numbers locally:
117
+ ```bash
118
+ python benchmarks/run_all.py --trials 50
119
+ ```
120
+
121
+ ---
122
+
123
+ ## Installation
124
+
125
+ ```bash
126
+ # Core package (zero ML model dependencies out of the box)
127
+ pip install agent-snr
128
+
129
+ # Optional fast on-device semantic embeddings (fastembed + BGE)
130
+ pip install "agent-snr[embeddings]"
131
+
132
+ # Optional LangGraph extras
133
+ pip install "agent-snr[langgraph]"
134
+ ```
135
+
136
+ ---
137
+
138
+ ## Quickstart Integrations
139
+
140
+ ### 1. Read-Only Telemetry Audit (`dry_run=True` / CLI)
141
+
142
+ Profile token waste and loop occurrences in your existing agent without altering outputs:
143
+
144
+ ```bash
145
+ # Run the interactive CLI diagnostic demo
146
+ agent-snr demo
147
+ ```
148
+
149
+ In Python:
150
+ ```python
151
+ from agent_snr import AgentSNRFirewall
152
+
153
+ # Profile in dry-run mode
154
+ firewall = AgentSNRFirewall(dry_run=True)
155
+ optimized_msgs, action, metrics = firewall.process_outbound(
156
+ session_id="audit_01",
157
+ node_id="researcher",
158
+ messages=messages,
159
+ )
160
+
161
+ # Print rich diagnostic telemetry summary
162
+ firewall.profiler.print_report()
163
+ ```
164
+
165
+ ### 2. OpenAI & LiteLLM Drop-In Wrapper
166
+
167
+ Wrap any sync or async OpenAI-compatible client. `agent-snr` automatically intercepts outbound payloads, prunes noise, and enforces circuit breakers:
168
+
169
+ ```python
170
+ from openai import OpenAI
171
+ from agent_snr import SNRWrappedOpenAI
172
+
173
+ # Wrap native OpenAI client
174
+ client = SNRWrappedOpenAI(OpenAI(), session_id="user_session_42")
175
+
176
+ response = client.chat.completions.create(
177
+ model="gpt-4o",
178
+ messages=[
179
+ {"role": "user", "content": "Analyze system performance"},
180
+ {"role": "tool_result", "content": bloated_json_string},
181
+ ],
182
+ snr_node_id="analyst", # optional node tag for trajectory tracking
183
+ )
184
+
185
+ # Access diagnostic profiler metrics
186
+ client.profiler.print_report()
187
+ ```
188
+
189
+ ### 3. LangGraph Node Guard & Skip-Level Router
190
+
191
+ Protect LangGraph nodes from bloat and bypass intermediate critique nodes when output meets schema:
192
+
193
+ ```python
194
+ from pydantic import BaseModel
195
+ from langgraph.graph import StateGraph
196
+ from agent_snr import LangGraphSNRAdapter, SkipRule
197
+
198
+ class DiagnosticBrief(BaseModel):
199
+ status: str
200
+ confidence: float
201
+
202
+ adapter = LangGraphSNRAdapter(session_key="thread_id")
203
+
204
+ # Register skip-level bypass rule
205
+ adapter.firewall.router.register_rule(
206
+ SkipRule(
207
+ source_node="Validator",
208
+ bypassed_node="ManualReviewer",
209
+ target_node="Deployer",
210
+ min_snr=0.40,
211
+ output_schema=DiagnosticBrief,
212
+ )
213
+ )
214
+
215
+ # Decorate execution nodes (supports both sync and async)
216
+ @adapter.guard_node("Validator")
217
+ def validator_node(state):
218
+ ...
219
+ return state
220
+
221
+ # Guard conditional edges
222
+ builder = StateGraph(...)
223
+ builder.add_conditional_edges(
224
+ "Validator",
225
+ adapter.skip_router("Validator", default_router_fn),
226
+ )
227
+ ```
228
+
229
+ ### 4. CrewAI Step Callback
230
+
231
+ Enforce loop entropy detection and automatic circuit breaking on repetitive tool calls in CrewAI:
232
+
233
+ ```python
234
+ from crewai import Agent, Task, Crew
235
+ from agent_snr import CrewAISNRHook
236
+
237
+ hook = CrewAISNRHook(session_id="incident_triage")
238
+
239
+ crew = Crew(
240
+ agents=[...],
241
+ tasks=[...],
242
+ step_callback=hook.as_callback(),
243
+ )
244
+ crew.kickoff()
245
+ ```
246
+
247
+ ---
248
+
249
+ ## Configuration & Tuning Reference
250
+
251
+ `AgentSNRFirewall` comes pre-configured with balanced defaults, but every threshold can be customized:
252
+
253
+ | Parameter | Default | Component | Description |
254
+ |:---|:---:|:---|:---|
255
+ | `snr_drop_threshold` | `0.08` | `StateCompactor` | Frames below this score are suppressed as low-signal duplicates. |
256
+ | `max_frame_tokens` | `512` | `StateCompactor` | Maximum token ceiling for individual tool outputs before truncation. |
257
+ | `max_json_depth` | `5` | `StateCompactor` | Maximum recursion depth when pruning nested JSON dictionaries. |
258
+ | `max_list_items` | `15` | `StateCompactor` | Maximum items retained per list in JSON payloads before folding. |
259
+ | `entropy_warn` | `0.30` | `LoopEntropyDetector` | Triggers `INJECT_CORRECTION` to nudge the agent to alter strategy. |
260
+ | `entropy_break` | `0.15` | `LoopEntropyDetector` | Triggers `CIRCUIT_BREAK` (`SNRCircuitBreakError`) on action loops. |
261
+ | `drift_break` | `0.78` | `LoopEntropyDetector` | Triggers `CIRCUIT_BREAK` when EMA drift from initial goal exceeds threshold. |
262
+ | `max_context_tokens` | `8192` | `DynamicAttentionBudgeter` | Hard ceiling for total tokens in allocated context window. |
263
+ | `recency_window` | `2` | `DynamicAttentionBudgeter` | Number of trailing non-pinned frames preserved unconditionally. |
264
+ | `decay_lambda` | `0.08` | `DynamicAttentionBudgeter` | Exponential decay rate penalizing stale trajectory history. |
265
+ | `SkipRule.min_snr` | `0.45` | `SkipLevelRouter` | Minimum SNR score required to trigger a DAG skip-level bypass. |
266
+ | `SkipRule.min_goal_similarity`| `0.72` | `SkipLevelRouter` | Minimum cosine similarity with root user goal to permit skip. |
267
+
268
+ ---
269
+
270
+ ## Roadmap
271
+
272
+ - [x] Canonical data structures (`SignalFrame`, `TraceLedger`) & zero-dependency `HashNgramEmbedder`.
273
+ - [x] Deterministic multi-tier `StateCompactor` (JSON pruning, traceback folding, deduplication).
274
+ - [x] Discrete Shannon entropy & EMA Goal Drift detector (`LoopEntropyDetector`).
275
+ - [x] Dynamic attention knapsack budgeter (`DynamicAttentionBudgeter`).
276
+ - [x] Skip-level graph routing (`SkipLevelRouter`).
277
+ - [x] Framework adapters: OpenAI, LiteLLM, LangGraph, CrewAI.
278
+ - [x] Reproducible adversarial loop benchmarks & trajectory replay evaluation harness.
279
+ - [ ] Redis/Postgres-backed distributed ledger persistence.
280
+ - [ ] Auto-tuning hyperparameters based on trajectory history.
281
+
282
+ ---
283
+
284
+ ## Contributing & License
285
+
286
+ Contributions, issues, and feature requests are welcome! See [`CONTRIBUTING.md`](CONTRIBUTING.md) for local development instructions.
287
+
288
+ `agent-snr` is authored by **Sandeep Hipparagi** and licensed under the [Apache License 2.0](LICENSE).
@@ -0,0 +1,247 @@
1
+ # agent-snr: The Agent Signal Firewall
2
+
3
+ [![CI](https://github.com/Sandeep-Hipparagi/agent-snr/actions/workflows/ci.yml/badge.svg)](https://github.com/Sandeep-Hipparagi/agent-snr/actions/workflows/ci.yml)
4
+ [![PyPI version](https://img.shields.io/pypi/v/agent-snr.svg)](https://pypi.org/project/agent-snr/)
5
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/agent-snr/)
6
+ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
7
+ [![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
8
+ [![Type Checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)
9
+
10
+ > **An L4/L5 Signal Firewall for AI Agents**: *Treat agent memory and graph states like a high-efficiency organization.*
11
+
12
+ `agent-snr` is an ultra-fast, zero-lock-in Python firewall that sits between your agent loops and upstream LLM providers (OpenAI, Anthropic, LiteLLM, LangGraph, CrewAI). It continuously computes the **Signal-to-Noise Ratio (SNR)** of every message, prunes bloated metadata, detects non-convergent retry loops and silent goal drift, and dynamically bypasses unnecessary DAG critique hops.
13
+
14
+ ---
15
+
16
+ ## The Problem: Corporate Bureaucracy in Multi-Agent Graphs
17
+
18
+ As autonomous agent workflows scale beyond 5–10 steps, they invariably fall victim to three computational bottlenecks:
19
+
20
+ 1. **Context Rot & Token Bloat**: Multi-step tool calls return 15KB–40KB of nested JSON metadata (`request_id`, `trace_id`, `_links`, null headers) and repetitive 40-line `site-packages` Python stack traces. As context accumulates, tokens grow quadratically ($O(N^2)$), degrading LLM reasoning and inflating cost.
21
+ 2. **Silent Retry Loops & Goal Drift**: When an agent hits an error, it often enters a loop—mutating query keywords slightly or bouncing the unresolved sub-task back and forth between `Planner` and `Executor` while appearing "busy". Alternatively, reasoning subtly drifts away from the user's root goal over successive turns.
22
+ 3. **Unnecessary Hierarchical Hops**: Static agent graphs enforce rigid review cycles (e.g. `Researcher` $\rightarrow$ `ManagerReviewer` $\rightarrow$ `FinalSynthesizer`) even when early nodes produce unambiguous, schema-validated outputs with high confidence.
23
+
24
+ `agent-snr` solves this with an in-memory, deterministic **Signal Firewall** adding **$< 1.5\text{ ms}$ overhead** per step.
25
+
26
+ ---
27
+
28
+ ## Architecture
29
+
30
+ ```mermaid
31
+ flowchart LR
32
+ A["Raw Agent Messages\n(Tools, Prompts, History)"] --> B["StateCompactor\n(SNR Scoring & Pruning)"]
33
+ B --> C["LoopEntropyDetector\n(Shannon H & Goal Drift)"]
34
+ C -->|Loop / Drift| CB["🚨 Circuit Breaker\n(SNRCircuitBreakError)"]
35
+ C -->|Warning| IC["⚠️ Inject Correction\n(Nudge Prompt)"]
36
+ C -->|Healthy| D["DynamicAttentionBudgeter\n(Knapsack Utility Packing)"]
37
+ D --> E["SkipLevelRouter\n(Schema & SNR Bypass)"]
38
+ E --> F["Optimized Context Window\n(to LLM Provider)"]
39
+ ```
40
+
41
+ 1. **`StateCompactor`**: Computes lexical and semantic novelty scores. Prunes noise keys, collapses whitespace, folds repetitive internal tracebacks, and deduplicates idempotent tool reads.
42
+ 2. **`LoopEntropyDetector`**: Tracks discrete action entropy ($H_{\text{discrete}}$) and semantic stagnation ($S_t$) across trailing execution frames, combined with EMA Goal Drift ($D_t$) against initial user intents.
43
+ 3. **`DynamicAttentionBudgeter`**: Knapsack utility density allocation that preserves pinned constraints (system prompt, root goal) and recency windows while respecting strict token ceilings.
44
+ 4. **`SkipLevelRouter`**: Dynamically evaluates intermediate outputs against Pydantic schemas and SNR thresholds, bypassing redundant evaluation hops.
45
+
46
+ ---
47
+
48
+ ## Empirical Benchmark Results
49
+
50
+ Measured across **50 trials per scenario** (`seed=42`) comparing unprotected baseline execution against `AgentSNRFirewall`. Reproduced via [`benchmarks/run_all.py`](benchmarks/run_all.py).
51
+
52
+ ### 1. Adversarial Loop & Context Bloat Stress Suite
53
+
54
+ | Scenario | Baseline Tokens | SNR Tokens | Token Reduction | Baseline Steps | SNR Steps | Loop Intercept Rate | False Positive Break Rate |
55
+ |:---|---:|---:|---:|---:|---:|---:|---:|
56
+ | **Argument-Mutation Tool Retry Loop** | 24,950 | 242 | **99.0%** | 25.0 | 3.0 | **100.0%** | 0.0% |
57
+ | **Ping-Pong Multi-Agent Delegation Loop** | 12,674 | 417 | **96.7%** | 25.0 | 5.0 | **100.0%** | 0.0% |
58
+ | **Bloated JSON & Stack-Trace Explosion** | 119,900 | 15,148 | **87.4%** | 10.0 | 10.0 | *N/A (Bloat)* | 0.0% |
59
+ | **Silent Semantic Goal Drift** | 4,186 | 166 | **96.0%** | 12.0 | 3.0 | **100.0%** | 0.0% |
60
+ | **Control Group (Valid SE Workflow)** | 2,963 | 2,165 | **26.9%** | 11.0 | 11.0 | *N/A (Valid)* | **0.0%** |
61
+ | **Overall Stress Benchmark Average** | **8,234,700** | **906,900** | **89.0%** | — | — | **100.0%** | **0.0%** |
62
+
63
+ ### 2. Trajectory Replay A/B Evaluation (20 Representative Workflows)
64
+
65
+ Replayed across 20 representative real-world workflows (coding, API orchestration, research):
66
+
67
+ | Metric | Baseline Agent | AgentSNRFirewall | Optimization Impact |
68
+ |:---|---:|---:|:---|
69
+ | **Total Prompt Tokens Consumed** | 25,305 | 19,376 | **-23.4% prompt tokens** |
70
+ | **Mean Peak Context Window** | 317.5 tokens | 216.5 tokens | **-31.8% peak window** |
71
+ | **LLM Hops Saved via SkipLevelRouter** | 0 hops (0.0%) | 20 / 20 hops | **100.0% eligible skips saved** |
72
+ | **Critical Fact Retention Recall** | 100.0% | 100.0% | **Zero constraint amnesia** |
73
+ | **Per-Step Firewall Latency Overhead** | 0.00 ms | **p50: 0.76 ms \| p95: 1.43 ms** | **Sub-10ms latency confirmed** |
74
+
75
+ To reproduce these numbers locally:
76
+ ```bash
77
+ python benchmarks/run_all.py --trials 50
78
+ ```
79
+
80
+ ---
81
+
82
+ ## Installation
83
+
84
+ ```bash
85
+ # Core package (zero ML model dependencies out of the box)
86
+ pip install agent-snr
87
+
88
+ # Optional fast on-device semantic embeddings (fastembed + BGE)
89
+ pip install "agent-snr[embeddings]"
90
+
91
+ # Optional LangGraph extras
92
+ pip install "agent-snr[langgraph]"
93
+ ```
94
+
95
+ ---
96
+
97
+ ## Quickstart Integrations
98
+
99
+ ### 1. Read-Only Telemetry Audit (`dry_run=True` / CLI)
100
+
101
+ Profile token waste and loop occurrences in your existing agent without altering outputs:
102
+
103
+ ```bash
104
+ # Run the interactive CLI diagnostic demo
105
+ agent-snr demo
106
+ ```
107
+
108
+ In Python:
109
+ ```python
110
+ from agent_snr import AgentSNRFirewall
111
+
112
+ # Profile in dry-run mode
113
+ firewall = AgentSNRFirewall(dry_run=True)
114
+ optimized_msgs, action, metrics = firewall.process_outbound(
115
+ session_id="audit_01",
116
+ node_id="researcher",
117
+ messages=messages,
118
+ )
119
+
120
+ # Print rich diagnostic telemetry summary
121
+ firewall.profiler.print_report()
122
+ ```
123
+
124
+ ### 2. OpenAI & LiteLLM Drop-In Wrapper
125
+
126
+ Wrap any sync or async OpenAI-compatible client. `agent-snr` automatically intercepts outbound payloads, prunes noise, and enforces circuit breakers:
127
+
128
+ ```python
129
+ from openai import OpenAI
130
+ from agent_snr import SNRWrappedOpenAI
131
+
132
+ # Wrap native OpenAI client
133
+ client = SNRWrappedOpenAI(OpenAI(), session_id="user_session_42")
134
+
135
+ response = client.chat.completions.create(
136
+ model="gpt-4o",
137
+ messages=[
138
+ {"role": "user", "content": "Analyze system performance"},
139
+ {"role": "tool_result", "content": bloated_json_string},
140
+ ],
141
+ snr_node_id="analyst", # optional node tag for trajectory tracking
142
+ )
143
+
144
+ # Access diagnostic profiler metrics
145
+ client.profiler.print_report()
146
+ ```
147
+
148
+ ### 3. LangGraph Node Guard & Skip-Level Router
149
+
150
+ Protect LangGraph nodes from bloat and bypass intermediate critique nodes when output meets schema:
151
+
152
+ ```python
153
+ from pydantic import BaseModel
154
+ from langgraph.graph import StateGraph
155
+ from agent_snr import LangGraphSNRAdapter, SkipRule
156
+
157
+ class DiagnosticBrief(BaseModel):
158
+ status: str
159
+ confidence: float
160
+
161
+ adapter = LangGraphSNRAdapter(session_key="thread_id")
162
+
163
+ # Register skip-level bypass rule
164
+ adapter.firewall.router.register_rule(
165
+ SkipRule(
166
+ source_node="Validator",
167
+ bypassed_node="ManualReviewer",
168
+ target_node="Deployer",
169
+ min_snr=0.40,
170
+ output_schema=DiagnosticBrief,
171
+ )
172
+ )
173
+
174
+ # Decorate execution nodes (supports both sync and async)
175
+ @adapter.guard_node("Validator")
176
+ def validator_node(state):
177
+ ...
178
+ return state
179
+
180
+ # Guard conditional edges
181
+ builder = StateGraph(...)
182
+ builder.add_conditional_edges(
183
+ "Validator",
184
+ adapter.skip_router("Validator", default_router_fn),
185
+ )
186
+ ```
187
+
188
+ ### 4. CrewAI Step Callback
189
+
190
+ Enforce loop entropy detection and automatic circuit breaking on repetitive tool calls in CrewAI:
191
+
192
+ ```python
193
+ from crewai import Agent, Task, Crew
194
+ from agent_snr import CrewAISNRHook
195
+
196
+ hook = CrewAISNRHook(session_id="incident_triage")
197
+
198
+ crew = Crew(
199
+ agents=[...],
200
+ tasks=[...],
201
+ step_callback=hook.as_callback(),
202
+ )
203
+ crew.kickoff()
204
+ ```
205
+
206
+ ---
207
+
208
+ ## Configuration & Tuning Reference
209
+
210
+ `AgentSNRFirewall` comes pre-configured with balanced defaults, but every threshold can be customized:
211
+
212
+ | Parameter | Default | Component | Description |
213
+ |:---|:---:|:---|:---|
214
+ | `snr_drop_threshold` | `0.08` | `StateCompactor` | Frames below this score are suppressed as low-signal duplicates. |
215
+ | `max_frame_tokens` | `512` | `StateCompactor` | Maximum token ceiling for individual tool outputs before truncation. |
216
+ | `max_json_depth` | `5` | `StateCompactor` | Maximum recursion depth when pruning nested JSON dictionaries. |
217
+ | `max_list_items` | `15` | `StateCompactor` | Maximum items retained per list in JSON payloads before folding. |
218
+ | `entropy_warn` | `0.30` | `LoopEntropyDetector` | Triggers `INJECT_CORRECTION` to nudge the agent to alter strategy. |
219
+ | `entropy_break` | `0.15` | `LoopEntropyDetector` | Triggers `CIRCUIT_BREAK` (`SNRCircuitBreakError`) on action loops. |
220
+ | `drift_break` | `0.78` | `LoopEntropyDetector` | Triggers `CIRCUIT_BREAK` when EMA drift from initial goal exceeds threshold. |
221
+ | `max_context_tokens` | `8192` | `DynamicAttentionBudgeter` | Hard ceiling for total tokens in allocated context window. |
222
+ | `recency_window` | `2` | `DynamicAttentionBudgeter` | Number of trailing non-pinned frames preserved unconditionally. |
223
+ | `decay_lambda` | `0.08` | `DynamicAttentionBudgeter` | Exponential decay rate penalizing stale trajectory history. |
224
+ | `SkipRule.min_snr` | `0.45` | `SkipLevelRouter` | Minimum SNR score required to trigger a DAG skip-level bypass. |
225
+ | `SkipRule.min_goal_similarity`| `0.72` | `SkipLevelRouter` | Minimum cosine similarity with root user goal to permit skip. |
226
+
227
+ ---
228
+
229
+ ## Roadmap
230
+
231
+ - [x] Canonical data structures (`SignalFrame`, `TraceLedger`) & zero-dependency `HashNgramEmbedder`.
232
+ - [x] Deterministic multi-tier `StateCompactor` (JSON pruning, traceback folding, deduplication).
233
+ - [x] Discrete Shannon entropy & EMA Goal Drift detector (`LoopEntropyDetector`).
234
+ - [x] Dynamic attention knapsack budgeter (`DynamicAttentionBudgeter`).
235
+ - [x] Skip-level graph routing (`SkipLevelRouter`).
236
+ - [x] Framework adapters: OpenAI, LiteLLM, LangGraph, CrewAI.
237
+ - [x] Reproducible adversarial loop benchmarks & trajectory replay evaluation harness.
238
+ - [ ] Redis/Postgres-backed distributed ledger persistence.
239
+ - [ ] Auto-tuning hyperparameters based on trajectory history.
240
+
241
+ ---
242
+
243
+ ## Contributing & License
244
+
245
+ Contributions, issues, and feature requests are welcome! See [`CONTRIBUTING.md`](CONTRIBUTING.md) for local development instructions.
246
+
247
+ `agent-snr` is authored by **Sandeep Hipparagi** and licensed under the [Apache License 2.0](LICENSE).
@@ -0,0 +1,106 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "agent-snr"
7
+ version = "0.1.1"
8
+ description = "An L4/L5 Signal Firewall for AI Agents: context compression, loop entropy circuit breaking, attention budgeting, and skip-level routing."
9
+ readme = "README.md"
10
+ authors = [
11
+ { name = "Sandeep Hipparagi" }
12
+ ]
13
+ license = { text = "Apache-2.0" }
14
+ requires-python = ">=3.10"
15
+ keywords = [
16
+ "agents",
17
+ "firewall",
18
+ "llm",
19
+ "snr",
20
+ "signal-to-noise",
21
+ "compression",
22
+ "langgraph",
23
+ "crewai",
24
+ "circuit-breaker",
25
+ "entropy",
26
+ "routing",
27
+ ]
28
+ classifiers = [
29
+ "Development Status :: 4 - Beta",
30
+ "Intended Audience :: Developers",
31
+ "Intended Audience :: Science/Research",
32
+ "License :: OSI Approved :: Apache Software License",
33
+ "Programming Language :: Python :: 3",
34
+ "Programming Language :: Python :: 3.10",
35
+ "Programming Language :: Python :: 3.11",
36
+ "Programming Language :: Python :: 3.12",
37
+ "Programming Language :: Python :: 3.13",
38
+ "Programming Language :: Python :: 3.14",
39
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
40
+ "Topic :: Software Development :: Libraries :: Python Modules",
41
+ ]
42
+ dependencies = [
43
+ "numpy",
44
+ "pydantic>=2.0",
45
+ "rich",
46
+ ]
47
+
48
+ [project.urls]
49
+ Homepage = "https://github.com/Sandeep-Hipparagi/agent-snr"
50
+ Documentation = "https://github.com/Sandeep-Hipparagi/agent-snr#readme"
51
+ Repository = "https://github.com/Sandeep-Hipparagi/agent-snr"
52
+ Issues = "https://github.com/Sandeep-Hipparagi/agent-snr/issues"
53
+ Changelog = "https://github.com/Sandeep-Hipparagi/agent-snr/releases"
54
+
55
+ [project.optional-dependencies]
56
+ embeddings = [
57
+ "fastembed>=0.3.0",
58
+ ]
59
+ langgraph = [
60
+ "langgraph>=0.2.0",
61
+ ]
62
+ dev = [
63
+ "pytest",
64
+ "pytest-asyncio",
65
+ "ruff",
66
+ "mypy",
67
+ ]
68
+
69
+ [project.scripts]
70
+ agent-snr = "agent_snr.cli:main"
71
+
72
+ [tool.setuptools.packages.find]
73
+ where = ["src"]
74
+
75
+ [tool.ruff]
76
+ line-length = 100
77
+ target-version = "py310"
78
+
79
+ [tool.ruff.lint]
80
+ select = [
81
+ "E", # pycodestyle errors
82
+ "W", # pycodestyle warnings
83
+ "F", # pyflakes
84
+ "I", # isort
85
+ "B", # flake8-bugbear
86
+ "C4", # flake8-comprehensions
87
+ "UP", # pyupgrade
88
+ ]
89
+ ignore = []
90
+
91
+ [tool.mypy]
92
+ strict = true
93
+ warn_return_any = true
94
+ warn_unused_configs = false
95
+ disallow_untyped_defs = true
96
+ disallow_incomplete_defs = true
97
+
98
+ [[tool.mypy.overrides]]
99
+ module = "fastembed"
100
+ ignore_missing_imports = true
101
+
102
+ [tool.pytest.ini_options]
103
+ testpaths = ["tests"]
104
+ pythonpath = ["."]
105
+ asyncio_mode = "auto"
106
+ addopts = "--basetemp=.pytest_temp"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+