kite-agent 0.1.0__tar.gz

kite_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to Kite 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.1.0] - 2025-01-23
+
+### Added
+
+#### Core Framework
+- Initial release of Kite Framework
+- Lazy-loading architecture with ~50ms startup time
+- Multi-provider LLM support (OpenAI, Anthropic, Groq, Ollama)
+- Configuration management via environment variables
+
+#### Safety Mechanisms
+- **Circuit Breaker**: Production-grade circuit breaker with 3 states (CLOSED, OPEN, HALF_OPEN)
+  - Automatic failure detection and recovery
+  - Configurable thresholds and timeouts
+  - Statistics tracking and monitoring
+- **Idempotency Manager**: Duplicate operation prevention
+  - Memory and Redis backend support
+  - Configurable TTL for cached results
+- **Kill Switch**: Emergency stop mechanism
+  - Max iterations enforcement
+  - Cost limit enforcement
+  - Custom stop conditions
+
+#### Agent Reasoning Patterns
+- **ReAct Agent**: Reasoning + Acting loop with tool use
+- **Plan-Execute Agent**: Task decomposition with replanning
+- **ReWOO Agent**: Parallel execution with dependency resolution
+- **Tree-of-Thoughts Agent**: Multi-path reasoning exploration
+
+#### Memory Systems
+- **Vector Memory**: Semantic search with FAISS/ChromaDB
+  - Document storage and retrieval
+  - Embedding-based similarity search
+- **Graph RAG**: Knowledge graph for multi-hop reasoning
+  - Entity and relationship management
+  - Graph traversal queries
+- **Session Memory**: Conversation context management
+
+#### Pipeline & Routing
+- **Deterministic Pipelines**: Workflow orchestration
+  - Sequential step execution
+  - Checkpoint support for Human-in-the-Loop (HITL)
+  - Intervention points for state modification
+- **Semantic Router**: Intent classification using embeddings
+- **Aggregator Router**: Multi-agent response combination
+
+#### Tools & Integrations
+- Built-in tools: web_search, calculator, datetime
+- MCP (Model Context Protocol) integration
+  - PostgreSQL MCP server
+  - Gmail MCP client (basic)
+  - Google Drive MCP client (basic)
+
+#### Monitoring & Observability
+- Metrics collection for agents and operations
+- Circuit breaker statistics
+- Cost tracking
+
+#### Documentation
+- Comprehensive README with quick start
+- API reference documentation
+- Architecture guide
+- Safety guide
+- Memory systems guide
+- 9 production-ready example case studies
+
+### Known Issues
+- No comprehensive unit test suite
+- Tool ecosystem limited (only 3 built-in tools)
+- MCP servers are basic implementations
+
+### Notes
+This is an **alpha release** (v0.1.0). The framework is functional but has known limitations:
+- Not recommended for production use without thorough testing
+- API may change in future releases
+- Some features are basic implementations
+- Comprehensive testing needed before production deployment
+
+For production use, we recommend:
+1. Add your own unit tests for critical paths
+2. Implement proper async in LLM providers if using async extensively
+3. Add persistence layer for vector memory
+4. Monitor circuit breaker statistics closely
+
+### Contributors
+- Thien Nguyen (@thienzz)
+
+[0.1.0]: https://github.com/thienzz/Kite/releases/tag/v0.1.0

kite_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,179 @@
+# Contributing to Kite Framework
+
+First off, thank you for considering contributing to Kite! 🎉
+
+## Code of Conduct
+
+This project adheres to a code of conduct. By participating, you are expected to uphold this code.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues. When you create a bug report, include:
+
+- **Use a clear and descriptive title**
+- **Describe the exact steps to reproduce the problem**
+- **Provide specific examples** (code snippets, error messages)
+- **Describe the behavior you observed** and what you expected
+- **Include your environment details** (Python version, OS, Kite version)
+
+Example bug report:
+```markdown
+**Title**: Circuit breaker not opening after 3 failures
+
+**Description**: 
+Circuit breaker is configured with failure_threshold=3 but doesn't 
+open even after 5 consecutive failures.
+
+**Steps to Reproduce**:
+1. Configure circuit breaker with threshold=3
+2. Cause 5 consecutive LLM call failures
+3. Observe circuit breaker state
+
+**Expected**: State should be OPEN after 3 failures
+**Actual**: State remains CLOSED
+
+**Environment**:
+- Kite version: 0.1.0
+- Python: 3.10.0
+- OS: Ubuntu 22.04
+```
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:
+
+- **Use a clear and descriptive title**
+- **Provide a detailed description** of the proposed functionality
+- **Explain why this enhancement would be useful**
+- **Provide examples** of how it would be used
+
+### Pull Requests
+
+1. **Fork the repo** and create your branch from `main`
+2. **Add tests** if you've added code that should be tested
+3. **Update documentation** if you've changed APIs
+4. **Ensure tests pass**: `pytest tests/`
+5. **Follow the code style**: `black kite/ && flake8 kite/`
+6. **Write a clear commit message**
+
+Example workflow:
+```bash
+# Fork and clone
+git clone https://github.com/thienzz/Kite.git
+cd Kite
+
+# Create branch
+git checkout -b feature/my-new-feature
+
+# Make changes
+# ... code ...
+
+# Test
+pytest tests/
+
+# Format
+black kite/
+flake8 kite/
+
+# Commit
+git add .
+git commit -m "Add feature: description"
+
+# Push
+git push origin feature/my-new-feature
+
+# Open Pull Request on GitHub
+```
+
+## Development Setup
+```bash
+# Clone repository
+git clone https://github.com/thienzz/Kite.git
+cd Kite
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+pip install -e ".[dev]"  # Install in editable mode with dev dependencies
+
+# Run tests
+pytest tests/
+
+# Run examples
+python examples/case1_ecommerce_support.py
+```
+
+## Code Style
+
+- Follow PEP 8
+- Use `black` for formatting: `black kite/`
+- Use `flake8` for linting: `flake8 kite/`
+- Use type hints where possible
+- Write docstrings for public APIs
+
+Example:
+```python
+def create_agent(
+    self, 
+    name: str, 
+    system_prompt: str = "", 
+    tools: Optional[List[Tool]] = None,
+    **kwargs
+) -> Agent:
+    """
+    Create a general-purpose agent.
+    
+    Args:
+        name: Agent name
+        system_prompt: System prompt for the agent
+        tools: List of tools available to the agent
+        **kwargs: Additional configuration
+        
+    Returns:
+        Agent instance with configured tools
+        
+    Example:
+        >>> agent = ai.create_agent(
+        ...     name="Assistant",
+        ...     system_prompt="You are helpful",
+        ...     tools=[search_tool]
+        ... )
+    """
+    # Implementation
+```
+
+## Testing
+
+- Write unit tests for new features
+- Ensure existing tests pass
+- Aim for >70% code coverage
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest --cov=kite tests/
+
+# Run specific test
+pytest tests/test_circuit_breaker.py
+```
+
+## Documentation
+
+- Update README.md if adding major features
+- Update docs/ for API changes
+- Add examples for new functionality
+- Keep CHANGELOG.md updated
+
+## Questions?
+
+Feel free to open an issue with the "question" label or reach out to maintainers.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

kite_agent-0.1.0/LICENSE

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

kite_agent-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include requirements.txt
+include requirements_no_vllm.txt
+include CHANGELOG.md
+include CONTRIBUTING.md
+recursive-include kite *.json *.yaml *.yml *.txt