# ToolFusion

> Intelligent middleware for AI agent tool orchestration — caching, dedup, fusion, and observability.

ToolFusion is a Python 3.11+ async-first middleware that sits between AI agents and their tools. It provides two-level caching (exact + semantic), single-flight request coalescing, two-stage deduplication, cross-tool fusion with conflict resolution, VAAC cache admission, circuit breakers, and full observability — all through a single decorator or adapter.

## Quick Start

```python
from toolfusion import ToolFusion

async with ToolFusion(preset="balanced") as tf:
    @tf.tool(cache_mode="semantic_ok", ttl=300)
    async def search(query: str) -> dict:
        return {"results": [...]}

    result = await tf.call("search", {"query": "python async"})
    print(result.result)            # tool output
    print(result.cache_info.source) # "miss", "l1_cache", "l2_cache"
```

## Docs

- [API Reference](https://github.com/HetanshWaghela/ToolFusion/blob/main/docs/API.md): Complete API docs with all parameters, types, and protocols
- [AI Agent Instructions](https://github.com/HetanshWaghela/ToolFusion/blob/main/AGENTS.md): Patterns and recipes for AI coding assistants
- [Usage Guide](https://github.com/HetanshWaghela/ToolFusion/blob/main/USAGE.md): Practical how-to guide with examples
- [Technical Spec](https://github.com/HetanshWaghela/ToolFusion/blob/main/TOOLFUSION_SPEC.md): Full technical specification
- [Changelog](https://github.com/HetanshWaghela/ToolFusion/blob/main/CHANGELOG.md): Version history
- [Contributing](https://github.com/HetanshWaghela/ToolFusion/blob/main/CONTRIBUTING.md): How to contribute

## Key Features

- Two-level caching (L1 exact hash + L2 semantic similarity)
- Single-flight request coalescing (N concurrent identical calls → 1 execution)
- Two-stage deduplication (SimHash/MinHash → semantic verification)
- VAAC cache admission (Thompson sampling multi-armed bandit)
- Cross-tool fusion with weighted conflict resolution
- Stale-while-revalidate for eligible tools
- Circuit breaker per tool
- 6 framework adapters: LangChain, OpenAI, CrewAI, AutoGen, MCP, Haystack
- Protocol-based pluggable architecture
- CLI tools: doctor, init, stats, bench, cache inspect/clear, explain

## Install

```bash
pip install toolfusion
```
