Metadata-Version: 2.5
Name: agentjit
Version: 0.1.10
Summary: Just-In-Time Compiler for AI Agent Trajectories. Compiles multi-step LLM workflows into ultra-fast deterministic Python code with zero token cost.
Project-URL: Homepage, https://github.com/eminsk/agentjit
Project-URL: Documentation, https://github.com/eminsk/agentjit#readme
Project-URL: Repository, https://github.com/eminsk/agentjit.git
Project-URL: Issues, https://github.com/eminsk/agentjit/issues
Project-URL: Interactive Colab Demo, https://colab.research.google.com/github/eminsk/agentjit/blob/main/notebooks/AgentJIT_Interactive_Demo.ipynb
Author: AgentJIT Team
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,compiler,free-threaded,freethreading,jit,llm,no-gil,nogil,optimization,pep-703,performance,pypy,pypy3,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3.16
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.8
Requires-Dist: typing-extensions>=4.0; python_version < '3.10'
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: rich>=12.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# ⚡ AgentJIT

### Just-In-Time Compiler for AI Agent Trajectories
**Compile flaky, 30-second multi-step AI Agent workflows into 5-millisecond deterministic code.**

[![PyPI Version](https://img.shields.io/pypi/v/agentjit.svg?style=flat)](https://pypi.org/project/agentjit/)
[![Conda-Forge](https://img.shields.io/conda/vn/conda-forge/agentjit.svg?style=flat&logo=condaforge)](https://anaconda.org/conda-forge/agentjit)
[![Debian / Ubuntu PPA](https://img.shields.io/badge/Debian%20%2F%20Ubuntu-APT%20PPA-E95420.svg?style=flat)](https://eminsk.github.io/ppa/)
[![The Daily Diff](https://img.shields.io/badge/The_Daily_Diff-%231_Top_Story_(9%2F10)-crimson?logo=hackernews)](https://tdd.cat/2026-09-13/)
[![Python Version](https://img.shields.io/badge/python-3.8%20--%203.16-blue.svg?style=flat)](https://pypi.org/project/agentjit/)
[![PyPy](https://img.shields.io/badge/PyPy-3.8%20--%203.12-orange.svg)](https://www.pypy.org/)
[![Free-Threaded No-GIL](https://img.shields.io/badge/No--GIL%20(PEP%20703)-3.13t%20%7C%203.14t%20%7C%203.15t%20%7C%203.16t-blueviolet.svg?style=flat)](https://pypi.org/project/agentjit/)
[![CI Test Suite](https://github.com/eminsk/agentjit/actions/workflows/ci.yml/badge.svg)](https://github.com/eminsk/agentjit/actions/workflows/ci.yml)
[![Hardware FASM SIMD](https://img.shields.io/badge/Hardware-FASM_AVX2_%2B_FMA-purple.svg?style=flat)](https://flatassembler.net/)
[![GitHub Stars](https://img.shields.io/github/stars/eminsk/agentjit?style=flat&logo=github)](https://github.com/eminsk/agentjit/stargazers)
[![GitHub Issues](https://img.shields.io/github/issues/eminsk/agentjit?style=flat&color=red&logo=github)](https://github.com/eminsk/agentjit/issues)
[![GitHub Discussions](https://img.shields.io/badge/Discussions-Join_Community-blue?style=flat&logo=github)](https://github.com/eminsk/agentjit/discussions)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![Speedup](https://img.shields.io/badge/speedup-1000x%2B-orange.svg)]()
[![Token Cost](https://img.shields.io/badge/tokens%20on%20hot%20path-%240.00-brightgreen.svg)]()
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eminsk/agentjit/blob/main/notebooks/AgentJIT_Interactive_Demo.ipynb)
[![Donate USDT](https://img.shields.io/badge/Donate-USDT_(TRC20)-26A17B?style=flat&logo=tether&logoColor=white)](https://tronscan.org/#/address/TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P)

> ### 🤝 Community, Issues & Support
> - 🐛 **Found a bug, compiler deopt issue, or guard failure?** Please [Open an Issue](https://github.com/eminsk/agentjit/issues) — reports are tracked and resolved quickly!
> - 💬 **Questions, trajectory compilation ideas, or new backends?** Join our [GitHub Discussions](https://github.com/eminsk/agentjit/discussions).
> - ⭐ **Find AgentJIT useful?** Give it a star on GitHub — it helps more AI agent engineers discover the compiler!
> - ☕ **Support development (USDT TRC-20):** `TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P` ([Verify on TronScan](https://tronscan.org/#/address/TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P))

[**Quickstart**](#quickstart) • [**Compatibility**](#compatibility) • [**Why AgentJIT?**](#the-problem-in-2026-why-agentjit) • [**FASM Acceleration**](#fasm-engine) • [**Architecture**](#architecture) • [**Benchmarks**](#benchmarks)

</div>

> 🏆 **Featured as #1 Top Story in [The Daily Diff](https://tdd.cat/2026-09-13/):** Selected by Arpit Bhayani as the lead AI story (*Depth: 9/10, Utility: 9/10, Novelty: 9/10, Interest: 9/10*). Discussion on [Hacker News](https://news.ycombinator.com/item?id=49683344).

---

## <a id="compatibility"></a>🧩 Universal Compatibility Matrix

| Runtime / Implementation | Supported Versions | Execution Mode | Status |
|:---|:---|:---|:---:|
| **CPython (Standard)** | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15, 3.16 (Alpha) | Bytecode + GIL | ✅ Fully Supported |
| **CPython (Free-Threaded)** | 3.13t, 3.14t, 3.15t, 3.16t (Alpha) | Multi-core No-GIL (PEP 703) | ✅ Fully Supported |
| **PyPy (JIT Accelerated)** | 3.8, 3.9, 3.10, 3.11, 3.12 | High-speed JIT tracing | ✅ Fully Supported |
| **FASM Hardware Engine** | AVX2+FMA (x86-64), SSE2 (x86 32-bit) | Bare-Metal Assembly Microkernels | ✅ Fully Supported |
| **Operating Systems** | Windows (7, 8, 10, 11), Linux, macOS (Intel & Apple Silicon) | x86_64, ARM64 | ✅ Fully Supported |

---

## <a id="the-problem-in-2026-why-agentjit"></a>💥 The Problem in 2026: Why AgentJIT?

In 2026, autonomous AI agents solve real-world workflows across business, DevOps, and data analysis. However, running stochastic LLM loops in production faces four critical barriers:

1. **Massive Latency:** A standard 4-step agent workflow (`think -> tool -> observe -> think`) takes **15 to 45 seconds**.
2. **Exponential Costs:** Running the loop 10,000 times/day costs thousands of dollars in redundant API tokens.
3. **Flakiness & Hallucinations:** Even 98% reliability per step leads to compounding errors across multi-turn trajectories.
4. **Redundant Reasoning:** Most agent invocations execute the *exact same structural trajectory* with slightly different input parameters (e.g. different user IDs or dates).

---

## <a id="fasm-engine"></a>⚡ Bare-Metal FASM Hardware SIMD Acceleration

AgentJIT integrates a high-performance **Flat Assembler (FASM)** hardware microkernel engine providing unrolled, native assembly acceleration for critical agent execution hot paths:

- 🏎️ **AVX2 + FMA (x86-64) & SSE2 (x86 32-bit):** Hand-crafted assembly microkernels with 256-bit SIMD registers (`agentjit64.dll`, `agentjit32.dll`).
- ⚡ **Sub-Nanosecond Trajectory Hashing:** 64-bit unrolled hash algorithms (`agentjit_fast_hash`) for instantaneous prompt and trajectory cache lookups (> 300,000 hashes/sec).
- 🛡️ **Vectorized Speculative Guards:** Parallel NULL-pointer evaluation and numerical range validation across parameters simultaneously using SIMD vector comparison.
- 🧠 **Semantic Prompt Similarity Router:** Unrolled 32-float AVX2+FMA cosine distance check (`agentjit_semantic_guard_cosine`) comparing prompt embeddings in **< 0.1 µs** to speculatively route to compiled pipelines or de-optimize to the LLM agent.
- 📦 **Zero External C/C++ Compiler Dependencies:** Assembled into standalone DLLs directly via FASM without MSVC, GCC, or bloated toolchains.

```python
import agentjit

# Verify active hardware SIMD backend
print(f"Active Backend: {agentjit.simd_backend()}")
# -> "AVX2+FMA (FASM x86-64, 256-bit SIMD)"

# Access the hardware engine directly
engine = agentjit.get_fasm_engine()
h = engine.fast_hash("Process order 1042")
all_valid = engine.eval_range_guards([25.0, 150.0], [0.0, 100.0], [50.0, 500.0])
```

---

## <a id="architecture"></a>🏗️ Architecture & Trajectory JIT Compilation

Just like **V8** compiles hot JavaScript into machine code, and **PyTorch `torch.compile`** traces dynamic tensors into optimized CUDA kernels, **AgentJIT traces dynamic agent trajectories and compiles them into pure, type-safe, ultra-fast Python code.**

```
       [Dynamic Agent Task]
                │
         (1st run / warmup)
                ▼
     ┌──────────────────────┐
     │   AgentJIT Tracer    │ ── (Captures tool calls, data flow, variables)
     └──────────────────────┘
                │
                ▼
     ┌──────────────────────┐
     │ DAG Flow Analyzer    │ ── (Parameter generalization, dependency graph)
     └──────────────────────┘
                │
                ▼
     ┌──────────────────────┐
     │ AST Code Generator   │ ── (Synthesizes pure Python pipeline + Guards)
     └──────────────────────┘
                │
                ▼
  ┌────────────────────────────┐
  │   Compiled JIT Pipeline    │ ──► Subsequent runs: <1ms, $0 tokens!
  └────────────────────────────┘
                │
       (Guard failure? Deopt!)
                ▼
     [Fall back to LLM Agent]
```

---

## ⚡ Key Features

- 🏎️ **Up to 100,000x Speedup:** Hot paths drop from ~20,000 ms to **< 0.1 ms**.
- 💸 **100% Token Savings:** Once compiled, recurring workflows run completely locally with **0 LLM tokens consumed**.
- 🛡️ **Speculative De-Optimization (Bailout):** Automatically generates runtime input guards. If unexpected data formats or divergent branches appear, AgentJIT transparently falls back to the dynamic LLM agent.
- 🔍 **Transparent & Inspectable:** Inspect the exact Python code generated by the JIT with `agent.source_code`.
- 🧵 **Free-Threaded / No-GIL (PEP 703) Ready:** Thread-safe runtime fully tested on Python 3.13t and 3.14t for true multi-core parallel agent execution without GIL contention.
- 🔌 **Framework Agnostic:** Seamlessly wraps LangChain, CrewAI, AutoGen, OpenAI Tool calls, or native Python functions.

---

## <a id="quickstart"></a>🚀 Quickstart

### Installation

| Platform / Manager | Installation Command |
|---|---|
| **PyPI (pip)** | `pip install agentjit` |
| **PyPI (uv)** | `uv add agentjit` |
| **Conda (Anaconda.org)** | `conda install -c m_n_nik agentjit` |
| **Ubuntu / Debian (APT PPA)** | `curl -sS https://eminsk.github.io/ppa/setup.sh \| sudo bash`<br>`sudo apt install python3-agentjit` |
| **Ubuntu / Debian (.deb)** | `sudo dpkg -i python3-agentjit_0.1.6-1_all.deb` |

```bash
pip install agentjit
# or with uv
uv add agentjit
```

### 10-Second Example

Decorate your agent with `@jit` and mark your tools with `@trace_tool`:

```python
from agentjit import jit, trace_tool

# 1. Define your tools
@trace_tool()
def search_product(name: str):
    return {"name": name, "price": 49.99, "stock": 120}

@trace_tool()
def apply_tax(price: float, tax_rate: float):
    return round(price * (1.0 + tax_rate), 2)

# 2. Decorate your agent with @jit
@jit
def checkout_agent(product_name: str, tax_rate: float):
    # This dynamic workflow could call an LLM (Claude, GPT, Gemini)
    item = search_product(name=product_name)
    total = apply_tax(price=item["price"], tax_rate=tax_rate)
    return {"item": item["name"], "total": total}

# --- Run 1: Warmup & Tracing (runs dynamic agent, compiles to Python) ---
order1 = checkout_agent("Mechanical Keyboard", 0.19)

# --- Run 2+: Instant compiled execution (ZERO tokens, sub-millisecond!) ---
order2 = checkout_agent("Wireless Mouse", 0.19)  # Takes 0.05 ms!
```

---

## 🔎 Inspecting Generated Code

You can view the exact synthesized Python code generated by the JIT at any time:

```python
print(checkout_agent.source_code)
```

**Synthesized Output:**
```python
def compiled_checkout_agent(product_name, tax_rate):
    """JIT-compiled trajectory pipeline generated by AgentJIT.
    Executes deterministically in sub-millisecond time with zero token cost.
    """
    # --- Speculative Guards ---
    if not (product_name is not None):
        raise GuardViolation("Argument 'product_name' must not be None", param="product_name")
    if not (isinstance(product_name, str)):
        raise GuardViolation("Argument 'product_name' must be of type str", param="product_name")

    # --- Execution Steps ---
    step_1_out = _tools['search_product'](name=product_name)
    step_2_out = _tools['apply_tax'](price=step_1_out['price'], tax_rate=tax_rate)

    # --- Return Final Result ---
    return {'item': step_1_out['name'], 'total': step_2_out}
```

---

## <a id="benchmarks"></a>📊 Benchmarks

Benchmark comparing a simulated 3-step reasoning agent (15s latency, 2,500 tokens) vs AgentJIT compiled execution over 100 runs:

| Execution Mode | Mean Latency | 99th Percentile | Cost per 1k runs | Token Usage | Determinism |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Standard LLM Agent** | `14,820 ms` | `22,400 ms` | **\$75.00** | 2,500,000 | ~94% |
| **AgentJIT (Warm Path)** | **`0.08 ms`** | **`0.12 ms`** | **\$0.00** | **0** | **100%** |
| **Improvement** | **185,000x faster** | **186,000x faster** | **100% savings** | **Zero tokens** | **Rock-solid** |

---

## <a id="speculative-execution--bailouts"></a>🛡️ Speculative Execution & Bailouts

What happens when an input is unusual or triggers an unexpected branch?

AgentJIT uses **Speculative De-Optimization**:
1. Input variables are validated against synthesized guards.
2. If any guard fails (e.g. wrong type, missing required key) or a tool raises an unhandled exception, AgentJIT catches `GuardViolation`.
3. It seamlessly bails out to the dynamic LLM agent to handle the edge case.
4. Telemetry records the bailout for future multi-branch specialization.

```python
# Normal input: runs compiled pipeline in 0.08ms
checkout_agent("Monitor", 0.19)

# Divergent input (e.g. invalid type): automatically bails out to dynamic agent
checkout_agent(12345, None)  # Transparently de-optimizes, no crash!
```

---

## 🤖 Native Model Context Protocol (MCP) Server

AgentJIT provides a built-in **Model Context Protocol (MCP) Server** over JSON-RPC 2.0 stdio, empowering **Claude Desktop**, **Cursor**, **Windsurf**, and **Google Antigravity** to compile their own tool calling trajectories into deterministic Python functions on the fly.

### Quickstart

Launch the MCP server via CLI:
```bash
agentjit mcp
# or using the direct entry point:
agentjit-mcp
```

### Client Configuration

Add to your `claude_desktop_config.json`, `.cursor/mcp.json`, or Antigravity MCP settings:

```json
{
  "mcpServers": {
    "agentjit": {
      "command": "agentjit-mcp"
    }
  }
}
```

*Or zero-install with `uvx`:*
```json
{
  "mcpServers": {
    "agentjit": {
      "command": "uvx",
      "args": ["agentjit", "mcp"]
    }
  }
}
```

### Available MCP Tools

| Tool | Purpose | Annotations |
| :--- | :--- | :---: |
| `agentjit_compile` | Synthesizes deterministic Python code with input type guards from an agent tool trace. | `readOnlyHint: true` |
| `agentjit_analyze` | Analyzes DAG data-flow dependencies, identifying constant literals vs dynamic parameters. | `readOnlyHint: true` |
| `agentjit_simulate_savings` | Computes exact dollar cost and latency savings when compiling recurring LLM workflows. | `readOnlyHint: true` |
| `agentjit_info` | Returns runtime compiler capabilities, Free-Threaded (PEP 703 No-GIL), and PyPy JIT status. | `readOnlyHint: true` |

---

## 🛠️ Telemetry & Observability

Monitor your compiled agents in real time:

```python
print(checkout_agent.stats)
# Output:
# {
#     "total_calls": 1500,
#     "compiled_hits": 1492,
#     "bailouts": 8,
#     "compiled_hit_rate": 99.47,
#     "total_time_saved_ms": 22380000.0,
#     "total_tokens_saved": 3730000
# }
```

---

## 🗺️ Roadmap for 2026–2027

- [x] **Core Tracer & DAG Flow Analyzer**
- [x] **AST Code Generation with Speculative Guards**
- [x] **De-optimization / Bailout Runtime**
- [x] **`@jit` Decorator with Auto-Warmup**
- [ ] **Multi-Branch Polyhedral JIT:** Merge multiple execution paths into a unified control-flow graph (`if/else` branching synthesis).
- [ ] **eBPF-Isolated Micro-Sandbox:** Ultra-fast sub-millisecond process sandbox for compiled shell actions.
- [ ] **WebAssembly (Wasm) Export:** Compile agent trajectories into standalone Wasm binaries for browser and edge runtime.

---

## 🧪 Testing & Verification

AgentJIT includes a comprehensive test suite covering the Tracer, Flow Analyzer, AST CodeGen, Runtime Bailout, and End-to-End decorators:

```bash
uv run --extra dev pytest -v
# or with standard pytest
pytest -v
```

All 9 test suites pass 100% across **Python 3.8 through 3.16 (including No-GIL free-threaded 3.13t–3.16t)** and **PyPy 3.8 through 3.12**.

---

## 🌐 High-Performance Systems Ecosystem

`agentjit` is developed by [**@eminsk**](https://github.com/eminsk) as part of an open-source AI & systems engineering ecosystem:

* ⚡ [**NanoVector**](https://github.com/eminsk/nanovector) — Bare-metal C99/AVX2 vector search & episodic memory engine (~120KB) with Native MCP Server (`pip install nanovector`).
* ⚡ [**NanoGEMM**](https://github.com/eminsk/nanogemm) — Bare-metal AVX2+FMA SIMD matrix multiplication engine in ~100KB for sub-microsecond CPU inference (`pip install nanogemm`).
* 🖥️ [**NanoRecall**](https://github.com/eminsk/nanorecall) — 100% Private, offline desktop memory & semantic screen search engine powered by NanoVector (`pip install nanorecall`).
* 🛒 [**avito-sdk**](https://github.com/eminsk/avito-sdk) — Headless Avito scraping & data extraction SDK with price drop tracking, Playwright cookies, Telegram/VK bots, and Native MCP Server (`pip install avito-sdk`).
* 📈 [**yfinance-ta-patterns**](https://github.com/eminsk/yfinance-ta-patterns) — Institutional-grade technical pattern scanner with AI Confluence Scoring, Backtester, and Native MCP Server (`pip install yfinance-ta-patterns`).
* 📊 [**xlsx_vievers**](https://github.com/eminsk/xlsx_vievers) — Headless Excel formula engine (129+ functions), desktop spreadsheet viewer, SIMD SSE2 math, and Native MCP Server (`pip install xlsx-viewer-pro`).
* 🎥 [**screenvideo**](https://github.com/eminsk/screenvideo) — Desktop screen recorder with WASAPI audio and standalone pure x64 FASM edition.

---

## ☕ Support, Community & Donations

If you find this project valuable and would like to support ongoing development:

* ⭐ **Star the Repository**: If AgentJIT helps your AI agents run faster, give us a star on GitHub — it helps more developers discover the project!
* 💬 **Join Discussions**: Have ideas, use cases, or questions? Start or join a thread in [GitHub Discussions](https://github.com/eminsk/agentjit/discussions)!
* ☕ **Donate (USDT TRC-20)**:  
  `TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P`  
  *(Network: TRON / TRC-20 | [Verify on TronScan](https://tronscan.org/#/address/TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P))*

[![GitHub Repo stars](https://img.shields.io/github/stars/eminsk/agentjit?style=social)](https://github.com/eminsk/agentjit)
[![GitHub Discussions](https://img.shields.io/badge/Discussions-Join_Community-blue?logo=github&style=flat-square)](https://github.com/eminsk/agentjit/discussions)
[![Donate USDT](https://img.shields.io/badge/Donate-USDT_(TRC20)-26A17B?style=flat-square&logo=tether&logoColor=white)](https://tronscan.org/#/address/TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P)

---

## 📄 License

AgentJIT is open-source software licensed under the [Apache 2.0 License](LICENSE).
