Metadata-Version: 2.3
Name: inflion
Version: 0.2.1
Summary: Observability and influence tracing infrastructure for multi-agent AI systems.
Project-URL: Homepage, https://github.com/Anarv2104/Inflion
Project-URL: Documentation, https://github.com/Anarv2104/Inflion#readme
Project-URL: Repository, https://github.com/Anarv2104/Inflion
Author: Inflion 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: crewai<1.0,>=0.30; extra == 'all'
Requires-Dist: jupyterlab>=4.0; extra == 'all'
Requires-Dist: langchain-core<0.4,>=0.2; extra == 'all'
Requires-Dist: langgraph<0.4,>=0.2; 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: crewai
Requires-Dist: crewai<1.0,>=0.30; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff==0.9.7; 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: langchain
Requires-Dist: langchain-core<0.4,>=0.2; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph<0.4,>=0.2; extra == 'langgraph'
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

<p align="center">
  <img src="https://img.shields.io/badge/Inflion-AI%20Influence%20Measurement-blue?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyek0xMiAyMGMtNC40MSAwLTgtMy41OS04LThzMy41OS04IDgtOCA4IDMuNTkgOCA4LTMuNTkgOC04IDh6Ii8+PC9zdmc+" alt="Inflion">
</p>

<h1 align="center">Inflion</h1>

> **Note:** This project was previously released as **TraceIQ** and has been renamed to **Inflion**. The API and behavior remain unchanged.

<p align="center">
  <strong>
Inflion is a Python library for measuring cross-agent influence in multi-agent AI systems,
providing reproducible metrics for semantic drift, propagation risk, and reasoning stability.
</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/inflion/"><img src="https://img.shields.io/pypi/v/inflion.svg?cacheSeconds=60?cacheSeconds=60" alt="PyPI version"></a>
  <a href="https://pypi.org/project/inflion/"><img src="https://img.shields.io/pypi/pyversions/inflion.svg?cacheSeconds=60?cacheSeconds=60" alt="Python versions"></a>
  <a href="https://pypi.org/project/inflion/"><img src="https://img.shields.io/pypi/l/inflion.svg?cacheSeconds=60?cacheSeconds=60" alt="License"></a>
  <a href="https://pypi.org/project/inflion/">
    <img src="https://img.shields.io/pypi/dm/inflion.svg?cacheSeconds=60" alt="Downloads">
  </a>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#quick-example">Quick Start</a> •
  <a href="#scientific-contributions">Science</a> •
  <a href="#documentation">Docs</a> •
  <a href="#citation">Cite</a>
</p>

---

## The Problem

Modern AI systems increasingly operate through interaction: agents collaborate, critique, retrieve, plan, and self-modify through communication with other agents.

Yet we lack scientific tools to answer fundamental questions:

> - **How much did one agent influence another?**
> - **Did incorrect reasoning propagate through the system?**
> - **When does collaboration become instability?**
> - **How can influence be measured reproducibly and rigorously?**

**Inflion** introduces a formal measurement framework for studying influence propagation in autonomous multi-agent AI systems.

---

## Scientific Contributions

Inflion provides three core measurement primitives:

### 1. Influence Quotient (IQx)

A quantitative metric measuring **semantic drift** in an agent's output caused by prior agent messages.

```
IQx = Drift_L2 / (Baseline_Median + ε)
```

IQx estimates how much reasoning changed due to interaction, enabling measurement of cross-agent cognitive influence.

### 2. Propagation Risk (PR)

A network-level metric estimating how influence spreads across an agent graph using **spectral radius analysis**.

```
PR = max(|eigenvalues(Adjacency_Matrix)|)
```

PR provides early detection of unstable influence propagation and cascading reasoning errors.

### 3. Reproducible Influence Experiments

Inflion includes CI-safe experimental pipelines evaluating:

- ✓ Hint injection and misinformation propagation
- ✓ Influence stability across agent chains
- ✓ Cold-start detection behavior
- ✓ Mitigation policy effectiveness

These experiments support ongoing research into multi-agent AI safety and **Contagious Intelligence**.

---

## Where Inflion Fits in AI Research

Modern AI tooling focuses on different layers of the stack:

| Tool | What It Measures |
|------|------------------|
| **TensorBoard** | Model training metrics |
| **Weights & Biases** | Experiment tracking |
| **LangSmith / Prompt tools** | Prompt execution traces |
| **Inflion** | Cross-agent influence and reasoning propagation |

Inflion introduces a missing instrumentation layer:
**measurement of cognitive influence between autonomous AI agents.**

As multi-agent systems become standard in RAG, planning, robotics, and orchestration,
understanding *how agents influence each other* becomes as critical as measuring accuracy.

---

## Why Inflion Exists

Autonomous AI systems are evolving from isolated models into **collaborative agent networks**.

However, we currently lack standardized methods to measure:

| Challenge | Description |
|-----------|-------------|
| **Cross-agent reasoning influence** | How does one agent's output change another's behavior? |
| **Error propagation** | Do mistakes cascade through agent pipelines? |
| **Stability** | Is collaborative reasoning stable or chaotic? |
| **Safety risks** | What are the emergent risks in multi-agent systems? |

Inflion was built as a **scientific instrument** for studying emergent behavior in distributed intelligence.

> **Inflion is not a dashboard. It is not a monitoring SaaS.**
>
> Inflion is **measurement infrastructure** for multi-agent cognition research.

---

## Research Vision

Inflion is measurement infrastructure for multi-agent AI systems.

As AI shifts from isolated models to collaborative agent networks, system behavior emerges from interactions between models—not from a single model alone. While we can measure accuracy, latency, and loss, we currently lack tools to quantify how reasoning propagates across agents.

Inflion provides reproducible metrics and structured tracking for cross-agent influence, reasoning drift, and propagation dynamics. The goal is not monitoring dashboards, but scientific instrumentation for studying distributed AI cognition.

If collaborative AI becomes the dominant computing paradigm, measuring influence between agents will be as fundamental as measuring model performance.

---

## Features

| Feature | Description |
|---------|-------------|
| 📊 **Influence Tracking** | Track influence between agent interactions |
| 🎯 **Semantic Drift** | Measure drift using embedding similarity |
| 🌐 **Propagation Risk** | Estimate network-level influence spread |
| ⚡ **Anomaly Detection** | Quantile-calibrated alerting system |
| 🧊 **Cold-Start Handling** | Statistical validation during warm-up |
| 🔬 **Research Pipelines** | CI-safe reproducible experiments |
| 🔌 **Integration Ready** | Templates for RAG and multi-agent orchestration |

---

## Installation

**Core library** (lightweight, no heavy ML dependencies):

```bash
pip install inflion
```

**With real embedding models:**

```bash
pip install "inflion[embedding]"
```

**With research plotting tools:**

```bash
pip install "inflion[research]"
```

**Full installation:**

```bash
pip install "inflion[embedding,research]"
```

---

## Real-World Use Cases

Inflion is designed for real multi-agent AI systems:

- **Evaluate RAG hallucination propagation**
  Measure whether incorrect retrieval contaminates downstream reasoning.

- **Audit autonomous agent pipelines**
  Track which agents influence critical decisions in planning systems.

- **Study collaborative reasoning stability**
  Detect when agent feedback loops amplify errors.

- **AI governance and accountability**
  Build audit trails showing how decisions evolved across agents.

- **Research on Contagious Intelligence**
  Quantify cognitive transfer between AI systems in controlled experiments.

Inflion acts as a **measurement microscope** for studying distributed AI cognition.

---

## Quick Example

```python
from inflion import InfluenceTracker

tracker = InfluenceTracker(use_mock_embedder=True)

result = tracker.track_event(
    sender_id="agent_a",
    receiver_id="agent_b",
    sender_content="We should switch to renewable energy.",
    receiver_content="Good point. Renewables are the future."
)

print("Drift:", result["drift_l2_state"])
print("IQx:", result["IQx"])
print("Alert:", result["alert"])

tracker.close()
```

**Output:**
```
Drift: 0.847
IQx: 1.23
Alert: False
```

---

## What Inflion Outputs

Each tracked interaction returns structured metrics you can log, visualize, or audit:

- `drift_l2_state` — semantic drift magnitude
- `IQx` — normalized influence score
- `alert` — anomaly signal (calibrated)
- `valid` — whether baseline is stabilized
- `receiver_state` — receiver baseline summary

---

## Research Applications

Inflion has been evaluated on synthetic multi-agent benchmarks
and integrated into experimental LLM pipelines involving chained,
retrieval-augmented, and tool-using agents.

The framework enables reproducible studies of:

- Influence propagation across agent graphs
- Stability of collaborative reasoning loops
- Detection of misleading hint injection
- Mitigation policy effectiveness
- Cold-start behavior in autonomous agents

All experiments are reproducible through CI-safe pipelines
that generate structured `summary.json` artifacts for verification.

---

## Integration Patterns

Inflion works with common agent architectures:

| Pattern | Description |
|---------|-------------|
| **LLM-only agents** | Track message → response influence |
| **RAG systems** | Include retrieved context in receiver input |
| **Tool-using agents** | Track tool output influence |
| **Memory agents** | Track before/after memory state |
| **Multi-agent orchestrators** | Full conversation influence graphs |

### Instrumentation

Inflion ships an adapter abstraction so framework integrations plug into the
tracker without touching core.

- v0.1.6 — `BaseAdapter` ABC, `DemoAdapter` reference impl, `apply_temporal_decay`.
- v0.1.8 — first real framework adapter: **LangGraph**.
- v0.1.9 — **LangChain** and **CrewAI** adapters on the same abstraction.

```python
from inflion import InfluenceTracker, TrackerConfig, DemoAdapter, apply_temporal_decay

tracker = InfluenceTracker(
    config=TrackerConfig(storage_backend="memory"),
    use_mock_embedder=True,
)
adapter = DemoAdapter(tracker, run_id="demo-1")

adapter.emit({"from": "planner", "to": "researcher", "input": "...", "output": "..."})

decayed = apply_temporal_decay(
    list(tracker.storage.get_all_scores()),
    list(tracker.storage.get_all_events()),
    lambda_=0.1,
    unit="hours",
)
```

Try the bundled mock pipeline:

```bash
python -m inflion.examples_runtime.mock_pipeline_demo
```

#### LangGraph adapter (v0.1.8)

Install the optional extra:

```bash
pip install "inflion[langgraph]"
```

**Recommended path — explicit `emit_node_transition`** (stable across LangGraph
versions; instrument from inside your nodes or your orchestration loop):

```python
from inflion import InfluenceTracker, TrackerConfig, InflionLangGraphAdapter

tracker = InfluenceTracker(
    config=TrackerConfig(storage_backend="memory"),
    use_mock_embedder=True,
)
adapter = InflionLangGraphAdapter(tracker, run_id="run-1")

adapter.emit_node_transition(
    prev_node="planner",
    next_node="researcher",
    prev_state={"plan": "outline"},
    next_state={"plan": "outline", "notes": "fact-1"},
    metadata={"step": 1},
)
```

Try the bundled LangGraph demo:

```bash
python -m inflion.examples_runtime.langgraph_pipeline_demo
```

##### Experimental — `wrap(graph)`

```python
wrapped = adapter.wrap(compiled_graph)
wrapped.invoke({"task": "..."})
```

May follow LangGraph internals between minor versions; pin LangGraph and
prefer `emit_node_transition` in production. The first call per process
emits a `UserWarning` pointing at the explicit API.

#### LangChain adapter (v0.1.9)

Install the optional extra:

```bash
pip install "inflion[langchain]"
```

**Recommended path — explicit `emit_chain_step`** (stable across LangChain
versions; instrument from your chain code or your orchestration loop):

```python
from inflion import InfluenceTracker, TrackerConfig, InflionLangChainAdapter

tracker = InfluenceTracker(
    config=TrackerConfig(storage_backend="memory"),
    use_mock_embedder=True,
)
adapter = InflionLangChainAdapter(tracker, run_id="run-1")

adapter.emit_chain_step(
    prev_step="prompt",
    next_step="llm",
    prev_input={"question": "..."},
    next_output={"answer": "..."},
)
```

Try the bundled LangChain demo:

```bash
python -m inflion.examples_runtime.langchain_pipeline_demo
```

##### Experimental — `callback_handler()`

```python
handler = adapter.callback_handler()
chain.invoke(inputs, config={"callbacks": [handler]})
```

Depends on LangChain's public callback surface; may follow LangChain
internals between minor versions. The first call per process emits a
`UserWarning` pointing at the explicit API.

#### CrewAI adapter (v0.1.9)

Install the optional extra:

```bash
pip install "inflion[crewai]"
```

**Recommended path — explicit `emit_task_handoff`** (stable across CrewAI
versions; emit from your task-completion handlers):

```python
from inflion import InfluenceTracker, TrackerConfig, InflionCrewAIAdapter

tracker = InfluenceTracker(
    config=TrackerConfig(storage_backend="memory"),
    use_mock_embedder=True,
)
adapter = InflionCrewAIAdapter(tracker, run_id="run-1")

adapter.emit_task_handoff(
    from_agent="researcher",
    to_agent="writer",
    prev_output="Findings: ...",
    next_input="Draft a summary of: ...",
)
```

Try the bundled CrewAI demo:

```bash
python -m inflion.examples_runtime.crewai_pipeline_demo
```

##### Experimental — `step_callback()`

```python
from crewai import Crew
cb = adapter.step_callback()
Crew(agents=[...], tasks=[...], step_callback=cb).kickoff()
```

Depends on CrewAI's documented step-callback parameter; may follow CrewAI
internals between minor versions. The first call per process emits a
`UserWarning` pointing at the explicit API.

> Adapters are thin instrumentation layers. Inflion-Core remains
> framework-agnostic — adapters must not leak framework types into core
> metrics or storage. `import inflion` never imports any framework; each
> `[framework]` extra is only required when you actually access its
> matching `Inflion*Adapter`.

---

### Sessions (v0.2.0)

Pass `run_id` (and optionally `task_id`) to `track_event` to tag events
into a session. The values are stamped into `InteractionEvent.metadata`
under the reserved keys `_inflion_run_id` / `_inflion_task_id`, and are
visible to the read-only `SessionTrace` API and the `inflion session`
CLI. No schema change.

```python
from inflion import InfluenceTracker, SessionTrace, list_sessions, TrackerConfig

tracker = InfluenceTracker(
    config=TrackerConfig(storage_backend="sqlite", storage_path="inflion.db"),
    use_mock_embedder=True,
)
for prompt, response in pairs:
    tracker.track_event("agent_a", "agent_b", prompt, response, run_id="exp-42")
tracker.close()
```

```bash
inflion session list --db inflion.db
inflion session show exp-42 --db inflion.db
inflion session export exp-42 --db inflion.db -o exp-42.jsonl
```

The exported JSONL row shape matches `inflion.export.export_combined_jsonl`
exactly — no new fields in v0.2.0. Row order is `timestamp` ascending
with `event_id` ascending as tiebreaker. `list_sessions` and
`inflion session list` are sorted by `last_timestamp` descending with
`run_id` ascending as tiebreaker.

#### Dogfood quickstart (v0.2.1)

The four shipped demos (`mock_pipeline_demo`, `langgraph_pipeline_demo`,
`langchain_pipeline_demo`, `crewai_pipeline_demo`) accept `--run-id` and
`--db` so consecutive invocations seed distinct sessions you can
immediately inspect via the CLI:

```bash
DB=/tmp/inflion-dogfood.db
python -m inflion.examples_runtime.mock_pipeline_demo --run-id run-1 --db $DB
python -m inflion.examples_runtime.mock_pipeline_demo --run-id run-2 --db $DB
python -m inflion.examples_runtime.mock_pipeline_demo --run-id run-3 --db $DB
inflion session list --db $DB
inflion session show run-2 --db $DB
inflion session export run-2 --db $DB -o /tmp/run-2.jsonl
```

Replace `mock_pipeline_demo` with `langgraph_pipeline_demo`,
`langchain_pipeline_demo`, or `crewai_pipeline_demo` to exercise each
adapter. Remove the dogfood DB with `rm /tmp/inflion-dogfood.db` when
you're done. The bare `python -m inflion.examples_runtime.<name>` (no
flags) keeps the original in-memory smoke behavior.

---

## What Inflion Is NOT

| Limitation | Explanation |
|------------|-------------|
| **Not causal inference** | Metrics measure correlation, not proven causation |
| **Not intent detection** | Cannot determine manipulation intent |
| **Not semantic understanding** | Measures embedding-level drift |
| **Not a production security system** | Research measurement tool |
| **Not plug-and-play safety** | Thresholds require calibration per environment |

---

## Research Context

Inflion supports research into:

- 🔬 AI-to-AI influence modeling
- 🧬 Contagious Intelligence hypothesis
- ⚖️ Multi-agent reasoning stability
- 🛡️ Autonomous system safety
- 🧠 Distributed cognition in AI systems

Detailed metric definitions and implementation notes
are available in the project documentation.

---

## Documentation

| Document | Description |
|----------|-------------|
| [Metrics](https://github.com/Anarv2104/Inflion/blob/main/docs/metrics.md) | Metric definitions and formulas |
| [Integration](https://github.com/Anarv2104/Inflion/blob/main/docs/integration.md) | Integration patterns |
| [CLI Reference](https://github.com/Anarv2104/Inflion/blob/main/docs/cli.md) | Command-line interface |
| [Configuration](https://github.com/Anarv2104/Inflion/blob/main/docs/configuration.md) | TrackerConfig options |
| [Architecture](https://github.com/Anarv2104/Inflion/blob/main/docs/architecture.md) | System design |
| [Theory](https://github.com/Anarv2104/Inflion/blob/main/docs/THEORY.md) | Mathematical foundations |
| [Experiments](https://github.com/Anarv2104/Inflion/tree/main/experiments) | Research testbed |

**CLI Help:** `inflion --help`

---

## Reproducibility & CI

Inflion experiments are **CI-safe**:

- ✅ Quick mode never hard-fails CI
- ✅ Proof mode enforces strict statistical validation
- ✅ Artifacts upload even on failures
- ✅ Experiments produce structured outputs

This ensures reproducible research pipelines.

---

## Contributing

Contributions welcome! See
[CONTRIBUTING.md](https://github.com/Anarv2104/Inflion/blob/main/CONTRIBUTING.md)

```bash
# 1. Fork the repository
# 2. Create a feature branch
git checkout -b feature/amazing-feature

# 3. Run tests and linter
pytest
ruff check src/ tests/

# 4. Submit a Pull Request
```

---

## Citation

If you use Inflion in your research, please cite:

```bibtex
@software{inflion,
  title = {Inflion: Measuring AI-to-AI Influence in Multi-Agent Systems},
  author = {Vasavada, Anarv and Contributors},
  year = {2026},
  url = {https://github.com/Anarv2104/Inflion}
}
```

---

## License

Inflion is open-source under the MIT License, enabling academic and commercial use with minimal restrictions.

See the full license text at:
https://github.com/Anarv2104/Inflion/blob/main/LICENSE

---

<p align="center">
  <a href="https://github.com/Anarv2104/Inflion">
    <img src="https://img.shields.io/badge/GitHub-Source%20Code-24292e?style=for-the-badge&logo=github&logoColor=white">
  </a>
  <a href="https://pypi.org/project/inflion/">
    <img src="https://img.shields.io/badge/PyPI-Install%20Package-3776AB?style=for-the-badge&logo=pypi&logoColor=white">
  </a>
  <a href="https://github.com/Anarv2104/Inflion/tree/main/docs">
    <img src="https://img.shields.io/badge/Docs-Technical%20Documentation-6A0DAD?style=for-the-badge&logo=readthedocs&logoColor=white">
  </a>
  <a href="https://github.com/Anarv2104/Inflion/issues">
    <img src="https://img.shields.io/badge/Community-Report%20Issues-D73A49?style=for-the-badge&logo=github&logoColor=white">
  </a>
</p>
