traceiq 0.3.2__tar.gz → 0.3.4__tar.gz

{traceiq-0.3.2 → traceiq-0.3.4}/.gitignore

@@ -87,6 +87,10 @@ examples/output/*.png
 examples/output/*.csv
 examples/output/*.jsonl
 
+# Experiments output
+experiments/results/*.csv
+experiments/plots/*.png
+
 # macOS
 .DS_Store
 

{traceiq-0.3.2 → traceiq-0.3.4}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 TraceIQ Contributors
+Copyright (c) 2026 TraceIQ 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

{traceiq-0.3.2 → traceiq-0.3.4}/MATH.md

@@ -88,6 +88,47 @@ $$\text{drift}_\text{cosine} = 1 - \frac{s_j(t^+) \cdot s_j(t^-)}{\|s_j(t^+)\| \
 
 ---
 
+## Counterfactual Influence
+
+### Formal Definition
+
+The **counterfactual influence** of agent $i$ on agent $j$ at time $t$ is formally defined as:
+
+$$I_{\text{CF}}(i \to j, t) = D(S_j(t^+), S_j^{\emptyset}(t^+))$$
+
+where:
+- $S_j(t^+)$ is agent $j$'s state after receiving message $M_i$ from agent $i$
+- $S_j^{\emptyset}(t^+)$ is the **counterfactual** state agent $j$ would have had without receiving $M_i$
+- $D(\cdot, \cdot)$ is a distance metric (L2 norm)
+
+**Interpretation**: Counterfactual influence measures the difference between what happened and what *would have happened* without the interaction.
+
+### Observable Approximation
+
+Computing $S_j^{\emptyset}(t^+)$ requires running the agent without the message, which is expensive and often impractical. TraceIQ uses an **observable approximation**:
+
+$$\hat{I}(i \to j, t) = D(S_j(t^+), S_j(t^-))$$
+
+where $S_j(t^-)$ is agent $j$'s state immediately before receiving $M_i$.
+
+### Justification
+
+Under the **local stability assumption** (in the absence of external input, agent behavior is locally stable over short time intervals):
+
+$$S_j^{\emptyset}(t^+) \approx S_j(t^-)$$
+
+This approximation measures the actual state change, attributing it to the interaction. The error in this approximation is bounded by the agent's baseline variance.
+
+### Relationship to IQx
+
+The Influence Quotient (IQx) normalizes the observable influence by baseline:
+
+$$\text{IQx}(i \to j, t) = \frac{\hat{I}(i \to j, t)}{B_j + \varepsilon} = \frac{D(S_j(t^+), S_j(t^-))}{B_j + \varepsilon}$$
+
+This connects the theoretical counterfactual definition to the practical IQx metric.
+
+---
+
 ## Influence Quotient (IQx)
 
 The Influence Quotient normalizes drift by receiver baseline:

traceiq-0.3.4/PKG-INFO

@@ -0,0 +1,356 @@
+Metadata-Version: 2.3
+Name: traceiq
+Version: 0.3.4
+Summary: Measure AI-to-AI influence in multi-agent systems
+Project-URL: Homepage, https://github.com/Anarv2104/TraceIQ
+Project-URL: Documentation, https://github.com/Anarv2104/TraceIQ#readme
+Project-URL: Repository, https://github.com/Anarv2104/TraceIQ
+Author: TraceIQ Contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,embeddings,ieee,influence,research,security,tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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 :: Security
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.7; extra == 'all'
+Requires-Dist: pandas>=2.0; extra == 'all'
+Requires-Dist: scipy>=1.10; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Provides-Extra: embedding
+Requires-Dist: sentence-transformers>=2.2; extra == 'embedding'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Provides-Extra: research
+Requires-Dist: jupyterlab>=4.0; extra == 'research'
+Requires-Dist: matplotlib>=3.7; extra == 'research'
+Requires-Dist: pandas>=2.0; extra == 'research'
+Requires-Dist: scipy>=1.10; extra == 'research'
+Description-Content-Type: text/markdown
+
+# TraceIQ
+
+**Measure AI-to-AI Influence in Multi-Agent Systems**
+
+[![PyPI version](https://img.shields.io/pypi/v/traceiq.svg?cacheSeconds=60)](https://pypi.org/project/traceiq/)
+[![Python versions](https://img.shields.io/pypi/pyversions/traceiq.svg?cacheSeconds=60)](https://pypi.org/project/traceiq/)
+[![License](https://img.shields.io/pypi/l/traceiq.svg?cacheSeconds=60)](https://pypi.org/project/traceiq/)
+
+---
+
+## What It Is
+
+- Tracks and quantifies how AI agents influence each other in multi-agent systems
+- Uses semantic embeddings to measure state changes between interactions
+- Provides network-level analysis of influence propagation
+- Includes anomaly detection for unusual influence patterns
+- Supports research with IEEE-standard metrics (IQx, RWI, Z-score)
+
+## What It Does NOT Measure
+
+- **Causal attribution**: TraceIQ detects correlation, not causation
+- **Intent**: Cannot determine if influence is intentional or benign
+- **Content analysis**: Does not parse meaning, only embedding similarity
+- **Internal state**: Measures observable outputs, not agent cognition
+
+## Research Context
+
+TraceIQ is developed as part of research on AI-to-AI influence and multi-agent coordination. The metrics are grounded in a formal mathematical framework documented in [MATH.md](MATH.md) and [docs/THEORY.md](docs/THEORY.md).
+
+---
+
+## Quickstart
+
+```python
+from traceiq import InfluenceTracker
+
+# Create tracker (use_mock_embedder=True for testing without sentence-transformers)
+tracker = InfluenceTracker(use_mock_embedder=True)
+
+# Track an interaction
+result = tracker.track_event(
+    sender_id="agent_a",
+    receiver_id="agent_b",
+    sender_content="We should all switch to renewable energy!",
+    receiver_content="You make a good point. Renewables are the future.",
+)
+
+# Access metrics
+print(f"State Drift: {result['drift_l2_state']}")
+print(f"IQx: {result['IQx']}")
+print(f"Alert: {result['alert']}")
+print(f"Risk Level: {result['risk_level']}")
+
+tracker.close()
+```
+
+## Installation
+
+```bash
+# Core installation
+pip install traceiq
+
+# With plotting support (matplotlib)
+pip install "traceiq[plot]"
+
+# With real embeddings (sentence-transformers)
+pip install "traceiq[embedding]"
+
+# Everything included
+pip install "traceiq[all]"
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/Anarv2104/TraceIQ.git
+cd TraceIQ
+pip install -e ".[all,dev]"
+```
+
+---
+
+## Metrics Overview
+
+| Metric | What It Captures |
+|--------|------------------|
+| **State Drift** | How much a receiver's output changed after an interaction |
+| **Influence Quotient (IQx)** | Normalized influence relative to baseline responsiveness |
+| **Propagation Risk (PR)** | Network-level instability (spectral radius > 1.0 = amplification) |
+| **Risk-Weighted Influence (RWI)** | IQx adjusted for sender's attack surface |
+| **Z-score** | Anomaly detection (values > threshold trigger alerts) |
+
+For detailed metric documentation, see [docs/metrics.md](docs/metrics.md).
+
+---
+
+## Basic Usage
+
+### Track Multiple Interactions
+
+```python
+interactions = [
+    {
+        "sender_id": "agent_a",
+        "receiver_id": "agent_b",
+        "sender_content": "AI will transform healthcare completely.",
+        "receiver_content": "Yes, medical AI is very promising.",
+    },
+    {
+        "sender_id": "agent_b",
+        "receiver_id": "agent_c",
+        "sender_content": "Healthcare AI needs careful regulation.",
+        "receiver_content": "Agreed, we need safety standards.",
+    },
+]
+
+results = tracker.bulk_track(interactions)
+
+for r in results:
+    print(f"{r['sender_id']} -> {r['receiver_id']}: IQx={r['IQx']}")
+```
+
+### Generate Summary Report
+
+```python
+summary = tracker.summary(top_n=5)
+
+print(f"Total Events: {summary.total_events}")
+print(f"Top Influencers: {summary.top_influencers}")
+print(f"Most Susceptible: {summary.top_susceptible}")
+```
+
+### Export Data
+
+```python
+tracker.export_csv("influence_data.csv")
+tracker.export_jsonl("influence_data.jsonl")
+```
+
+### Monitor Anomalies
+
+```python
+# Get propagation risk
+pr = tracker.get_propagation_risk()
+if pr > 1.0:
+    print(f"Warning: PR={pr:.2f} - influence may amplify")
+
+# Get anomaly alerts (only valid metrics, not cold-start)
+alerts = tracker.get_alerts()
+for alert in alerts:
+    print(f"Alert: Z={alert.Z_score:.2f}")
+```
+
+---
+
+## CLI Usage
+
+```bash
+# Initialize a database
+traceiq init --db analysis.db
+
+# Ingest interactions from JSONL file
+traceiq ingest interactions.jsonl --db analysis.db
+
+# View summary report
+traceiq summary --db analysis.db
+
+# Export data
+traceiq export --db analysis.db -o results.csv --format csv
+
+# Generate plots
+traceiq plot heatmap --db analysis.db -o heatmap.png
+traceiq plot network --db analysis.db -o network.png
+
+# IEEE Metrics Commands
+traceiq propagation-risk --db analysis.db
+traceiq alerts --db analysis.db --threshold 2.0
+traceiq risky-agents --db analysis.db --top-n 10
+```
+
+For full CLI reference, see [docs/cli.md](docs/cli.md).
+
+---
+
+## Visualizations
+
+```python
+from traceiq.plotting import (
+    plot_influence_heatmap,
+    plot_top_influencers,
+    plot_influence_network,
+    plot_drift_over_time,
+)
+
+# Influence heatmap
+plot_influence_heatmap(tracker.graph, output_path="heatmap.png")
+
+# Top influencers bar chart
+plot_top_influencers(tracker.graph, n=10, output_path="influencers.png")
+
+# Network visualization
+plot_influence_network(tracker.graph, output_path="network.png")
+```
+
+---
+
+## Research Testbed
+
+TraceIQ includes reproducible experiments for studying AI-to-AI influence:
+
+```bash
+pip install -e ".[research]"
+
+# Run experiments
+python experiments/run_exp1_wrong_hint.py   # Wrong hint infection
+python experiments/run_exp2_propagation.py  # Multi-hop propagation
+python experiments/run_exp3_mitigation.py   # Mitigation policy
+
+# Generate plots
+python experiments/plot_all.py
+```
+
+See [experiments/README.md](experiments/README.md) for details.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [docs/quickstart.md](docs/quickstart.md) | Getting started guide |
+| [docs/metrics.md](docs/metrics.md) | Detailed metric documentation |
+| [docs/configuration.md](docs/configuration.md) | Configuration reference |
+| [docs/architecture.md](docs/architecture.md) | System architecture |
+| [docs/integration.md](docs/integration.md) | Integration patterns |
+| [docs/cli.md](docs/cli.md) | CLI reference |
+| [docs/THEORY.md](docs/THEORY.md) | Mathematical foundations |
+| [MATH.md](MATH.md) | IEEE metric formulas |
+
+---
+
+## Dependencies
+
+**Core:**
+- pydantic >= 2.0
+- numpy >= 1.24
+- networkx >= 3.0
+- click >= 8.0
+- rich >= 13.0
+
+**Optional:**
+- sentence-transformers >= 2.2 (`[embedding]`)
+- matplotlib >= 3.7 (`[plot]`)
+- pandas >= 2.0, scipy >= 1.10 (`[research]`)
+
+---
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[all,dev]"
+
+# Run linter
+ruff check src/ tests/
+
+# Run tests
+pytest -v
+
+# Build documentation
+pip install mkdocs mkdocs-material
+mkdocs serve
+```
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests (`pytest`)
+4. Run linter (`ruff check src/ tests/`)
+5. Commit your changes
+6. Push to the branch
+7. Open a Pull Request
+
+## Citation
+
+If you use TraceIQ in your research, please cite:
+
+```bibtex
+@software{traceiq,
+  title = {TraceIQ: Measure AI-to-AI Influence in Multi-Agent Systems},
+  year = {2024},
+  url = {https://github.com/Anarv2104/TraceIQ}
+}
+```
+
+---
+
+*Built for AI safety researchers and multi-agent system developers*