chore: major repository cleanup and v0.2.0 preparation

User · claude · User · commit 0dcaa57167ba · 2025-10-15T22:15:46.000+02:00
- Bump version to 0.2.0 for LangChain integration release - Add comprehensive CHANGELOG.md tracking all versions - Add CONTRIBUTING.md with contribution guidelines - Add troubleshooting section to README - Add PyPI and GitHub Actions badges to README - Add Quick Links section for better navigation - Clean up scripts directory with explanatory README - Update .gitignore to exclude build artifacts - Add git-changelog to dev dependencies for future automation - Remove unnecessary development files from repo This prepares the repository for the v0.2.0 release featuring LangChain integration and improves overall project documentation and structure. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/.gitignore b/.gitignore
@@ -69,4 +69,7 @@ venv.bak/
 
 # Project specific
 *.pdf
-ACE_IMPROVEMENTS.md
+ACE_IMPROVEMENTS.md
+*.egg-info/
+reports/
+docs/method_outline.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to ACE Framework will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-10-15
+
+### Added
+- LangChain integration via `LangChainLiteLLMClient` for advanced workflows
+- Router support for load balancing across multiple model deployments
+- Comprehensive example for LangChain usage (`examples/langchain_example.py`)
+- Optional installation group: `pip install ace-framework[langchain]`
+- PyPI badges and Quick Links section in README
+- CHANGELOG.md for version tracking
+
+### Fixed
+- Parameter filtering in LiteLLM and LangChain clients (refinement_round, max_refinement_rounds)
+- GitHub Actions workflow using deprecated artifact actions v3 → v4
+
+### Changed
+- Improved README with better structure and badges
+- Updated .gitignore to exclude build artifacts and development files
+
+### Removed
+- Unnecessary development files from repository
+
+## [0.1.1] - 2025-10-15
+
+### Fixed
+- GitHub Actions workflow for PyPI publishing
+- Updated artifact upload/download actions from v3 to v4
+
+## [0.1.0] - 2025-10-15
+
+### Added
+- Initial release of ACE Framework
+- Core ACE implementation based on paper (arXiv:2510.04618)
+- Three-role architecture: Generator, Reflector, and Curator
+- Playbook system for storing and evolving strategies
+- LiteLLM integration supporting 100+ LLM providers
+- Offline and Online adaptation modes
+- Async and streaming support
+- Example scripts for quick start
+- Comprehensive test suite
+- PyPI packaging and GitHub Actions CI/CD
+
+### Features
+- Self-improving agents that learn from experience
+- Delta operations for incremental playbook updates
+- Support for OpenAI, Anthropic, Google, and more via LiteLLM
+- Type hints and modern Python practices
+- MIT licensed for open source use
+
+[0.2.0]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/Kayba-ai/agentic-context-engine/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Kayba-ai/agentic-context-engine/releases/tag/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,104 @@
+# Contributing to ACE Framework
+
+Thank you for your interest in contributing to the Agentic Context Engine! We welcome contributions from the community.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:
+
+- A clear and descriptive title
+- Steps to reproduce the issue
+- Expected behavior vs actual behavior
+- Environment details (OS, Python version, package versions)
+- Any relevant error messages or logs
+
+### Suggesting Enhancements
+
+Enhancement suggestions are welcome! Please provide:
+
+- A clear description of the enhancement
+- Use cases and benefits
+- Possible implementation approach (optional)
+- Any potential drawbacks or considerations
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests to ensure nothing breaks
+5. Commit your changes using conventional commits (see below)
+6. Push to your branch
+7. Open a Pull Request
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/your-username/agentic-context-engine.git
+cd agentic-context-engine
+
+# Install in development mode with all dependencies
+pip install -e .[all,dev]
+
+# Run tests
+python -m pytest tests/
+
+# Run linting
+black ace/
+mypy ace/
+```
+
+## Commit Message Format
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) for clear commit history and automatic changelog generation.
+
+Format: `<type>(<scope>): <subject>`
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding tests
+- `chore`: Maintenance tasks
+
+Examples:
+```
+feat(llm): add support for new LLM provider
+fix(adapter): resolve memory leak in online mode
+docs(readme): update installation instructions
+```
+
+## Code Style
+
+- Follow PEP 8
+- Use type hints where possible
+- Add docstrings to all public functions and classes
+- Keep line length under 100 characters
+- Use Black for automatic formatting
+
+## Testing
+
+- Write tests for new features
+- Ensure all tests pass before submitting PR
+- Aim for good test coverage
+- Use meaningful test names
+
+## Documentation
+
+- Update README.md if adding new features
+- Add docstrings to new code
+- Update CHANGELOG.md following Keep a Changelog format
+- Include examples for new functionality
+
+## Questions?
+
+Feel free to open an issue for any questions or join the discussion in [GitHub Discussions](https://github.com/Kayba-ai/agentic-context-engine/discussions).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
diff --git a/README.md b/README.md
@@ -2,8 +2,10 @@
 
 **Build self-improving AI agents that learn from experience**
 
+[![PyPI version](https://badge.fury.io/py/ace-framework.svg)](https://pypi.org/project/ace-framework/)
 [![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)
+[![Tests](https://github.com/Kayba-ai/agentic-context-engine/actions/workflows/test.yml/badge.svg)](https://github.com/Kayba-ai/agentic-context-engine/actions)
 [![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.
@@ -12,6 +14,10 @@
 
 🔌 **Works with any LLM** - OpenAI, Anthropic Claude, Google Gemini, and 100+ more providers out of the box!
 
+## Quick Links
+
+📦 [PyPI Package](https://pypi.org/project/ace-framework/) | 📚 [Documentation](https://github.com/Kayba-ai/agentic-context-engine/wiki) | 🐛 [Issues](https://github.com/Kayba-ai/agentic-context-engine/issues) | 💬 [Discussions](https://github.com/Kayba-ai/agentic-context-engine/discussions)
+
 ## Quick Start
 
 **Minimum Python 3.9 required**
@@ -272,6 +278,36 @@ Based on the open reproduction at: https://github.com/sci-m-wang/ACE-open
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
+## Troubleshooting
+
+### Installation Issues
+
+**Problem**: `pip install ace-framework` fails
+- **Solution**: Ensure Python 3.9+ is installed: `python --version`
+- **Solution**: Upgrade pip: `pip install --upgrade pip`
+
+**Problem**: ImportError when using LangChain integration
+- **Solution**: Install with extras: `pip install ace-framework[langchain]`
+
+**Problem**: LiteLLM API errors
+- **Solution**: Check your API keys are set correctly in `.env`
+- **Solution**: Verify your API key has sufficient credits/quota
+
+### Common Errors
+
+**"Unrecognized request argument"**: The LLM provider doesn't support a parameter
+- This is usually handled automatically, but if it persists, please report an issue
+
+**Memory issues with large playbooks**:
+- Use online adaptation mode instead of offline
+- Periodically save and reload playbooks
+
+**Rate limiting errors**:
+- Add delays between requests
+- Use exponential backoff (built into LiteLLM)
+
+For more help, check the [Issues](https://github.com/Kayba-ai/agentic-context-engine/issues) page.
+
 ---
 
 **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).
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ace-framework"
-version = "0.1.0"
+version = "0.2.0"
 description = "Build self-improving AI agents that learn from experience"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -69,6 +69,7 @@ dev = [
     "pytest-asyncio>=0.21.0",
     "black>=23.0.0",
     "mypy>=1.0.0",
+    "git-changelog>=2.5.0",
 ]
 
 [project.urls]
diff --git a/scripts/README.md b/scripts/README.md
@@ -0,0 +1,20 @@
+# Development Scripts
+
+⚠️ **Note**: These scripts are for development and research purposes only. They are not included in the PyPI package and may reference local model weights or data files that are not part of the public repository.
+
+## Scripts
+
+- `run_questions.py` - Run ACE adaptation on sample questions with a local model
+- `run_questions_direct.py` - Run questions directly without adaptation for baseline comparison
+- `run_local_adapter.py` - Test ACE with local Transformers models
+
+## Requirements
+
+These scripts require:
+- Local model weights (not included in repo)
+- CUDA-capable GPU for local model inference
+- Additional dependencies beyond the base package
+
+## Usage
+
+These are primarily for ACE framework development and testing. For production use, please refer to the examples in the `examples/` directory which use cloud LLM providers.
diff --git a/setup.py b/setup.py
@@ -20,7 +20,7 @@
 
 setup(
     name="ace-framework",
-    version="0.1.0",
+    version="0.2.0",
     author="Kayba.ai",
     author_email="hello@kayba.ai",
     description="Build self-improving AI agents that learn from experience",
