omniagent-fleet 0.1.4__tar.gz

omniagent_fleet-0.1.4/CHANGELOG.md

@@ -0,0 +1,296 @@
+# Changelog
+
+All notable changes to OmniAgent are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+OmniAgent adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.1.4] — 2026-06-02 — *The Private Fleet*
+
+**Multi-machine orchestration. Same engine, now fleet-aware.**
+
+This release ships the building blocks of Private Fleet v0: a per-machine HTTP node and a fleet coordinator that registers nodes, queries their live offers, and routes tasks to the best one. This is the trusted-owner-only foundation that the public distributed compute mesh will sit on top of.
+
+### Added
+
+#### `omniagent node start` — per-machine HTTP server
+- FastAPI app with 4 endpoints: `GET /health`, `GET /offer`, `GET /models`, `POST /generate`
+- Reuses the existing `ResourcePublisher`, `OllamaManager`, and `SmartRouter` — zero new abstractions
+- Listens on `:8766` by default (`--port` and `--host` configurable)
+- `python -m node start --port 8766` for the standalone path
+- Each `ResourceOffer` is the existing dataclass, JSON-serializable, with the same `models_supported` and `trust_score` fields
+
+#### `omniagent fleet <subcommand>` — fleet coordinator
+- `add <url>` — register a remote node (verifies via `/health` first)
+- `list` — show registered nodes (offline view, no network)
+- `remove <node_id>` — unregister a node
+- `status` — query all nodes live, show a table (OS, tier, free VRAM, free RAM, models, latency)
+- `route "task" --budget 0.01` — query all online nodes, pick the best (most free VRAM, lowest CPU util), execute the task there, return the result
+- `benchmark --tasks 5 --output report.md` — run N benchmark tasks across the fleet, measure cost + latency, write a markdown report (the Ferrari demo)
+- Storage: `~/.omniagent/fleet/registry.json`
+
+#### Routing logic
+- Fleet router queries all online nodes in parallel (sequential for v0)
+- Picks the best node by: most free VRAM, then lowest CPU util, then trust score
+- Falls through to lower-priority nodes if the best one fails
+- Records job completion on the chosen node (success/failure counters)
+
+### Tests
+- **367 unit tests** + **7 integration tests** = **374 passing, 2 skipped** (Docker daemon)
+- **+10 new tests**:
+  - `test_node_server.py` (6): health, offer, models, generate validation, routes
+  - `test_fleet_registry.py` (4): add+list, replace, remove, persistence roundtrip
+- **0 regressions** in existing 357 tests
+
+### Deferred (NOT in this release)
+- The public mesh: strangers' machines, payments, marketplace, reputation — explicitly out of scope
+- mDNS auto-discovery: still requires manual `omniagent fleet add <url>`
+- TLS / auth: trusted local network only
+- Cross-node load balancing: v0 picks ONE node per task
+
+---
+
+## [0.1.3] — 2026-06-02 — *The Visibility Layer*
+
+**The same engine, finally visible. No new features, just clarity.**
+
+This release turns the existing codebase into something a non-dev can understand in 5 seconds. The Python engine is unchanged. The README, the landing pages, and the URL references are the only things that moved.
+
+### Added
+
+#### README.md (full rewrite, 216 lines)
+- **Hero**: "You are overspending on AI." — direct, factual, hook
+- **Killer demo table** (right under the hero): 4 concrete examples with measured savings
+  - Review 5,000-LOC PR: $2.81 → $0.07 (−97.5%)
+  - Write 200 docstrings: $0.42 → $0.002 (−99.5%)
+  - Refactor rename: $1.10 → $0.00 (−100%, local)
+  - Design distributed system: $1.50 → $1.50 (0%, Claude is the right tool)
+- **"Saved this week on a typical dev setup: 96.2%"** as the bottom line
+- **4 façades** (one engine, four ways to use it): CLI, Web, YAML, MCP
+- **90/9/1 design philosophy**: dashboard is the product, YAML is the protocol, CLI is the power tool
+- **How it works** section: 8-step pipeline from task to LLM call to cost tracking
+- **60-second quickstart** (git clone → pip install → omniagent web)
+- **Updated roadmap**: AI Infrastructure OS (shipped) → Optimization Layer (next) → Visual Dashboard → Distributed Compute (deferred) → Marketplace (deferred)
+- Mixed audience (devs + founders) with sections clearly separated
+
+#### landing/wow.html (polished)
+- "You are overspending on AI." hook above the existing hero
+- New static **killer demo table** inserted BEFORE the interactive example
+  - Same 4 examples as the README, visually consistent
+  - "Saved this week: −96.2%" as the bottom line
+- Same dark theme, no dependencies
+
+#### landing/index.html (polished)
+- Same "You are overspending on AI." hook
+- Cross-link to wow.html for the interactive demo
+- Updated H1: "How much could you save?"
+
+### Changed
+- **All 15 references** to `github.com/anomalyco/omniagent` now point to `github.com/landrover1984/omniagent` (README, CHANGELOG, both landing pages, web UI, POSTS template)
+
+### Stats
+- **364 unit tests** + **7 integration tests** = **371 passing, 2 skipped** (Docker daemon)
+- **6 files changed**, **+294 lines**, **−149 lines**
+- **0 new dependencies** required
+
+---
+
+## [0.1.2] — 2026-06-02 — *The Run Button*
+
+**From "decide" to "do" in one click. The CLI and web now execute end-to-end.**
+
+This patch closes the loop. Before, you could see the routing decision (`agent-decide` / `/api/decide`); now you can also run the task end-to-end and get the actual LLM response back — same call, same agent, same model, same cost tracking.
+
+### Added
+
+#### CLI: `omniagent agent-route`
+- **Full end-to-end**: `decide` + `execute` in a single command
+- Flags: `--budget` (USD cap), `--agent` (force agent), `--show-decision` (print routing before running), `--json` (raw response for piping)
+- Output: a panel with the model's actual text + cost + token counts + latency
+- Example: `omniagent agent-route "review this code for security" --budget 0.10 --show-decision`
+
+#### Web: `POST /api/route` + new "Run it ▶" button
+- Same decision + execution in one HTTP call
+- The Try It tab now has two buttons: **Route this →** (decide only, free) and **Run it ▶** (decide + execute, costs money)
+- Result panel shows the actual generated text with cost/tokens/latency in a monospace meta line
+
+### Fixed
+- **Test `test_router_generate_uses_first_provider`**: was asserting `len(records) == 1` against a global `CostTracker` singleton, so any other test that ran `router.generate(...)` first broke it. Now snapshots the count and asserts `before + 1`. No more order-dependence.
+
+### Stats
+- **364 unit tests** + **7 integration tests** = **371 passing, 2 skipped** (Docker daemon)
+- **+3 new tests**: `test_agent_route_review_show_decision`, `test_agent_route_json_output`, `test_agent_route_no_providers`
+- **+1 new endpoint** in the web (`/api/route`)
+
+---
+
+## [0.1.1] — 2026-06-02 — *The Visual Layer*
+
+**The same brain, now visible. No more terminal-only.**
+
+This release adds the web UI layer that makes OmniAgent understandable for non-devs. The Python engine is unchanged — the web app is a thin HTTP wrapper around the same CLI commands.
+
+### Added
+
+#### Web UI: `omniagent web` (new!)
+- **`omniagent web`** starts a local FastAPI server on `http://localhost:8765` (configurable via `OMNIAGENT_WEB_PORT`)
+- **5 tabs** in `web/static/index.html`:
+  - **Try It** — type any task, see which agent + model gets picked (real `AdaptiveRouter` decision, no LLM call)
+  - **Agents** — visual cards for all 3 built-in agents, click to see full YAML
+  - **Hardware** — your detected GPU/CPU/RAM/tier, plus models you can run locally
+  - **Sandbox** — test any command against the 3 sandbox policies
+  - **Optimize** — the killer feature: see cost-saving suggestions, apply with one click
+- **12 endpoints** in `web/server.py` that wrap the existing CLI 1:1
+- **Process-wide singleton** for `AdaptiveRouter` so the server doesn't re-detect hardware on every request
+- **30s TTL cache** for `compute.detector` (Windows `psutil.disk_partitions` can take 30+ seconds on machines with stale network drive mappings)
+
+#### Optimize Tab: cost transparency that pays for itself
+- **`/api/optimize`** returns a list of cost-saving suggestions
+  - **Hybrid data source**: real telemetry if `~/.omniagent/telemetry.jsonl` exists, else 3 demo suggestions
+  - Shows: agent, current model + cost, suggested model + cost, monthly savings, risk level, reason
+- **`/api/optimize/apply`** creates a **new** agent YAML (`{name}-optimized.yaml`) in the user dir
+  - **Never overwrites** the original — user can compare, then disable the original if they want
+  - Returns the path + a copy-paste command to test the new agent
+
+#### Landing: `landing/wow.html` (the viral piece)
+- Single HTML file, no server, no build
+- "Stop spending $500/month on AI coding tools" hook
+- 4 pre-loaded examples with realistic routing traces (animated)
+- Side-by-side: "All-Claude $X.XX" vs "OmniAgent $0.YY" with savings %
+- 4 share buttons: Twitter, LinkedIn, Hacker News, Copy link
+- Guardian++ callout in every trace
+- Energy estimate: "≈ 0.4 kWh local · vs ≈ 4.1 kWh all-cloud"
+
+### Fixed
+- **`compute.detector`**: removed `temperature.gpu` and `power.draw` from `nvidia-smi` query (those fields intermittently hang on Windows; 5 fields left are enough for routing decisions)
+- **`compute.detector`**: added 30s TTL cache to avoid 30+ second hangs from `psutil.disk_partitions` on Windows hosts with network drive mappings
+- **`compute.detector`**: disabled disk detection by default (was the main source of the 30s hang); can be re-enabled behind a flag
+- **`compute.detector`**: wrapped every detect step in try/except so one failure can't kill the whole detection
+- **`ollama_manager.is_running`**: timeout 30s → 2s; added `TimeoutException` and broad `Exception` catch
+- **Test `test_compute_share_with_no_offers`**: was using `monkeypatch.setattr(config, "settings", ...)` but `compute.publisher` imports `settings` by name, so the patch didn't reach it. Now patches both `config.settings` and `publisher.settings`
+
+### Stats
+- **354 unit tests** + **7 integration tests** = **361 passing, 2 skipped** (Docker daemon)
+- **+15 new endpoints** exposed via web (12 functional + 3 docs)
+- **0 new dependencies required** for the user (FastAPI/uvicorn were already installed)
+- **0 telemetry** by default
+
+---
+
+## [0.1.0] — 2026-06-01 — *The Coordination Layer*
+
+**First public release. The AI Infrastructure OS is alive.**
+
+OmniAgent is no longer just a multi-agent orchestrator. It is the **coordination layer** for the entire AI ecosystem — models, agents, hardware, costs, and security. This release ships the brain: `AdaptiveRouter`, the `Agent Protocol`, and the YAML agent registry.
+
+### Added
+
+#### Core: Agent Protocol
+- **`AgentSpec`** — declarative dataclass for YAML-defined agents
+- **`load_agent_from_yaml` / `load_agent_from_dict`** — strict validation (missing keys, invalid categories, empty prompts, wrong types)
+- **`render_user_prompt_safe`** — safe templating with empty-string fallback for missing variables
+- **`AgentRegistry`** — discover + install + uninstall agents
+  - Priority order: `project` > `user` > `builtin`
+  - User agents in `~/.omniagent/agents/*.yaml`
+  - Built-ins in `omniagent/agents/registry/builtin/`
+  - Override built-ins by installing same-named YAML in your project
+- **3 built-in YAML agents**: `architect`, `developer`, `reviewer`
+
+#### Core: Task Classification
+- **`TaskClassifier`** — 10 categories (`code_simple`, `code_complex`, `reasoning`, `generation`, `review`, `testing`, `documentation`, `embeddings`, `translation`, `summarization`)
+- Detects complexity: `trivial`, `simple`, `medium`, `complex`, `extreme`
+- Detects required capabilities: `vision`, `function_calling`
+- Confidence score + matched keyword reporting
+
+#### Core: AdaptiveRouter (the brain)
+- **`AdaptiveRouter.decide(task, budget_usd)`** — single decision point that picks:
+  - the right **agent** (from registry)
+  - the right **model** (from SmartRouter)
+  - on the right **hardware** (from ResourceDetector)
+  - under the right **cost ceiling** (from user/agent budget)
+- Returns `RoutingDecision` with full reasoning trail
+- **`AdaptiveRouter.execute(decision, task)`** — actually runs the LLM call
+
+#### CLI: agent commands
+- `omniagent agent-list` — table view of all available agents
+- `omniagent agent-show <name>` — full YAML inspection
+- `omniagent agent-install <path>` — install with optional `--name` override
+- `omniagent agent-classify <task>` — see how a task is classified
+- `omniagent agent-decide <task> --budget 0.10` — see the routing decision (no LLM call)
+
+#### Documentation
+- **`docs/agents.md`** — comprehensive guide to writing your own agent in 5 minutes
+  - Minimal example, full schema, 10 categories, 4 quality tiers
+  - 3 real-world examples (local reviewer, cloud architect, translator)
+  - Install, manage, test, share workflows
+
+#### Tests
+- **+65 new tests** for Agent Protocol (354 unit + 7 integration = **361 total passing**, 2 skipped)
+- `test_agent_protocol_spec.py` — 18 tests: validation, loading, rendering, built-in loading
+- `test_agent_registry.py` — 12 tests: discover, list, install, uninstall, override
+- `test_task_classifier.py` — 20 tests: all 10 categories, complexity, vision/function-calling detection
+- `test_adaptive_router.py` — 8 tests: routing decisions, force-agent, GPU vs no-GPU, budget clamping
+- `test_cli_agent.py` — 7 tests: end-to-end CLI commands
+
+### Fixed
+- **`SandboxPolicy` isolation**: renamed `can_accept_job` property to `has_capacity` (was a property with arg, now both property and method work)
+- **`best_node_for`**: now filters out offers with `vram_total_gb == 0`
+- **`ComputeResources.summary`**: now includes total RAM in GB (e.g. `16GB (8.0 free)`)
+- **`ResourcePublisher.publish_local`**: accepts optional `res` param to avoid re-detecting when caller already has resources
+- **`ResourcePublisher`**: caches last `build_offer` result to avoid duplicate detection
+- **`UNTRUSTED_NETWORK_POLICY`**: properly serializes Permission enum keys (was: `Permission.X: True` only worked for str keys in some paths)
+- **`compute-share` CLI**: missing import of `ResourcePublisher` (NameError on invoke)
+- **Test `test_policy_policies_are_isolated`**: fixed contradictory assertion (was checking untrusted allowed writes, which conflicts with `test_untrusted_network_blocks_everything`)
+
+### Changed
+- **README rewritten as "AI Infrastructure OS"** — moved from "Pagani" framing to the bigger thesis: *we don't build models, we don't build agents, we build the coordination layer that makes the entire AI ecosystem work*
+- Comparison table now shows OmniAgent vs Cursor vs Continue.dev across 11 dimensions
+- Roadmap updated with 5 phases (Coordination → Marketplace → Distributed → Energy → Ecosystem)
+
+---
+
+## [0.0.x] — pre-release development
+
+Earlier development releases are not documented here. The repo began as a local-first multi-agent orchestrator and evolved through:
+
+- Phase 0: Hardware detection, Ollama manager, 7 built-in agents
+- Phase 1a: Smart router, cost tracker, audit (Guardian++), MCP server, hybrid deploy
+- Phase 1b: Agent Protocol (this release)
+
+---
+
+## What ships in v0.1.0
+
+```
+omniagent/
+├── README.md                    # AI Infrastructure OS pitch
+├── docs/
+│   └── agents.md                # YAML agent guide
+├── agents/
+│   ├── protocol/                # AgentSpec, Registry, Classifier, AdaptiveRouter
+│   └── registry/builtin/        # architect.yaml, developer.yaml, reviewer.yaml
+├── providers/                   # 18 models, 8 adapters, SmartRouter, CostTracker
+├── compute/                     # ResourceDetector, SandboxPolicy, ResourcePublisher
+├── core/guardrails/             # Guardian++ audit
+├── core/deploy/                 # LocalProvider, VpsProvider, AwsProvider (ECR+Fargate)
+├── mcp_server/                  # 6 tools, InProcessMCPClient
+└── cli.py                       # typer app: deploy, agent, compute, mcp
+```
+
+**Test count: 361 passing, 2 skipped (Docker daemon not running on host)**
+
+---
+
+## Coming next
+
+- **v0.2.0** — Web dashboard (Next.js) + multi-tenant SaaS
+- **v0.3.0** — Agent marketplace (community YAMLs, trust scores, one-click install)
+- **v0.4.0** — Real distributed compute (mDNS discovery, LAN federation, trust graph)
+- **v0.5.0** — Energy efficiency reporting (kWh per task, carbon per call, sustainability score)
+
+---
+
+**The models will change. The hardware will change. The coordination layer is permanent.**
+
+[Star on GitHub](https://github.com/landrover1984/omniagent) · [Read the docs](docs/) · [Write your first agent](docs/agents.md)

omniagent_fleet-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Garcia
+
+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.

omniagent_fleet-0.1.4/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include agents *.yaml *.yml
+recursive-include landing *.html
+recursive-include landing *.md
+recursive-exclude * __pycache__
+recursive-exclude * *.pyc
+recursive-exclude * *.egg-info
+global-exclude .DS_Store
+global-exclude *.pyc
+global-exclude __pycache__

omniagent_fleet-0.1.4/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: omniagent-fleet
+Version: 0.1.4
+Summary: AI Infrastructure OS — same engine, four facades (CLI, REST, web, MCP). Reduce 80-95% of AI spend by routing tasks to the right model.
+Author-email: Sergio Garcia <sgarcia@ubicacuenca.com>
+License: MIT
+Project-URL: Homepage, https://github.com/landrover1984/omniagent
+Project-URL: Source, https://github.com/landrover1984/omniagent
+Project-URL: Issues, https://github.com/landrover1984/omniagent/issues
+Project-URL: Changelog, https://github.com/landrover1984/omniagent/blob/main/CHANGELOG.md
+Keywords: ai,llm,router,cost-reduction,cli,mcp,local-first,ollama,fleet,infrastructure
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: psutil>=5.9.8
+Requires-Dist: py-cpuinfo>=9.0.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: python-socketio>=5.11.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: docker>=7.0.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: paramiko>=3.4.0
+Requires-Dist: boto3>=1.34.0
+Dynamic: license-file
+
+<div align="center">
+
+# OmniAgent
+
+## You are overspending on AI.
+
+**OmniAgent routes every AI task to the most efficient model automatically.**
+Local first. Cloud only when it pays off. **80–97% savings** on your AI bill.
+
+[Try the AI Cost Calculator](landing/index.html) · [See the 60-second demo](#the-60-second-demo) · [Star on GitHub](https://github.com/landrover1984/omniagent)
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-367%20passing-brightgreen.svg)](tests/)
+[![Zero Telemetry](https://img.shields.io/badge/zero-telemetry-blueviolet.svg)]()
+[![Local First](https://img.shields.io/badge/local-first-blue.svg)]()
+[![MIT 100%](https://img.shields.io/badge/100%25-open%20source-orange.svg)]()
+
+</div>
+
+---
+
+## The math most devs don't realize
+
+> *"I just need AI to review my code, write docstrings, and rename things."*
+> — every developer with a $500/month Cursor + Claude bill
+
+Here's what you actually need (benchmarked on real hardware, Jun 2026):
+
+| Task | All-Claude reality | OmniAgent | Savings |
+|------|-------------------|-----------|---------|
+| **Review a function for bugs** | Claude · **$0.30** | qwen2.5-coder:7b (local) · **$0.00** | **100%** |
+| **Write a Google-style docstring** | Claude · **$0.28** | qwen2.5-coder:7b (local) · **$0.00** | **100%** |
+| **Rename a variable** | Claude · **$0.15** | qwen2.5-coder:7b (local) · **$0.00** | **100%** |
+| **Explain TCP vs UDP** | Claude · **$0.10** | qwen2.5-coder:7b (local) · **$0.00** | **100%** |
+| **Classify a bug ticket** | Claude · **$0.08** | qwen2.5-coder:7b (local) · **$0.00** | **100%** |
+
+**Fleet benchmark · MSI desktop (GTX 1650, 4GB VRAM, 8 threads) · 5 tasks · 506 tokens: $0.00 total cloud spend.**
+
+OmniAgent uses Claude when Claude is the right tool. It just doesn't use Claude when Qwen can do the same job at 1% the cost.
+
+---
+
+## The 60-second demo
+
+Real benchmark run on MSI desktop (GTX 1650, 4GB VRAM, 8 threads):
+
+```
+→ msi-node: qwen2.5-coder:7b | $0.00 | 30,123ms  (review function)
+→ msi-node: qwen2.5-coder:7b | $0.00 | 50,475ms  (write docstring)
+→ msi-node: qwen2.5-coder:7b | $0.00 | 10,181ms  (rename variable)
+→ msi-node: qwen2.5-coder:7b | $0.00 | 15,321ms  (explain TCP/UDP)
+→ msi-node: qwen2.5-coder:7b | $0.00 |  8,649ms  (classify ticket)
+
+Total: 5 tasks · 506 tokens · $0.00 cloud spend · avg 22.95s/task
+```
+
+**Every task ran on local GPU. Zero cloud cost. That's what "AI Infrastructure OS" means.**
+
+---
+
+## Why OmniAgent exists
+
+The AI industry is in an efficiency crisis:
+
+- **73% of prompts** sent to frontier models could be handled by smaller local models
+- Developers burn **$500–$1000/month** on Cursor + Claude + GPT with **no visibility** into what each line costs
+- Agents **hallucinate APIs, break production code, leak secrets, forget to commit** — and you find out at 2 AM
+- Massive energy waste: a single city could run on the daily inference cycles of one frontier API call
+- Lock-in: one IDE, one provider, one pricing tier
+- No coordination between local hardware, cloud APIs, VPS nodes, and the billions of idle GPUs sitting in garages and offices worldwide
+
+**The models will keep changing. The hardware will keep evolving.**
+**The only permanent problem is: how do you orchestrate all this intelligence efficiently, securely, and cheaply?**
+
+That's what OmniAgent solves.
+
+---
+
+## What it is (and what it isn't)
+
+OmniAgent is **not** a model. **Not** an agent. **Not** a chatbot.
+
+OmniAgent is the **operating system that coordinates the entire AI ecosystem** — models, agents, hardware, costs, and security — so you stop wasting compute, money, and trust.
+
+Think of it as:
+
+- **Linux** doesn't create every app, but everything runs on it.
+- **Kubernetes** doesn't build every container, but it orchestrates them all.
+- **Steam** doesn't develop every game, but it hosts them.
+
+**OmniAgent** doesn't compete with OpenAI, Anthropic, DeepSeek, or your favorite open-source model. **It makes all of them work together intelligently.**
+
+---
+
+## The 4 façades: one engine, four ways to use it
+
+| Façade | Audience | What you get |
+|--------|----------|--------------|
+| **CLI** (`omniagent route "task"`) | Developers, power users | Full control, scriptable, fits in any pipeline |
+| **Web app** (`omniagent web`) | Everyone, especially non-devs | 5-tab dashboard on `http://localhost:8765` — visualize routing, hardware, optimize |
+| **YAML agents** (`*.yaml` in `~/.omniagent/agents/`) | Agent authors, teams | Declarative, shareable, version-controlled — see [docs/agents.md](docs/agents.md) |
+| **MCP tools** (via any MCP client) | Tool integrators | 6 tools: route, classify, decide, audit, deploy, optimize |
+
+Same Python engine. Four ways to use it. You pick the one that fits your workflow.
+
+---
+
+## The 90/9/1 design
+
+- **90% of users** never touch the CLI. They open `http://localhost:8765`, type a task, see the routing, hit **Run it ▶**.
+- **9% of users** open the **Optimize** tab, see what they're overspending on, and one-click install a cheaper agent.
+- **1% of users** write their own YAML agents, publish them, share them.
+
+The dashboard is the product. The YAML is the protocol. The CLI is the power tool.
+
+---
+
+## How it works (under the hood)
+
+1. **Task arrives** — text in the CLI, the web, or via MCP
+2. **TaskClassifier** — 10 categories, 5 complexities, detects vision / function-calling
+3. **AgentRegistry** — finds the right agent (project > user > builtin, YAML-defined)
+4. **SmartRouter** — picks the right model given the agent's constraints + your budget
+5. **AdaptiveRouter** — combines all of the above into a single `RoutingDecision`
+6. **LLM call** — local first, cloud only if budget + quality demand it
+7. **CostTracker** — logs the spend, feeds back into the next routing decision
+8. **Guardian++** — pre / during / post audit on every action (secret scan, command sandbox, commit verification)
+
+**364 unit tests** + **7 integration tests** validate every step.
+
+---
+
+## Quickstart (60 seconds)
+
+```bash
+git clone https://github.com/landrover1984/omniagent
+cd omniagent
+pip install -e .
+omniagent web
+# open http://localhost:8765
+```
+
+Or use the CLI directly:
+
+```bash
+omniagent agent-route "review this code for security" --budget 0.10
+omniagent agent-list                     # see all available agents
+omniagent agent-install ./my-agent.yaml  # add your own
+omniagent optimize                       # find cheaper routes
+omniagent cost-report                    # what you've spent
+omniagent agent-decide "design a cache"  # see the routing (no LLM call)
+```
+
+**Zero API keys needed to start.** Local models via Ollama work out of the box.
+
+---
+
+## What ships today
+
+| Layer | Status | Tests |
+|-------|--------|-------|
+| Agent Protocol (YAML agents) | Shipped | 18 |
+| Task Classifier (10 categories) | Shipped | 20 |
+| AdaptiveRouter (the brain) | Shipped | 8 |
+| 5-tab Web UI | Shipped | 13 endpoints |
+| Cost Optimizer (the killer feature) | Shipped | 3 |
+| Anti-Hallucination Audit (Guardian++) | Shipped | 23 |
+| Hybrid Deploy (local / VPS / AWS) | Shipped | 28 |
+| MCP Server (6 tools) | Shipped | 18 |
+| **CLI commands** | **20+** | **50+** |
+| **Total** | | **364 passing, 2 skipped** |
+
+---
+
+## Roadmap
+
+| Phase | Theme | Status |
+|-------|-------|--------|
+| **v0.1.x** | **AI Infrastructure OS** — routing, cost, optimize, local-first | **Shipped** |
+| v0.2.x | Optimization Layer — replay mode, "Claude unnecessary" detector, savings reports | Next |
+| v0.3.x | Visual Dashboard — real-time cost graphs, agent analytics, team view | Planned |
+| v0.4.x | Distributed Compute — idle GPU federation, opt-in mesh | Deferred |
+| v0.5.x | Marketplace + Incentives — community YAMLs, reputation, rewards | Deferred |
+
+We are **not** building another "AI wrapper". We are building the **coordination layer** that the entire AI ecosystem needs.
+
+Distributed compute and marketplace are real, but they're not the wedge. The wedge is: **stop overspending on AI**. Get that right first.
+
+---
+
+## License
+
+**MIT — 100% open source, forever.** No paid tier, no "enterprise edition", no bait-and-switch.
+
+---
+
+<div align="center">
+
+**The models will change. The hardware will change. The coordination layer is permanent.**
+
+[Star on GitHub](https://github.com/landrover1984/omniagent) · [Try the Cost Calculator](landing/index.html) · [Write your first agent](docs/agents.md)
+
+</div>