Metadata-Version: 2.5
Name: avo
Version: 0.7.4
Summary: Reliable execution infrastructure for long-running AI agents.
Project-URL: Homepage, https://github.com/Fqih/avo
Project-URL: Repository, https://github.com/Fqih/avo
Project-URL: Issues, https://github.com/Fqih/avo/issues
Project-URL: Changelog, https://github.com/Fqih/avo/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/Fqih/avo#readme
Project-URL: Funding, https://github.com/Fqih/avo
Author-email: Fqih <mhmdfkih21@gmail.com>
Maintainer-email: Fqih <mhmdfkih21@gmail.com>
License: MIT License
        
        Copyright (c) 2026 FaqihHakim
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,llm,observable,reliability,resumable,runtime,sqlite,state-machine
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: prompt-toolkit>=3.0.43
Requires-Dist: pydantic<3,>=2.8
Provides-Extra: all
Requires-Dist: avo-native>=0.1.4; extra == 'all'
Requires-Dist: docker>=7.0; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: langchain-core>=0.3; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: opentelemetry-api>=1.27; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'all'
Provides-Extra: dev
Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
Requires-Dist: hatchling>=1.26; extra == 'dev'
Requires-Dist: keyring>=25.0; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.8; extra == 'docs'
Provides-Extra: keyring
Requires-Dist: keyring>=25.0; extra == 'keyring'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: live-benchmark
Requires-Dist: httpx>=0.27; extra == 'live-benchmark'
Requires-Dist: matplotlib>=3.8; extra == 'live-benchmark'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: native
Requires-Dist: avo-native>=0.1.4; extra == 'native'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
Provides-Extra: providers
Requires-Dist: httpx>=0.27; extra == 'providers'
Provides-Extra: sandbox
Requires-Dist: docker>=7.0; extra == 'sandbox'
Provides-Extra: security
Requires-Dist: cryptography>=43; extra == 'security'
Provides-Extra: standalone
Requires-Dist: pyinstaller>=6.10; extra == 'standalone'
Description-Content-Type: text/markdown

<div align="center">

<img src="logo.png" width="160" height="160" alt="Avo logo">

# Avo

**Enterprise-Grade AI Agent Infrastructure with Zero-Downtime Multi-Tier Redundancy & Cost Optimization**

*Eliminate developer idle time, mitigate AI vendor lock-in, and slash enterprise token expenditures across your engineering organization.*

[![Status: Alpha](https://img.shields.io/badge/status-v0.7.3--alpha-orange.svg)](https://avo.faqihhakim.tech/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Security: Sandboxed](https://img.shields.io/badge/security-sandboxed--ephemeral-indigo.svg)](https://avo.faqihhakim.tech/)
[![Documentation](https://img.shields.io/badge/docs-avo.faqihhakim.tech-purple.svg)](https://avo.faqihhakim.tech/)

</div>

---

## Executive Summary

Modern engineering teams increasingly rely on AI coding assistants for software delivery. However, conventional single-vendor tools introduce severe operational vulnerabilities: **HTTP 429 quota exhaustion**, **cloud provider outages**, **unpredictable monthly token invoices**, and **uncontrolled code execution risks**.

**Avo** is an open-source, multi-tier autonomous AI agent runtime engineered for uninterrupted software engineering workflows. By unifying enterprise cloud account quotas, pay-as-you-go fallbacks, and zero-cost local hardware inference behind a resilient state machine, Avo guarantees that mission-critical development never halts.

---

## The Business Problem vs. The Avo Solution

| Business Challenge | Industry Impact | The Avo Strategic Solution |
|---|---|---|
| **Vendor Quota Halts & 429 Limits** | Developer workflows crash mid-refactor; context is permanently lost; engineering velocity drops. | **Zero-Drop Failover:** Automated provider hot-swap in milliseconds while preserving 100% conversation memory. |
| **Exploding Cloud Token Invoices** | Repetitive context ingestion and multi-turn audits rapidly burn budget on enterprise models. | **Integrated Token Savers:** Deterministic prompt minification and tool deduplication reduce token consumption by up to 26%+ (benchmarked). |
| **Vendor Lock-In & Outage Vulnerability** | Teams are tied to a single AI vendor's pricing models, service availability, and terms. | **Multi-Tier Redundancy:** Fluid routing across Anthropic, OpenRouter, Google, and on-premise models. |
| **Compliance & Code Tampering Risks** | Unrestricted AI tool loops may overwrite production assets or escape directory bounds. | **Defense-in-Depth:** Ephemeral sandbox isolation, strict POSIX file boundaries, and immutable audit logs. |

---

## Strategic Architecture

### 1. Cost-Optimized Multi-Tier Routing (Combo Pipeline)

Avo eliminates single-point-of-failure risks by cascading model execution through cost-prioritized operational tiers. When a primary cloud provider reaches rate limits or encounters latency spikes, requests transition down the tier hierarchy seamlessly.

```mermaid
flowchart TD
    User["Engineering Team Request"] --> Router["Avo Intelligent Router"]
    
    subgraph Tier1["Tier 1: Enterprise Account Quota (High Reasoning)"]
        Claude["Frontier Models (Claude / Codex / Gemini)"]
    end

    subgraph Tier2["Tier 2: Pay-Per-Token Fallback (Cost Efficient)"]
        OpenRouter["Cloud Aggregate Models (Llama 70B / DeepSeek)"]
    end

    subgraph Tier3["Tier 3: Local Hardware Floor (Zero Cost & Private)"]
        LocalLLM["Local Acceleration (Ollama Qwen Coder via ROCm / CUDA)"]
    end

    Router --> Claude
    Claude -- "HTTP 429 / Quota Halt" --> OpenRouter
    OpenRouter -- "Network Outage / Timeout" --> LocalLLM
    
    Claude --> Success["Completed Development Task"]
    OpenRouter --> Success
    LocalLLM --> Success
```

---

### 2. Multi-Agent Collaborative Governance

Complex software delivery requires segregation of duties. Rather than relying on a single monolithic prompt, Avo orchestrates specialized subagents to enforce architectural compliance before implementation begins.

```mermaid
flowchart LR
    Goal["Business Initiative"] --> Architect["@architect Agent (System Design)"]
    Architect --> Spec["Architecture Plan & Concurrency Audit"]
    Spec --> Coder["@coder Agent (Implementation)"]
    Coder --> Sandbox["Isolated Ephemeral Sandbox"]
    Sandbox --> Test["Automated Regression Verification"]
    Test --> Ledger["Durable SQLite Audit Ledger"]
    Ledger --> Telemetry["Real-Time Web UI Dashboard"]
```

---

## Core Business Pillars

### 📊 1. Measurable ROI & Financial Governance
- **Deterministic Token Reduction:** Automatically minifies tool JSON payloads, deduplicates redundant outputs, and elides verbose lines, reducing token consumption by up to **26%+** on long tool-heavy sessions (see [benchmark results](benchmark/savers/RESULTS.md)).
- **Tiered Spending Caps:** Organizations leverage free or pre-paid enterprise quota first, spill over to fractional-cent pay-as-you-go providers second, and maintain a zero-cost local compute floor as the final safety net.
- **Granular Cost Transparency:** View exact per-turn and aggregate expenditures categorized by provider tier directly within the operational ledger.

### 🛡️ 2. Business Continuity & High Availability
- **Mid-Turn State Preservation:** When an upstream vendor encounters service degradation, Avo migrates pending turns to alternate providers without requiring developers to restart their session.
- **On-Premise Hardware Autonomy:** Automated hardware discovery configures local GPU accelerators (AMD ROCm, NVIDIA CUDA, Apple Metal) so core coding loops remain operable even during complete internet connectivity loss.

### 🔒 3. Enterprise Security & Audit Compliance
- **POSIX Boundary Containment:** Strict POSIX path resolution with `O_NOFOLLOW` symlink containment blocks directory traversal, null-byte poisoning, and symlink replacement attacks.
- **Containerized Isolation:** Code execution operates within disposable, ephemeral Docker sandboxes with disabled external networking and dropped capabilities by default.
- **Immutable SQLite Ledger:** Every prompt, decision boundary, tool mutation, and model switch is stored chronologically for compliance review and security auditing.

### ⚡ 4. Operational Observability (Avo Web UI)
- **Real-Time Operational Cockpit:** Visual telemetry dashboard displaying live trace timelines, model latency meters, circuit breaker triggers, and local hardware configuration.
- **Extensible Enterprise Plugins:** Seamless integration with company-internal ticketing systems, GitHub pull request automation, and incident alert channels via standard extension points.

---

## Enterprise Capability Overview

```mermaid
graph TD
    subgraph ControlPlane["Unified Control Plane"]
        CLI["Terminal CLI Agent"]
        WebUI["Web Observability Dashboard"]
    end

    subgraph ResilienceEngine["Resilience Engine"]
        ComboEngine["Combo Multi-Tier Router"]
        FailoverState["Zero-Drop State Machine"]
        CacheStore["Semantic Token Savers"]
    end

    subgraph SecurityShield["Security & Audit Shield"]
        PosixGuard["POSIX O_NOFOLLOW Path Guard"]
        DockerBox["Ephemeral Sandbox Isolation"]
        SqliteLedger["Immutable Event Ledger"]
    end

    ControlPlane --> ResilienceEngine
    ResilienceEngine --> SecurityShield
```

---

## Platform Deployment & Governance

Avo is engineered as a lean, dependency-minimal binary with self-contained runtime management. It adapts automatically to developer workstations, cloud virtual machines, and restricted air-gapped environments without requiring administrative overhead.

For enterprise deployment guides, architectural whitepapers, compliance specifications, and CLI references, visit the official documentation portal:

👉 **[Explore Full Documentation & Guides at avo.faqihhakim.tech](https://avo.faqihhakim.tech/)**

---

## License & Attribution

Avo is open-source software distributed under the **MIT License**. Maintained and authored by **Fqih**.
