swarm-test 0.1.0__tar.gz

swarm_test-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: |
+          pytest tests/ -v --cov=swarm_test --cov-report=term-missing --cov-report=xml --cov-fail-under=70
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.11'
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install linting tools
+        run: |
+          pip install ruff black mypy
+
+      - name: Run ruff
+        run: ruff check swarm_test/
+
+      - name: Run black check
+        run: black --check swarm_test/
+
+      - name: Run mypy
+        run: mypy swarm_test/ --ignore-missing-imports
+
+  example:
+    name: Run example
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run research_crew example
+        run: python examples/research_crew.py
+        timeout-minutes: 2
+
+      - name: Test CLI probe
+        run: swarm-test --help
+
+      - name: Test CLI scan
+        run: |
+          swarm-test scan \
+            --agents ResearchAgent --agents DataAgent --agents WriterAgent \
+            --edges "ResearchAgent:DataAgent" --edges "DataAgent:WriterAgent" \
+            --name "ci-test-swarm"

swarm_test-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Generated reports (keep examples intact)
+/*.html
+
+# Environment variables
+.env
+.env.*
+
+# Claude Code
+.claude/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

swarm_test-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 swarm-test contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swarm_test-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: swarm-test
+Version: 0.1.0
+Summary: The first reliability testing framework for multi-agent AI systems
+Project-URL: Homepage, https://github.com/surajkumar811/swarm-test
+Project-URL: Documentation, https://github.com/surajkumar811/swarm-test#readme
+Project-URL: Repository, https://github.com/surajkumar811/swarm-test
+Project-URL: Issues, https://github.com/surajkumar811/swarm-test/issues
+Author: swarm-test contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,autogen,chaos,crewai,langchain,multi-agent,reliability,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: colorlog>=6.7
+Requires-Dist: jinja2>=3.1
+Requires-Dist: networkx>=3.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: ipython; extra == 'dev'
+Requires-Dist: mypy>=1.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: types-networkx; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1; extra == 'langchain'
+Requires-Dist: langgraph>=0.0.20; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# swarm-test
+
+**The first reliability testing framework for multi-agent AI systems.**
+
+swarm-test builds a NetworkX interaction graph of your agent swarm and runs 5 automated chaos tests to surface cascade failures, context leakage, intent drift, collusion, and blast radius risks — all from a 3-line API.
+
+```python
+from swarm_test import SwarmProbe
+
+probe  = SwarmProbe(crew)
+report = probe.run_all()
+report.print_summary()
+```
+
+---
+
+## Features
+
+| Test | What it checks |
+|---|---|
+| **Cascade Failure** | Which agents, if they fail, bring down the most of the swarm |
+| **Context Leakage** | Sensitive data (credentials, PII) crossing agent boundaries |
+| **Intent Drift** | Agents acting outside their role; prompt injection; goal hijacking |
+| **Collusion Detection** | Dense cliques, echo chambers, orchestrator-bypass cycles |
+| **Blast Radius** | Single points of failure, critical path, redundancy score |
+
+---
+
+## Installation
+
+```bash
+pip install swarm-test
+# or with framework extras:
+pip install "swarm-test[crewai]"
+pip install "swarm-test[langchain]"
+```
+
+From source:
+
+```bash
+git clone https://github.com/surajkumar811/swarm-test
+cd swarm-test
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### With a CrewAI crew
+
+```python
+from crewai import Crew, Agent, Task
+from swarm_test import SwarmProbe
+
+researcher = Agent(role="researcher", goal="...", backstory="...")
+writer     = Agent(role="writer",     goal="...", backstory="...")
+crew = Crew(agents=[researcher, writer], tasks=[...])
+
+probe  = SwarmProbe(crew, swarm_name="my-crew")
+report = probe.run_all()
+report.print_summary()
+report.to_html("report.html")   # D3 graph visualization
+```
+
+### Static graph (no live swarm)
+
+```python
+from swarm_test import SwarmProbe, AgentNode, InteractionEvent, EventType
+
+a = AgentNode(name="Fetcher", role="researcher")
+b = AgentNode(name="Summarizer", role="writer")
+
+probe = SwarmProbe(
+    swarm_name="my-swarm",
+    agents=[a, b],
+    events=[InteractionEvent(
+        source_agent_id=a.id,
+        target_agent_id=b.id,
+        event_type=EventType.TASK_DELEGATE,
+    )],
+)
+report = probe.run_all()
+report.print_summary()
+```
+
+### CLI
+
+```bash
+# Run against a Python script containing a `crew` variable
+swarm-test probe my_crew.py --output report.html --fail-on-critical
+
+# Static scan from the command line
+swarm-test scan \
+  --agents Researcher --agents Analyst --agents Writer \
+  --edges "Researcher:Analyst" --edges "Analyst:Writer" \
+  --output report.html
+```
+
+---
+
+## Architecture
+
+```
+swarm_test/
+├── core/
+│   ├── models.py       # Pydantic models (AgentNode, Finding, SwarmReport, …)
+│   ├── graph.py        # NetworkX SwarmGraph
+│   ├── interceptor.py  # Monkey-patch agent methods, sensitive-data scanner
+│   └── probe.py        # SwarmProbe — main entry point
+├── attacks/
+│   ├── cascade.py          # Cascade failure simulation
+│   ├── context_leakage.py  # Sensitive-data boundary check
+│   ├── intent_drift.py     # Role violations + goal hijacking
+│   ├── collusion.py        # Clique/echo-chamber/cycle detection
+│   └── blast_radius.py     # Topological SPOF + redundancy analysis
+├── integrations/
+│   ├── base.py             # BaseAdapter
+│   └── crewai_adapter.py   # CrewAI Crew ingestion
+├── reporters/
+│   ├── console.py          # Rich terminal output
+│   └── html.py             # D3 force-directed graph report
+└── cli.py                  # Click CLI
+```
+
+---
+
+## Report Output
+
+### Terminal (Rich)
+
+```
+─────────────────── SWARM-TEST RELIABILITY REPORT ───────────────────
+
+ Summary
+ Swarm: research-crew-demo    Framework: crewai
+ Agents: 4   Edges: 6
+ Risk Score: 45/100
+ Duration: 12ms
+
+╭─────────────────── Test Results ─────────────────────╮
+│ Test                  Status   Findings  Critical  High │
+│ cascade_failure       FAILED       2         1       1  │
+│ context_leakage       PASSED       0         0       0  │
+│ intent_drift          PASSED       0         0       0  │
+│ collusion_detection   PASSED       0         0       0  │
+│ blast_radius          FAILED       1         1       0  │
+╰───────────────────────────────────────────────────────╯
+```
+
+### HTML Report
+
+Interactive D3.js force-directed graph showing agent nodes, interaction edges, and color-coded findings.
+
+---
+
+## Extending
+
+### Custom attack
+
+```python
+from swarm_test.attacks.base import BaseAttack
+from swarm_test.core.models import Finding, Severity, TestResult
+
+class MyCustomAttack(BaseAttack):
+    name = "my_custom_attack"
+
+    def run(self, graph):
+        findings = []
+        # ... analyze graph.graph, graph.events ...
+        return TestResult(test_name=self.name, findings=findings)
+```
+
+### Custom adapter
+
+```python
+from swarm_test.integrations.base import BaseAdapter
+
+class MyFrameworkAdapter(BaseAdapter):
+    framework_name = "my-framework"
+
+    def _ingest_impl(self, swarm, graph):
+        for raw_agent in swarm.my_agents:
+            node = self._make_agent_node(raw_agent.name, raw_agent.role)
+            graph.add_agent(node)
+```
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v --cov=swarm_test
+ruff check swarm_test/
+black swarm_test/
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

swarm_test-0.1.0/README.md

@@ -0,0 +1,203 @@
+# swarm-test
+
+**The first reliability testing framework for multi-agent AI systems.**
+
+swarm-test builds a NetworkX interaction graph of your agent swarm and runs 5 automated chaos tests to surface cascade failures, context leakage, intent drift, collusion, and blast radius risks — all from a 3-line API.
+
+```python
+from swarm_test import SwarmProbe
+
+probe  = SwarmProbe(crew)
+report = probe.run_all()
+report.print_summary()
+```
+
+---
+
+## Features
+
+| Test | What it checks |
+|---|---|
+| **Cascade Failure** | Which agents, if they fail, bring down the most of the swarm |
+| **Context Leakage** | Sensitive data (credentials, PII) crossing agent boundaries |
+| **Intent Drift** | Agents acting outside their role; prompt injection; goal hijacking |
+| **Collusion Detection** | Dense cliques, echo chambers, orchestrator-bypass cycles |
+| **Blast Radius** | Single points of failure, critical path, redundancy score |
+
+---
+
+## Installation
+
+```bash
+pip install swarm-test
+# or with framework extras:
+pip install "swarm-test[crewai]"
+pip install "swarm-test[langchain]"
+```
+
+From source:
+
+```bash
+git clone https://github.com/surajkumar811/swarm-test
+cd swarm-test
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### With a CrewAI crew
+
+```python
+from crewai import Crew, Agent, Task
+from swarm_test import SwarmProbe
+
+researcher = Agent(role="researcher", goal="...", backstory="...")
+writer     = Agent(role="writer",     goal="...", backstory="...")
+crew = Crew(agents=[researcher, writer], tasks=[...])
+
+probe  = SwarmProbe(crew, swarm_name="my-crew")
+report = probe.run_all()
+report.print_summary()
+report.to_html("report.html")   # D3 graph visualization
+```
+
+### Static graph (no live swarm)
+
+```python
+from swarm_test import SwarmProbe, AgentNode, InteractionEvent, EventType
+
+a = AgentNode(name="Fetcher", role="researcher")
+b = AgentNode(name="Summarizer", role="writer")
+
+probe = SwarmProbe(
+    swarm_name="my-swarm",
+    agents=[a, b],
+    events=[InteractionEvent(
+        source_agent_id=a.id,
+        target_agent_id=b.id,
+        event_type=EventType.TASK_DELEGATE,
+    )],
+)
+report = probe.run_all()
+report.print_summary()
+```
+
+### CLI
+
+```bash
+# Run against a Python script containing a `crew` variable
+swarm-test probe my_crew.py --output report.html --fail-on-critical
+
+# Static scan from the command line
+swarm-test scan \
+  --agents Researcher --agents Analyst --agents Writer \
+  --edges "Researcher:Analyst" --edges "Analyst:Writer" \
+  --output report.html
+```
+
+---
+
+## Architecture
+
+```
+swarm_test/
+├── core/
+│   ├── models.py       # Pydantic models (AgentNode, Finding, SwarmReport, …)
+│   ├── graph.py        # NetworkX SwarmGraph
+│   ├── interceptor.py  # Monkey-patch agent methods, sensitive-data scanner
+│   └── probe.py        # SwarmProbe — main entry point
+├── attacks/
+│   ├── cascade.py          # Cascade failure simulation
+│   ├── context_leakage.py  # Sensitive-data boundary check
+│   ├── intent_drift.py     # Role violations + goal hijacking
+│   ├── collusion.py        # Clique/echo-chamber/cycle detection
+│   └── blast_radius.py     # Topological SPOF + redundancy analysis
+├── integrations/
+│   ├── base.py             # BaseAdapter
+│   └── crewai_adapter.py   # CrewAI Crew ingestion
+├── reporters/
+│   ├── console.py          # Rich terminal output
+│   └── html.py             # D3 force-directed graph report
+└── cli.py                  # Click CLI
+```
+
+---
+
+## Report Output
+
+### Terminal (Rich)
+
+```
+─────────────────── SWARM-TEST RELIABILITY REPORT ───────────────────
+
+ Summary
+ Swarm: research-crew-demo    Framework: crewai
+ Agents: 4   Edges: 6
+ Risk Score: 45/100
+ Duration: 12ms
+
+╭─────────────────── Test Results ─────────────────────╮
+│ Test                  Status   Findings  Critical  High │
+│ cascade_failure       FAILED       2         1       1  │
+│ context_leakage       PASSED       0         0       0  │
+│ intent_drift          PASSED       0         0       0  │
+│ collusion_detection   PASSED       0         0       0  │
+│ blast_radius          FAILED       1         1       0  │
+╰───────────────────────────────────────────────────────╯
+```
+
+### HTML Report
+
+Interactive D3.js force-directed graph showing agent nodes, interaction edges, and color-coded findings.
+
+---
+
+## Extending
+
+### Custom attack
+
+```python
+from swarm_test.attacks.base import BaseAttack
+from swarm_test.core.models import Finding, Severity, TestResult
+
+class MyCustomAttack(BaseAttack):
+    name = "my_custom_attack"
+
+    def run(self, graph):
+        findings = []
+        # ... analyze graph.graph, graph.events ...
+        return TestResult(test_name=self.name, findings=findings)
+```
+
+### Custom adapter
+
+```python
+from swarm_test.integrations.base import BaseAdapter
+
+class MyFrameworkAdapter(BaseAdapter):
+    framework_name = "my-framework"
+
+    def _ingest_impl(self, swarm, graph):
+        for raw_agent in swarm.my_agents:
+            node = self._make_agent_node(raw_agent.name, raw_agent.role)
+            graph.add_agent(node)
+```
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v --cov=swarm_test
+ruff check swarm_test/
+black swarm_test/
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).