Metadata-Version: 2.4
Name: capybala
Version: 0.9.2
Summary: Context-Aware Pruning for Yielding & Backtrack-Aligned Loop Avoidance: The chill, self-healing runtime that cures autonomous AI agents from cognitive deadlocks.
Author-email: Khairan Noor Fadhlillah <khairan.noor.f@students.esqbs.ac.id>
Project-URL: Homepage, https://github.com/codesbykhairannoor/capybala
Project-URL: Preprint Paper, https://doi.org/10.21203/rs.3.rs-11597011/v1
Project-URL: Benchmark Dataset, https://www.kaggle.com/datasets/khairan7/ai-agent-cognitive-deadlock-benchmark/data
Project-URL: Live Interactive Demo, https://capybala.onrender.com
Project-URL: Bug Tracker, https://github.com/codesbykhairannoor/capybala/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: llama-stack
Requires-Dist: llama-stack-client; extra == "llama-stack"
Provides-Extra: langchain
Requires-Dist: langchain-core; extra == "langchain"
Provides-Extra: all
Requires-Dist: llama-stack-client; extra == "all"
Requires-Dist: langchain-core; extra == "all"
Dynamic: requires-python

<p align="center">
  <img src="https://raw.githubusercontent.com/codesbykhairannoor/capybala/main/web/static/img/capybala-logo.png" width="180" alt="Capybala Logo">
</p>

# 🦫 `capybala` (v0.9.2)

**C**ontext-**A**ware **P**runing for **Y**ielding & **B**acktrack-**A**ligned **L**oop **A**voidance  
*High-Speed, Zero-Dependency Cognitive Deadlock & Oscillation Interceptor for Autonomous AI Coding Agents.*

[![PyPI Version](https://img.shields.io/badge/version-0.9.2-blue.svg)](https://pypi.org/project/capybala/)
[![Python Versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://pypi.org/project/capybala/)
[![DOI](https://img.shields.io/badge/DOI-10.21203%2Frs.3.rs--11597011%2Fv1-blue.svg)](https://doi.org/10.21203/rs.3.rs-11597011/v1)
[![Preprint](https://img.shields.io/badge/Research_Square-Preprint-green.svg)](https://www.researchsquare.com/article/rs-11597011/v1)
[![Tests](https://img.shields.io/badge/tests-95%20passed-brightgreen.svg)]()
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20(pure%20std%20lib)-success.svg)]()
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

---

## ⚡ The Problem: Cognitive Deadlocks & Cache Invalidation

When an autonomous coding agent (Google DeepMind Gemini 4 Argon, Anthropic Claude Sonnet 5.5, OpenAI GPT-5.4, Meta Llama 4 Scout, DeepSeek-V3) gets stuck in complex codebases:
1. **It loops cyclically**: Repeating the exact same failing command, alternating between broken patches (A ↔ B), or getting trapped in paraphrased search loops (`grep` vs `find`).
2. **Context window floods**: Accumulates 15,000+ tokens of identical traceback spam and negative observations.
3. **Prompt cache invalidation**: Naive middle-context pruners mutate historical messages, breaking Anthropic/OpenAI prompt prefix hashes and destroying the **90% prompt cache discount**.
4. **Infinite Healing Loops**: The agent repeatedly fails, receives naive error echoes, and burns through hundreds of dollars in API credits.

Existing libraries merely detect loops after dozens of failures and terminate the agent (`raise RuntimeError`).  
**`capybala` intercepts loops in sub-milliseconds, performs cache-preserving atomic rollbacks, injects grounded doctor guidance, and keeps the agent alive to finish the job.**

---

## 🏗️ Architecture: Two-Tier Detection Hierarchy

Capybala uses a stratified, two-tier detection engine that applies the optimal algorithmic complexity for each class of agent loop:

```mermaid
flowchart TD
    A["Agent Tool Action & Environment Feedback"] --> C["Canonical Action Normalizer\n(grep ↔ find|xargs ↔ rg)"]
    C --> T1{"Tier 1: Bounded Ring-Buffer Matcher"}
    T1 -- "Exact Repetition / 2-Period Oscillation / SHA Match" --> D1["Intercept in O(1) Time (< 0.01 ms)\nPattern: EXACT_CYCLE"]
    T1 -- "No Exact Match" --> T2{"Tier 2: Lexical Trajectory Engine"}
    T2 -- "Directional Velocity < 0.70 / Low Entropy / Intent Match" --> D2["Intercept in < 0.8 ms\nPattern: LEXICAL_ATTRACTOR"]
    T2 -- "Forward Trajectory Progress" --> OK["Pass Through\nTurn Progression Healthy"]
    D1 --> R["Cache-Preserving Context Rollback & Doctor Guidance"]
    D2 --> R
```

### 1. Tier 1: Bounded Ring-Buffer Cycle Matcher ($O(1)$, $< 0.01$ ms)
- **Ring-Buffer Cycle Verification**: Examines 16-byte SHA-256 action hash ring buffers to catch direct command repetitions ($A \to A \to A$), 2-period oscillations ($A \to B \to A \to B$), period-3/4 loops, and multi-agent delegation ping-pong in $< 10$ microseconds.
- **Zero Heap Overhead**: Fixed-size circular deque storage prevents memory retention leaks during long-running sessions.

### 2. Tier 2: Continuous Lexical Trajectory Velocity ($< 0.8$ ms)
- **Subword N-Gram Unit Sphere Projection**: Uses 1024-dimensional feature hashing (Weinberger et al., *ICML 2009*) combining semantic tokens and character 3-gram shingles to map agent trajectories without PyTorch or NumPy.
- **Canonical Action Intent Normalization**: Normalizes disparate command syntaxes into unified semantic intents (e.g. `grep -rn 'UserModel' src/` and `find src/ -name '*.py' | xargs grep 'UserModel'` both resolve to `INTENT:SEARCH query='usermodel' path='src/'`), eliminating syntax evasion in fuzzy loops.
- **Embedding Directional Velocity**: Tracks vector trajectory change $v_t = 1 - \cos(\mathbf{u}_t, \mathbf{u}_{t-1})$. Persistent stagnation below velocity threshold with low Markov transition entropy intercepts paraphrased exploration loops.

---

## 🚀 The 1-Line Developer Experience

### 1. Drop-In Client Wrapper (Sync & Async)
Zero modifications to your agent loop. Wrap your client and you're protected:

```python
from openai import OpenAI
import capybala as cb

# Explicit, type-safe, zero global side-effects:
client = cb.watch(OpenAI())

# Use client exactly as you always do (including stream=True!):
response = client.chat.completions.create(
    model="gemini-4-argon",  # Or "claude-sonnet-5.5", "gpt-5"
    messages=messages
)
```

#### Also Works Flawlessly with `AsyncOpenAI` & `AsyncAnthropic`:
```python
from openai import AsyncOpenAI
import capybala as cb

# Preserves inspect.iscoroutinefunction() and offloads CPU passes:
async_client = cb.watch(AsyncOpenAI())

response = await async_client.chat.completions.create(
    model="claude-sonnet-5.5",
    messages=messages
)
```

When an agent enters an infinite loop, Capybala intercepts it and prints the **Flight Recorder** to stderr:

```text
─────────────────────────────────────────────────────────────────
🦫  Capybala Cycle Intercepted [Tier 1 Exact Cycle: pytest tests/test_core.py]
 ├── Cycle Length: 2 turns | Recovered: ~3,200 tokens (~$0.019)
 ├── Cache Telemetry: 8,450 / 9,100 tokens cached (92.8% hit rate)
 └── Resolution:   Atomic Rollback + Grounded Reflection Injected
─────────────────────────────────────────────────────────────────
```

### 2. Enterprise Shadow Mode (`shadow_mode=True`)
For enterprise engineering teams wanting zero-risk observability before enabling active rollbacks:

```python
import capybala as cb
from openai import OpenAI

# Shadow mode: monitors and logs deadlocks without mutating messages or interrupting traffic
client = cb.watch(OpenAI(), shadow_mode=True)
```

In shadow mode, Capybala outputs:
```text
─────────────────────────────────────────────────────────────────
🦫  [SHADOW MODE] Capybala Cycle Intercept Candidate [pytest tests/test_core.py]
 ├── Cycle Length: 2 turns | Estimated Waste: ~3,200 tokens (~$0.019)
 ├── Detection Tier: tier1_exact | Policy: Shadow Audit (No Context Mutated)
 └── Resolution:   Audit Logged for Review (Zero-Risk Execution)
─────────────────────────────────────────────────────────────────
```

### 3. Cache-Preserving Rollback (`cache_preserving=True`)
Modern LLM APIs (Anthropic Claude, OpenAI) provide up to a 90% prompt cache discount on preserved prompt prefixes. Capybala's `rollback_and_reflect()` operates strictly on the suffix, leaving historic prefix messages byte-for-byte identical:

```python
import capybala as cb

pruner = cb.ContextPruner()
result = pruner.rollback_and_reflect(
    messages=messages,
    failing_action="python -m pytest tests/test_auth.py",
    deadlock_details="2-step oscillating circular dependency",
    rollback_turns=4,
    cache_preserving=True  # Preserves prefix cache hit rate
)

messages = result.pruned_messages
print(f"Tokens saved: {result.tokens_saved_estimate} | Cache preserved: {result.cache_preserved}")
```

### 4. Pure Functional 1-Liner (For Custom Agent Frameworks)
```python
import capybala as cb

# In-place mutation guarantees developer outer history lists never experience Ghost Desync:
messages = cb.heal(messages)
```

---

## 🛡️ Production Invariant Guarantees (v0.9.1)

| Production Hazard | Naive Loop Breakers | `capybala` v0.9.1 Guarantee |
| :--- | :---: | :---: |
| **Enterprise Adoption Risk** | Active mutation frightens production teams | **Enterprise Shadow Mode**: Run `shadow_mode=True` for passive observability with zero context changes. |
| **Prompt Cache Invalidation** | Rewrites ancient messages, busting Anthropic/OpenAI prompt cache | **Cache-Preserving Prefix Rollback**: Truncates suffix only; keeps historical prefixes 100% byte-for-byte identical. |
| **Cross-Syntax Evasion (`grep` vs `find`)** | Lexical shingles miss equivalent commands | **Canonical Action Normalizer**: Unifies diverse command syntaxes into standardized operational intents. |
| **Two-Tier Cycle Detection** | Slow regex scans or missed paraphrased loops | **Two-Tier Engine**: $O(1)$ Bounded Ring-Buffer Matcher ($<0.01$ ms) + Sub-millisecond continuous lexical trajectory ($<0.8$ ms). |
| **Infinite Healing Loops (Meta-Deadlocks)** | Blindly heals forever, burning thousands of dollars | **Autonomous Circuit Breaker**: Halts infinite healing loops after `max_interventions=5` (`DeadlockEmergencyStop`). |
| **Volatile Dynamic Arguments** | Hashes raw args; blinded by changing timestamps/nonces | **JSON Key Sanitizer**: Strips volatile fields (`timestamp`, `nonce`, `request_id`) and canonicalizes JSON dicts. |
| **Autoregressive Reflection Echo** | Static reflection becomes an attractor token loop | **Progressive Escalation Healer**: Levels 1, 2, 3+ escalate from local diagnostics to radical hypothesis resets. |
| **Streaming Completions (`stream=True`)** | Breaks generators and crashes chunk streaming | **Streaming Generator Passthrough**: Preserves chunk streaming and async generators without disruption. |
| **Anthropic Role Alternation** | Injects back-to-back user messages; triggers `400 Bad Request` | **Strict Claude Role Hygiene**: Merges guidance into existing user turns; strictly maintains turn alternation. |
| **AsyncIO Event Loop Starvation** | Stalls main loop with heavy regexes; strips coroutine flags | **Async-Native Offloading**: Preserves `iscoroutinefunction`, offloads CPU work via `asyncio.to_thread`. |
| **Ghost Pruning Desync** | Returns new list while developer's outer loop keeps old bloated list | **In-Place Mutation**: `messages[:] = clean_history` synchronizes caller state automatically. |
| **Memory Leaks in Ring Buffers** | Stores raw strings, pinning 800MB+ in RAM per agent | **Zero Memory Pinning**: Stores 16-byte SHA digests and bounds regex passes to 32KB. |
| **OpenAI Parallel Tool Calls** | Splits message, triggers fatal `400 Bad Request` | **Atomic Checkpoint Rollback**: Never separates `tool_calls` from paired `tool` responses. |
| **Legitimate Polling** | Kills `curl /health`, `kubectl`, `ps aux` after 3 runs | **Dynamic Polling Exemption**: Whitelists waiting and status commands. |

---

## 📊 Verification & Empirical Benchmarks

Validated against 200 real **SWE-bench Deadlock Trajectories** (`AnalogJ`, `PyTorch Lightning`, etc.) and live stress-tested with frontier models (Google DeepMind Gemini 4 Argon, Meta AI `muse-spark-1.3`, Claude Sonnet 5.5):
- **100.0% Recall** on repetitive cognitive deadlocks ($\ge 3$ turns).
- **0.0% False Positive Rate** on exploratory Git operations and healthy polling.
- **78.8% Token Waste Prevented** per session across benchmark dataset.
- **< 0.01 ms Tier 1 Latency / < 0.8 ms Tier 2 Latency** (100% pure Python standard library, 0 external dependencies).

---

## 📚 Academic Research & Citation

Capybala's architecture is grounded in peer-reviewed research across autonomous agent failure analysis, high-dimensional phase-space manifolds, and attention degradation:
- **Phase-Space Manifolds**: Grounded in Weinberger et al. (*ICML 2009*) feature hashing trick ($O(1)$ memory, sub-millisecond trajectory projection).
- **Agent Failure Taxonomies**: Evaluated against real failure modes documented in Xia et al. (*ACM PACMSE/FSE 2025*) and Jimenez et al. (*ICLR 2024 SWE-bench*).
- **Attention & Context Degradation**: Pruning rules formulated to eliminate U-shaped retrieval degradation identified by Liu et al. (*TACL 2024*).

See [**`RESEARCH_REFERENCES.md`**](RESEARCH_REFERENCES.md) for the complete, 100% Crossref-verified bibliography with active DOI and Open Access PDF links.

### 📄 How to Cite

If you use Capybala, its 200-trajectory benchmark dataset, or its phase-space manifold formulation in your research, please cite our official paper preprint:

> **CAPYBALA: Context-Aware Pruning for Yielding and Backtrack-Aligned Loop Avoidance in Autonomous Software Engineering Agents**  
> Khairan Noor Fadhlillah  
> *Research Square (Springer Nature)*, 2026.  
> DOI: [`10.21203/rs.3.rs-11597011/v1`](https://doi.org/10.21203/rs.3.rs-11597011/v1) | [Preprint PDF](https://www.researchsquare.com/article/rs-11597011/v1)

```bibtex
@article{fadhlillah2026capybala,
  title={{CAPYBALA: Context-Aware Pruning for Yielding and Backtrack-Aligned Loop Avoidance in Autonomous Software Engineering Agents}},
  author={Fadhlillah, Khairan Noor},
  journal={Research Square},
  year={2026},
  month={nov},
  doi={10.21203/rs.3.rs-11597011/v1},
  url={https://doi.org/10.21203/rs.3.rs-11597011/v1}
}
```

---

## 📜 License
Apache-2.0 License. Built for the Meta Global AI Developer Hackathon 2026.
