traceiq 0.3.1__tar.gz

traceiq-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      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 }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[plot,dev]"
+
+      - name: Run ruff check
+        run: |
+          ruff check src/ tests/
+
+      - name: Run ruff format check
+        run: |
+          ruff format --check src/ tests/
+
+      - name: Run pytest
+        run: |
+          pytest -v
+
+      - name: Run smoke test
+        run: |
+          python examples/smoke.py
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip build
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Validate with twine
+        run: |
+          pip install twine
+          python -m twine check dist/*
+
+      - name: Verify wheel
+        run: |
+          pip install dist/*.whl
+          python -c "import traceiq; print(f'TraceIQ v{traceiq.__version__} import successful!')"

traceiq-0.3.1/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,64 @@
+name: Publish to TestPyPI
+
+on:
+  push:
+    tags:
+      - "v*rc*"  # Only release candidates: v0.3.1rc1, v1.0.0rc2, etc.
+
+permissions:
+  contents: read
+  id-token: write  # Required for OIDC trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Validate with twine
+        run: python -m twine check dist/*
+
+      - name: Verify wheel installation
+        run: |
+          pip install dist/*.whl
+          python -c "import traceiq; print(f'traceiq {traceiq.__version__}')"
+          traceiq --version
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 5
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/traceiq/
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

traceiq-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+      - "!v*rc*"  # Exclude release candidates (handled by testpypi workflow)
+
+permissions:
+  contents: read
+  id-token: write  # Required for OIDC trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Validate with twine
+        run: python -m twine check dist/*
+
+      - name: Verify wheel installation
+        run: |
+          pip install dist/*.whl
+          python -c "import traceiq; print(f'traceiq {traceiq.__version__}')"
+          traceiq --version
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 5
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/traceiq/
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

traceiq-0.3.1/.gitignore

@@ -0,0 +1,98 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pytype static type analyzer
+.pytype/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Project specific
+*.db
+*.sqlite
+examples/output/*.png
+examples/output/*.csv
+examples/output/*.jsonl
+
+# macOS
+.DS_Store
+
+# MkDocs build output
+site/
+
+# Build artifacts
+dist/
+build/

traceiq-0.3.1/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.9
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

traceiq-0.3.1/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to TraceIQ will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-16
+
+### Added
+
+- **Truncation flags**: `sender_truncated` and `receiver_truncated` flags are added to score results when content exceeds `max_content_length`
+- **Real batch embeddings**: `embed_batch()` now uses true batch encoding via `model.encode(list)` for better performance
+- **Deterministic ordering**: All ranking outputs (`top_influencers`, `top_susceptible`, `top_influenced`) are now sorted by score descending, then agent_id ascending for consistent results
+- **CLI validation**: The `ingest` command now validates that both `sender_content` and `receiver_content` are present in each JSONL record, with line number reporting on errors
+- **Pre-commit hooks**: Added `.pre-commit-config.yaml` with ruff format and lint hooks
+- **New tests**: Added comprehensive PyPI safety tests for imports, schema compatibility, caching, and deterministic behavior
+
+### Changed
+
+- **max_content_length default**: Increased from 512 to 5000 characters
+- **Embedding cache key**: Cache key is now based on the hash of truncated content only, not full content
+- **Schema migration**: Old databases with single `content` column now raise `RuntimeError` instead of auto-migrating
+- **Version sourcing**: Version is now read from package metadata (single source of truth in `pyproject.toml`)
+
+### Fixed
+
+- **Susceptibility plot label**: Changed X-axis label from "Total Incoming Influence" to "Total Incoming Drift" to accurately reflect the metric
+
+### Documentation
+
+- Added detailed docstring in `scoring.py` explaining baseline definition and influence scoring algorithms
+
+## [0.1.0] - 2026-02-01
+
+### Added
+
+- Initial release
+- Core `InfluenceTracker` class for tracking AI-to-AI interactions
+- Support for memory and SQLite storage backends
+- SentenceTransformer-based embeddings with LRU caching
+- Mock embedder for testing without heavy dependencies
+- Drift and influence scoring with configurable thresholds
+- NetworkX-based influence graph analytics
+- Matplotlib plotting functions (drift over time, heatmaps, bar charts, network graphs)
+- CLI with init, ingest, summary, export, and plot commands
+- CSV and JSONL export functions
+- Comprehensive test suite
+- MkDocs documentation

traceiq-0.3.1/CLAUDE.md

@@ -0,0 +1,239 @@
+# CLAUDE.md - TraceIQ Project Context
+
+## Project Overview
+
+**TraceIQ** is a Python library for measuring AI-to-AI influence in multi-agent systems. It tracks how one agent's outputs influence another agent's behavior using semantic embeddings and provides tools for analysis, visualization, and security monitoring.
+
+## Repository
+
+- **GitHub**: https://github.com/Anarv2104/TraceIQ
+- **PyPI**: traceiq (pending publication)
+- **Version**: 0.3.0
+
+## Project Status: COMPLETE
+
+### v0.3.0 - IEEE Research Framework
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| Core Implementation | ✅ Done | All source modules implemented |
+| Storage Backends | ✅ Done | Memory and SQLite backends |
+| Embeddings | ✅ Done | SentenceTransformer + Mock embedder |
+| Scoring Engine | ✅ Done | Drift, influence, IQx, RWI, Z-score |
+| Graph Analytics | ✅ Done | NetworkX + spectral radius |
+| Plotting | ✅ Done | 10 plot types including IEEE metrics |
+| CLI | ✅ Done | Extended with IEEE metric commands |
+| Export | ✅ Done | CSV and JSONL export functions |
+| IEEE Metrics | ✅ Done | 7 new metrics (IQx, RWI, PR, etc.) |
+| Capability Registry | ✅ Done | Attack surface computation |
+| Research Scripts | ✅ Done | Simulation, ablation, sensitivity |
+| Tests | ✅ Done | 116 tests passing |
+| Documentation | ✅ Done | MATH.md + updated docs |
+
+## Architecture
+
+```
+TraceIQ/
+├── src/traceiq/
+│   ├── __init__.py          # Public API exports
+│   ├── models.py             # Pydantic models (extended with IEEE fields)
+│   ├── tracker.py            # Main InfluenceTracker class
+│   ├── embeddings.py         # SentenceTransformerEmbedder, MockEmbedder
+│   ├── scoring.py            # ScoringEngine (drift, IQx, RWI, Z-score)
+│   ├── metrics.py            # NEW: Core IEEE metric computations
+│   ├── capabilities.py       # NEW: CapabilityRegistry for attack surface
+│   ├── graph.py              # InfluenceGraph (spectral radius, adjacency)
+│   ├── plotting.py           # Extended plotting (IQx heatmap, PR over time)
+│   ├── cli.py                # Click CLI (propagation-risk, alerts, etc.)
+│   ├── export.py             # CSV/JSONL export functions
+│   └── storage/
+│       ├── base.py           # Abstract StorageBackend
+│       ├── memory.py         # MemoryStorage (dict-based)
+│       └── sqlite.py         # SQLiteStorage (extended schema)
+├── research/                 # NEW: Research experiment scripts
+│   ├── synthetic_simulation.py
+│   ├── ablation_study.py
+│   └── sensitivity_analysis.py
+├── tests/                    # Pytest test suite
+├── docs/                     # MkDocs documentation
+├── examples/                 # Runnable examples
+├── MATH.md                   # NEW: Mathematical framework documentation
+└── pyproject.toml           # Package configuration (v0.3.0)
+```
+
+## IEEE Metrics Summary
+
+| Metric | Formula | Purpose |
+|--------|---------|---------|
+| **Drift (L2)** | `D = \|\|s(t+) - s(t-)\|\|_2` | L2 norm state change |
+| **IQx** | `IQx = D / (B + ε)` | Normalized influence quotient |
+| **Accumulated Influence** | `AI = Σ IQx` | Sum over window |
+| **Propagation Risk** | `PR = spectral_radius(W)` | Network instability |
+| **Attack Surface** | `AS = Σ p(c)` | Capability-weighted risk |
+| **RWI** | `RWI = IQx × AS` | Security-adjusted influence |
+| **Z-score** | `Z = (IQx - μ) / (σ + ε)` | Anomaly detection |
+
+## Key Algorithms
+
+### Legacy Drift Detection
+```python
+drift_delta = 1 - cosine_similarity(current_embedding, baseline_embedding)
+```
+
+### IEEE Drift (L2)
+```python
+drift_l2 = np.linalg.norm(emb_after - emb_before)
+```
+
+### Influence Quotient (IQx)
+```python
+IQx = drift_l2 / (baseline_median + epsilon)
+```
+
+### Propagation Risk
+```python
+spectral_radius = max(abs(eigenvalues(adjacency_matrix)))
+```
+
+### Risk-Weighted Influence
+```python
+RWI = IQx * attack_surface
+```
+
+## 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]`)
+
+## Commands
+
+```bash
+# Install
+pip install -e ".[all,dev]"
+
+# Run tests
+pytest -v
+
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+
+# Build package
+python -m build
+
+# Run research simulation
+python research/synthetic_simulation.py
+
+# CLI commands (v0.3.0)
+traceiq --help
+traceiq propagation-risk --db traceiq.db
+traceiq alerts --db traceiq.db --threshold 2.0
+traceiq risky-agents --db traceiq.db
+traceiq capabilities show
+traceiq plot iqx-heatmap --db traceiq.db -o heatmap.png
+```
+
+## Example Usage (v0.3.0)
+
+```python
+from traceiq import InfluenceTracker, TrackerConfig
+
+# Configure with IEEE metrics
+config = TrackerConfig(
+    storage_backend="sqlite",
+    storage_path="research.db",
+    baseline_window=10,
+    epsilon=1e-6,
+    anomaly_threshold=2.0,
+    capability_weights={
+        "execute_code": 1.0,
+        "admin": 1.5,
+    }
+)
+
+tracker = InfluenceTracker(config=config)
+
+# Register agent capabilities
+tracker.capabilities.register_agent("agent_0", ["execute_code", "admin"])
+tracker.capabilities.register_agent("agent_1", ["file_read"])
+
+# Track with full metrics
+result = tracker.track_event(
+    sender_id="agent_0",
+    receiver_id="agent_1",
+    sender_content="Execute this command...",
+    receiver_content="Executing command...",
+)
+
+print(f"IQx: {result['IQx']}")
+print(f"RWI: {result['RWI']}")
+print(f"Z-score: {result['Z_score']}")
+print(f"Alert: {result['alert']}")
+
+# Get propagation risk
+pr = tracker.get_propagation_risk()
+print(f"Propagation Risk: {pr}")
+
+# Get anomaly alerts
+alerts = tracker.get_alerts()
+print(f"Alerts: {len(alerts)}")
+```
+
+## Test Results
+
+```
+116 tests passing (110 passed, 6 skipped)
+- test_metrics.py: 25 tests (L2 drift, IQx, PR, AS, RWI, Z-score)
+- test_capabilities.py: 21 tests (registry, persistence, attack surface)
+- test_scoring.py: 12 tests (cosine similarity, cold start, thresholds)
+- test_storage_sqlite.py: 11 tests (CRUD, persistence, schema migration)
+- test_export.py: 10 tests (CSV, JSONL output)
+- test_plotting.py: 7 tests (visualization generation - skipped without matplotlib)
+- test_pypi_safety.py: 16 tests (import safety, schema compat, determinism)
+```
+
+## Research Experiments
+
+### Synthetic Simulation
+```bash
+python research/synthetic_simulation.py
+```
+- 5-agent simulation with biased injector
+- Measures influence propagation
+- Generates plots to `research/outputs/`
+
+### Ablation Study
+```bash
+python research/ablation_study.py
+```
+- Tests baseline_window [3, 5, 10, 15, 20, 30]
+- Measures detection rate vs window size
+
+### Sensitivity Analysis
+```bash
+python research/sensitivity_analysis.py
+```
+- Epsilon sensitivity
+- Anomaly threshold precision/recall
+- Capability weight schemes
+
+## Backward Compatibility
+
+- v0.2.0 databases automatically migrated to v0.3.0 schema
+- All v0.2.0 API remains functional
+- New IEEE metric fields default to None for old records
+
+## Contact
+
+Repository: https://github.com/Anarv2104/TraceIQ