Upload README.md

README.md

@@ -1,26 +1,76 @@
----
-tags:
-- ml-intern
----
+# Agent Cost Optimizer (ACO)
 
-# narcolepticchicken/agent-cost-optimizer
+A universal control layer that reduces total cost of autonomous agent runs while preserving task quality.
 
-<!-- ml-intern-provenance -->
-## Generated by ML Intern
+## Core Thesis
 
-This model repository was generated by [ML Intern](https://github.com/huggingface/ml-intern), an agent for machine learning research and development on the Hugging Face Hub.
+Most agent cost is wasted through:
+- Overusing frontier models
+- Sending huge context every turn
+- Using tools unnecessarily
+- Failing and retrying blindly
+- Ignoring cache boundaries
+- Using verifiers everywhere instead of selectively
+- Not learning from previous traces
 
-- Try ML Intern: https://smolagents-ml-intern.hf.space
-- Source code: https://github.com/huggingface/ml-intern
+ACO learns when to spend and when not to spend.
 
-## Usage
+## Architecture
+
+### 10 Core Modules
+
+1. **Cost Telemetry Collector** — Structured trace collection with normalized schema
+2. **Task Cost Classifier** — Predicts expected cost, risk, model strength needed
+3. **Model Cascade Router** — Dynamic model selection (tiny → cheap → medium → frontier → specialist)
+4. **Context Budgeter** — Decides what context is needed vs. what can be omitted/summarized/cached
+5. **Cache-Aware Prompt Layout** — Optimizes prompt structure for prefix-cache reuse
+6. **Tool-Use Cost Gate** — Predicts whether a tool call is worth the cost
+7. **Verifier Budgeter** — Selective verification based on risk, confidence, task type
+8. **Retry/Recovery Optimizer** — Intelligent failure recovery without blind retry loops
+9. **Meta-Tool Miner** — Compresses repeated workflows into reusable deterministic scripts
+10. **Early Termination / Doom Detector** — Detects runs unlikely to succeed and stops them
+
+## Installation
+
+```bash
+pip install agent-cost-optimizer
+```
+
+## Quick Start
 
 ```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
+from aco import AgentCostOptimizer
 
-model_id = "narcolepticchicken/agent-cost-optimizer"
-tokenizer = AutoTokenizer.from_pretrained(model_id)
-model = AutoModelForCausalLM.from_pretrained(model_id)
+optimizer = AgentCostOptimizer.from_config("config.yaml")
+result = optimizer.optimize(agent_request, run_state)
 ```
 
-For non-causal architectures, replace `AutoModelForCausalLM` with the appropriate `AutoModel` class.
+## Reward Objective
+
+```
+cost_adjusted_score =
+  task_success_score
+  + safety_bonus
+  + artifact_completion_bonus
+  + calibration_bonus
+  - model_cost_penalty
+  - tool_cost_penalty
+  - latency_penalty
+  - retry_penalty
+  - unnecessary_verifier_penalty
+  - false_done_penalty
+  - unsafe_cheap_model_penalty
+  - missed_escalation_penalty
+```
+
+## Benchmarks
+
+- Coding Agent Tasks
+- Research Agent Tasks  
+- Tool-Use Tasks
+- Document / Contract / QA Tasks
+- Long-Horizon Agent Tasks
+
+## License
+
+MIT