ace-framework 0.1.0__tar.gz

ace_framework-0.1.0/.env.example

@@ -0,0 +1,42 @@
+# API Keys for LLM Providers
+# Copy this file to .env and add your actual API keys
+
+# OpenAI
+OPENAI_API_KEY=your-openai-api-key-here
+
+# Anthropic (Claude)
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+
+# Google (Gemini)
+GOOGLE_API_KEY=your-google-api-key-here
+
+# Cohere
+COHERE_API_KEY=your-cohere-api-key-here
+
+# Azure OpenAI (optional)
+AZURE_API_KEY=your-azure-api-key-here
+AZURE_API_BASE=https://your-resource.openai.azure.com
+AZURE_API_VERSION=2024-02-15-preview
+
+# AWS Bedrock (optional)
+AWS_ACCESS_KEY_ID=your-aws-access-key
+AWS_SECRET_ACCESS_KEY=your-aws-secret-key
+AWS_REGION_NAME=us-east-1
+
+# Hugging Face (optional)
+HUGGINGFACE_API_KEY=your-huggingface-api-key-here
+
+# Replicate (optional)
+REPLICATE_API_KEY=your-replicate-api-key-here
+
+# Together AI (optional)
+TOGETHER_API_KEY=your-together-api-key-here
+
+# Model Configuration (optional)
+DEFAULT_MODEL=gpt-4o-mini
+DEFAULT_TEMPERATURE=0.0
+DEFAULT_MAX_TOKENS=512
+
+# Cost Tracking (optional)
+TRACK_COSTS=true
+MAX_BUDGET=10.0

ace_framework-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kayba.ai
+
+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.

ace_framework-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include requirements.txt
+include requirements-optional.txt
+include .env.example
+recursive-include ace *.py
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

ace_framework-0.1.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.4
+Name: ace-framework
+Version: 0.1.0
+Summary: Build self-improving AI agents that learn from experience
+Home-page: https://github.com/Kayba-ai/agentic-context-engine
+Author: Kayba.ai
+Author-email: "Kayba.ai" <hello@kayba.ai>
+Maintainer-email: "Kayba.ai" <hello@kayba.ai>
+License: MIT
+Project-URL: Homepage, https://kayba.ai
+Project-URL: Documentation, https://github.com/Kayba-ai/agentic-context-engine#readme
+Project-URL: Repository, https://github.com/Kayba-ai/agentic-context-engine
+Project-URL: Issues, https://github.com/Kayba-ai/agentic-context-engine/issues
+Keywords: ai,llm,agents,machine-learning,self-improvement,context-engineering,ace,openai,anthropic,claude,gpt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: all
+Requires-Dist: litellm>=1.0.0; extra == "all"
+Requires-Dist: transformers>=4.0.0; extra == "all"
+Requires-Dist: torch>=2.0.0; extra == "all"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0.0; extra == "litellm"
+Provides-Extra: transformers
+Requires-Dist: transformers>=4.0.0; extra == "transformers"
+Requires-Dist: torch>=2.0.0; extra == "transformers"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Agentic Context Engine (ACE) 🚀
+
+**Build self-improving AI agents that learn from experience**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Paper](https://img.shields.io/badge/Paper-arXiv:2510.04618-red.svg)](https://arxiv.org/abs/2510.04618)
+
+🧠 **ACE** is a framework for building AI agents that get smarter over time by learning from their mistakes and successes.
+
+💡 Based on the paper "Agentic Context Engineering" from Stanford/SambaNova - ACE helps your LLM agents build a "playbook" of strategies that improves with each task.
+
+🔌 **Works with any LLM** - OpenAI, Anthropic Claude, Google Gemini, and 100+ more providers out of the box!
+
+## Quick Start
+
+**Minimum Python 3.9 required**
+
+### Install ACE:
+```bash
+pip install ace-framework
+# or for development:
+pip install -r requirements.txt
+```
+
+### Set up your API key:
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Add your OpenAI key (or Anthropic, Google, etc.)
+echo "OPENAI_API_KEY=your-key-here" >> .env
+```
+
+### Run your first agent:
+```python
+from ace import LiteLLMClient, OfflineAdapter, Generator, Reflector, Curator
+from ace import Playbook, Sample, TaskEnvironment, EnvironmentResult
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Create your agent with any LLM
+client = LiteLLMClient(model="gpt-3.5-turbo")  # or claude-3, gemini-pro, etc.
+
+# Set up ACE components
+adapter = OfflineAdapter(
+    playbook=Playbook(),
+    generator=Generator(client),
+    reflector=Reflector(client),
+    curator=Curator(client)
+)
+
+# Define a simple task
+class SimpleEnv(TaskEnvironment):
+    def evaluate(self, sample, output):
+        correct = sample.ground_truth.lower() in output.final_answer.lower()
+        return EnvironmentResult(
+            feedback="Correct!" if correct else "Try again",
+            ground_truth=sample.ground_truth
+        )
+
+# Train your agent
+samples = [
+    Sample(question="What is 2+2?", ground_truth="4"),
+    Sample(question="Capital of France?", ground_truth="Paris"),
+]
+
+results = adapter.run(samples, SimpleEnv(), epochs=1)
+print(f"Agent learned {len(adapter.playbook.bullets())} strategies!")
+```
+
+## How It Works
+
+ACE uses three AI "roles" that work together to help your agent improve:
+
+1. **🎯 Generator** - Tries to solve tasks using the current playbook
+2. **🔍 Reflector** - Analyzes what went wrong (or right)
+3. **📝 Curator** - Updates the playbook with new strategies
+
+Think of it like a sports team reviewing game footage to get better!
+
+## Examples
+
+### Simple Q&A Agent
+```python
+python examples/simple_ace_example.py
+```
+
+### Advanced Examples with Different LLMs
+```python
+python examples/quickstart_litellm.py
+```
+
+Check out the `examples/` folder for more!
+
+## Supported LLM Providers
+
+ACE works with **100+ LLM providers** through LiteLLM:
+
+- **OpenAI** - GPT-4, GPT-3.5-turbo
+- **Anthropic** - Claude 3 (Opus, Sonnet, Haiku)
+- **Google** - Gemini Pro, PaLM
+- **Cohere** - Command models
+- **Local Models** - Ollama, Transformers
+- **And many more!**
+
+Just change the model name:
+```python
+# OpenAI
+client = LiteLLMClient(model="gpt-4")
+
+# Anthropic Claude
+client = LiteLLMClient(model="claude-3-sonnet-20240229")
+
+# Google Gemini
+client = LiteLLMClient(model="gemini-pro")
+
+# With fallbacks for reliability
+client = LiteLLMClient(
+    model="gpt-4",
+    fallbacks=["claude-3-haiku", "gpt-3.5-turbo"]
+)
+```
+
+## Key Features
+
+- ✅ **Self-Improving** - Agents learn from experience and build knowledge
+- ✅ **Provider Agnostic** - Switch LLMs with one line of code
+- ✅ **Production Ready** - Automatic retries, fallbacks, and error handling
+- ✅ **Cost Efficient** - Track costs and use cheaper models as fallbacks
+- ✅ **Async Support** - Built for high-performance applications
+- ✅ **Fully Typed** - Great IDE support and type safety
+
+## Advanced Usage
+
+### Online Learning (Learn While Running)
+```python
+from ace import OnlineAdapter
+
+# Agent improves while processing real tasks
+adapter = OnlineAdapter(
+    playbook=existing_playbook,  # Can start with existing knowledge
+    generator=Generator(client),
+    reflector=Reflector(client),
+    curator=Curator(client)
+)
+
+# Process tasks one by one, learning from each
+for task in real_world_tasks:
+    result = adapter.process(task, environment)
+    # Agent automatically updates its strategies
+```
+
+### Custom Task Environments
+```python
+class CodeTestingEnv(TaskEnvironment):
+    def evaluate(self, sample, output):
+        # Run the generated code
+        test_passed = run_tests(output.final_answer)
+
+        return EnvironmentResult(
+            feedback=f"Tests {'passed' if test_passed else 'failed'}",
+            ground_truth=sample.ground_truth,
+            metrics={"pass_rate": 1.0 if test_passed else 0.0}
+        )
+```
+
+### Streaming Responses
+```python
+# Get responses token by token
+for chunk in client.complete_with_stream("Write a story"):
+    print(chunk, end="", flush=True)
+```
+
+### Async Operations
+```python
+import asyncio
+
+async def main():
+    response = await client.acomplete("Solve this problem...")
+    print(response.text)
+
+asyncio.run(main())
+```
+
+## Architecture
+
+ACE implements the Agentic Context Engineering method from the research paper:
+
+- **Playbook**: A structured memory that stores successful strategies
+- **Bullets**: Individual strategies with helpful/harmful counters
+- **Delta Operations**: Incremental updates that preserve knowledge
+- **Three Roles**: Generator, Reflector, and Curator working together
+
+The framework prevents "context collapse" - a common problem where agents forget important information over time.
+
+## Repository Structure
+
+```
+ace/
+├── ace/                    # Core library
+│   ├── playbook.py        # Strategy storage
+│   ├── roles.py           # Generator, Reflector, Curator
+│   ├── adaptation.py      # Training loops
+│   └── llm_providers/     # LLM integrations
+├── examples/              # Ready-to-run examples
+├── tests/                 # Unit tests
+└── docs/                  # Documentation
+```
+
+## Contributing
+
+We welcome contributions! Feel free to:
+- 🐛 Report bugs
+- 💡 Suggest features
+- 🔧 Submit PRs
+- 📚 Improve documentation
+
+## Citation
+
+If you use ACE in your research or project, please cite the original papers:
+
+### ACE Paper (Primary Reference)
+```bibtex
+@article{zhang2024ace,
+  title={Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models},
+  author={Zhang, Qizheng and Hu, Changran and Upasani, Shubhangi and Ma, Boyuan and Hong, Fenglu and
+          Kamanuru, Vamsidhar and Rainton, Jay and Wu, Chen and Ji, Mengmeng and Li, Hanchen and
+          Thakker, Urmish and Zou, James and Olukotun, Kunle},
+  journal={arXiv preprint arXiv:2510.04618},
+  year={2024}
+}
+```
+
+### Dynamic Cheatsheet (Foundation Work)
+ACE builds upon the adaptive memory concepts from Dynamic Cheatsheet:
+
+```bibtex
+@article{suzgun2025dynamiccheatsheet,
+  title={Dynamic Cheatsheet: Test-Time Learning with Adaptive Memory},
+  author={Suzgun, Mirac and Yuksekgonul, Mert and Bianchi, Federico and Jurafsky, Dan and Zou, James},
+  year={2025},
+  eprint={2504.07952},
+  archivePrefix={arXiv},
+  primaryClass={cs.LG},
+  url={https://arxiv.org/abs/2504.07952}
+}
+```
+
+### This Implementation
+If you use this specific implementation, you can also reference:
+
+```
+This repository: https://github.com/Kayba-ai/agentic-context-engine
+PyPI package: https://pypi.org/project/ace-framework/
+Based on the open reproduction at: https://github.com/sci-m-wang/ACE-open
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+**Note**: This is an independent implementation based on the ACE paper (arXiv:2510.04618) and builds upon concepts from Dynamic Cheatsheet. For the original reproduction scaffold, see [sci-m-wang/ACE-open](https://github.com/sci-m-wang/ACE-open).
+
+Made with ❤️ by [Kayba](https://kayba.ai) and the open-source community

ace_framework-0.1.0/README.md

@@ -0,0 +1,268 @@
+# Agentic Context Engine (ACE) 🚀
+
+**Build self-improving AI agents that learn from experience**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Paper](https://img.shields.io/badge/Paper-arXiv:2510.04618-red.svg)](https://arxiv.org/abs/2510.04618)
+
+🧠 **ACE** is a framework for building AI agents that get smarter over time by learning from their mistakes and successes.
+
+💡 Based on the paper "Agentic Context Engineering" from Stanford/SambaNova - ACE helps your LLM agents build a "playbook" of strategies that improves with each task.
+
+🔌 **Works with any LLM** - OpenAI, Anthropic Claude, Google Gemini, and 100+ more providers out of the box!
+
+## Quick Start
+
+**Minimum Python 3.9 required**
+
+### Install ACE:
+```bash
+pip install ace-framework
+# or for development:
+pip install -r requirements.txt
+```
+
+### Set up your API key:
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Add your OpenAI key (or Anthropic, Google, etc.)
+echo "OPENAI_API_KEY=your-key-here" >> .env
+```
+
+### Run your first agent:
+```python
+from ace import LiteLLMClient, OfflineAdapter, Generator, Reflector, Curator
+from ace import Playbook, Sample, TaskEnvironment, EnvironmentResult
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Create your agent with any LLM
+client = LiteLLMClient(model="gpt-3.5-turbo")  # or claude-3, gemini-pro, etc.
+
+# Set up ACE components
+adapter = OfflineAdapter(
+    playbook=Playbook(),
+    generator=Generator(client),
+    reflector=Reflector(client),
+    curator=Curator(client)
+)
+
+# Define a simple task
+class SimpleEnv(TaskEnvironment):
+    def evaluate(self, sample, output):
+        correct = sample.ground_truth.lower() in output.final_answer.lower()
+        return EnvironmentResult(
+            feedback="Correct!" if correct else "Try again",
+            ground_truth=sample.ground_truth
+        )
+
+# Train your agent
+samples = [
+    Sample(question="What is 2+2?", ground_truth="4"),
+    Sample(question="Capital of France?", ground_truth="Paris"),
+]
+
+results = adapter.run(samples, SimpleEnv(), epochs=1)
+print(f"Agent learned {len(adapter.playbook.bullets())} strategies!")
+```
+
+## How It Works
+
+ACE uses three AI "roles" that work together to help your agent improve:
+
+1. **🎯 Generator** - Tries to solve tasks using the current playbook
+2. **🔍 Reflector** - Analyzes what went wrong (or right)
+3. **📝 Curator** - Updates the playbook with new strategies
+
+Think of it like a sports team reviewing game footage to get better!
+
+## Examples
+
+### Simple Q&A Agent
+```python
+python examples/simple_ace_example.py
+```
+
+### Advanced Examples with Different LLMs
+```python
+python examples/quickstart_litellm.py
+```
+
+Check out the `examples/` folder for more!
+
+## Supported LLM Providers
+
+ACE works with **100+ LLM providers** through LiteLLM:
+
+- **OpenAI** - GPT-4, GPT-3.5-turbo
+- **Anthropic** - Claude 3 (Opus, Sonnet, Haiku)
+- **Google** - Gemini Pro, PaLM
+- **Cohere** - Command models
+- **Local Models** - Ollama, Transformers
+- **And many more!**
+
+Just change the model name:
+```python
+# OpenAI
+client = LiteLLMClient(model="gpt-4")
+
+# Anthropic Claude
+client = LiteLLMClient(model="claude-3-sonnet-20240229")
+
+# Google Gemini
+client = LiteLLMClient(model="gemini-pro")
+
+# With fallbacks for reliability
+client = LiteLLMClient(
+    model="gpt-4",
+    fallbacks=["claude-3-haiku", "gpt-3.5-turbo"]
+)
+```
+
+## Key Features
+
+- ✅ **Self-Improving** - Agents learn from experience and build knowledge
+- ✅ **Provider Agnostic** - Switch LLMs with one line of code
+- ✅ **Production Ready** - Automatic retries, fallbacks, and error handling
+- ✅ **Cost Efficient** - Track costs and use cheaper models as fallbacks
+- ✅ **Async Support** - Built for high-performance applications
+- ✅ **Fully Typed** - Great IDE support and type safety
+
+## Advanced Usage
+
+### Online Learning (Learn While Running)
+```python
+from ace import OnlineAdapter
+
+# Agent improves while processing real tasks
+adapter = OnlineAdapter(
+    playbook=existing_playbook,  # Can start with existing knowledge
+    generator=Generator(client),
+    reflector=Reflector(client),
+    curator=Curator(client)
+)
+
+# Process tasks one by one, learning from each
+for task in real_world_tasks:
+    result = adapter.process(task, environment)
+    # Agent automatically updates its strategies
+```
+
+### Custom Task Environments
+```python
+class CodeTestingEnv(TaskEnvironment):
+    def evaluate(self, sample, output):
+        # Run the generated code
+        test_passed = run_tests(output.final_answer)
+
+        return EnvironmentResult(
+            feedback=f"Tests {'passed' if test_passed else 'failed'}",
+            ground_truth=sample.ground_truth,
+            metrics={"pass_rate": 1.0 if test_passed else 0.0}
+        )
+```
+
+### Streaming Responses
+```python
+# Get responses token by token
+for chunk in client.complete_with_stream("Write a story"):
+    print(chunk, end="", flush=True)
+```
+
+### Async Operations
+```python
+import asyncio
+
+async def main():
+    response = await client.acomplete("Solve this problem...")
+    print(response.text)
+
+asyncio.run(main())
+```
+
+## Architecture
+
+ACE implements the Agentic Context Engineering method from the research paper:
+
+- **Playbook**: A structured memory that stores successful strategies
+- **Bullets**: Individual strategies with helpful/harmful counters
+- **Delta Operations**: Incremental updates that preserve knowledge
+- **Three Roles**: Generator, Reflector, and Curator working together
+
+The framework prevents "context collapse" - a common problem where agents forget important information over time.
+
+## Repository Structure
+
+```
+ace/
+├── ace/                    # Core library
+│   ├── playbook.py        # Strategy storage
+│   ├── roles.py           # Generator, Reflector, Curator
+│   ├── adaptation.py      # Training loops
+│   └── llm_providers/     # LLM integrations
+├── examples/              # Ready-to-run examples
+├── tests/                 # Unit tests
+└── docs/                  # Documentation
+```
+
+## Contributing
+
+We welcome contributions! Feel free to:
+- 🐛 Report bugs
+- 💡 Suggest features
+- 🔧 Submit PRs
+- 📚 Improve documentation
+
+## Citation
+
+If you use ACE in your research or project, please cite the original papers:
+
+### ACE Paper (Primary Reference)
+```bibtex
+@article{zhang2024ace,
+  title={Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models},
+  author={Zhang, Qizheng and Hu, Changran and Upasani, Shubhangi and Ma, Boyuan and Hong, Fenglu and
+          Kamanuru, Vamsidhar and Rainton, Jay and Wu, Chen and Ji, Mengmeng and Li, Hanchen and
+          Thakker, Urmish and Zou, James and Olukotun, Kunle},
+  journal={arXiv preprint arXiv:2510.04618},
+  year={2024}
+}
+```
+
+### Dynamic Cheatsheet (Foundation Work)
+ACE builds upon the adaptive memory concepts from Dynamic Cheatsheet:
+
+```bibtex
+@article{suzgun2025dynamiccheatsheet,
+  title={Dynamic Cheatsheet: Test-Time Learning with Adaptive Memory},
+  author={Suzgun, Mirac and Yuksekgonul, Mert and Bianchi, Federico and Jurafsky, Dan and Zou, James},
+  year={2025},
+  eprint={2504.07952},
+  archivePrefix={arXiv},
+  primaryClass={cs.LG},
+  url={https://arxiv.org/abs/2504.07952}
+}
+```
+
+### This Implementation
+If you use this specific implementation, you can also reference:
+
+```
+This repository: https://github.com/Kayba-ai/agentic-context-engine
+PyPI package: https://pypi.org/project/ace-framework/
+Based on the open reproduction at: https://github.com/sci-m-wang/ACE-open
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+**Note**: This is an independent implementation based on the ACE paper (arXiv:2510.04618) and builds upon concepts from Dynamic Cheatsheet. For the original reproduction scaffold, see [sci-m-wang/ACE-open](https://github.com/sci-m-wang/ACE-open).
+
+Made with ❤️ by [Kayba](https://kayba.ai) and the open-source community