RouteKitAI 0.1.0__tar.gz

routekitai-0.1.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project 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).
+
+## [Unreleased]
+
+### Added
+- Initial project scaffold
+- Core primitives: Model, Message, Tool, Agent, Runtime
+- Graph-based orchestration with nodes, edges, and state management
+- Step-based execution with complete trace capture
+- Immutable trace format with event logging
+- Deterministic replay engine with stub support
+- Policy system: ReAct, FunctionCalling, Graph, Supervisor, PlanExecute
+- Memory backends: EpisodicMemory, RetrievalMemory
+- Security hooks: PII redaction, tool filtering, approval gates
+- CLI tools: run, trace, replay, test-agent commands
+- Evaluation harness with dataset support and regression testing
+- Multi-agent supervisor pattern with delegation
+- Error handling with context and proper exception types
+- Type-safe APIs with full mypy compliance
+- Async-first design with asyncio support
+- Development tooling: ruff, mypy, pytest configuration
+- Comprehensive test suite
+- Documentation: architecture, security, examples
+
+### Changed
+- N/A (initial release)
+
+### Deprecated
+- N/A (initial release)
+
+### Removed
+- N/A (initial release)
+
+### Fixed
+- N/A (initial release)
+
+### Security
+- PII redaction for emails, phones, and custom patterns
+- Tool allow/deny lists at agent and runtime levels
+- Approval gates for high-risk permissions
+- Trace security with redaction support
+
+## [0.1.0] - 2024-01-XX
+
+### Added
+- Initial public release
+- Core framework functionality
+- Graph orchestration
+- Tracing and replay
+- Security features
+- CLI tools
+
+---
+
+## Version History
+
+- **0.1.0**: Initial release with core features
+
+## Upcoming Features
+
+See [Architecture Guide](docs/architecture.md#future-directions) for planned features.
+
+## Contributing
+
+See [Contributing Guide](CONTRIBUTING.md) (coming soon) for how to contribute changes.

routekitai-0.1.0/LICENSE

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

routekitai-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py
+global-exclude __pycache__
+global-exclude *.py[co]
+global-exclude .DS_Store

routekitai-0.1.0/PKG-INFO

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: RouteKitAI
+Version: 0.1.0
+Summary: An agent development + orchestration framework
+Author: Mohamed Ghassen Brahim
+License: MIT
+Project-URL: Homepage, https://github.com/MedGhassen/RouteKit
+Project-URL: Documentation, https://routekit.readthedocs.io
+Project-URL: Repository, https://github.com/MedGhassen/RouteKit
+Project-URL: Issues, https://github.com/MedGhassen/RouteKit/issues
+Keywords: ai,agents,orchestration,llm,framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: numpy<3.0.0,>=1.24.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.1.0; extra == "dev"
+Requires-Dist: rich>=13.0.0; extra == "dev"
+Requires-Dist: typer>=0.9.0; extra == "dev"
+Requires-Dist: safety>=2.0.0; extra == "dev"
+Requires-Dist: bandit>=1.7.0; extra == "dev"
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.104.0; extra == "ui"
+Requires-Dist: uvicorn[standard]>=0.24.0; extra == "ui"
+Provides-Extra: optional
+Requires-Dist: sentence-transformers>=2.2.0; extra == "optional"
+Requires-Dist: faiss-cpu>=1.7.4; extra == "optional"
+Requires-Dist: openai>=1.0.0; extra == "optional"
+Requires-Dist: nest-asyncio>=1.5.0; extra == "optional"
+Dynamic: license-file
+
+# RouteKitAI
+
+<div align="center">
+
+**A minimal, production-ready framework for building and orchestrating AI agents**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Type checking: mypy](https://img.shields.io/badge/type%20checking-mypy-blue)](http://mypy-lang.org/)
+
+[Features](#features) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Examples](#examples) • [Contributing](#contributing)
+
+</div>
+
+---
+
+RouteKitAI is a Python framework for building AI agents with **graph-based orchestration**, **built-in tracing**, and **deterministic replay**. Unlike other frameworks, RouteKitAI treats observability and testability as first-class features from day one.
+
+## ✨ Features
+
+### 🎯 Core Capabilities
+
+- **Graph-Native Orchestration**: Define agent workflows as explicit graphs with clear control flow
+- **Automatic Tracing**: Every execution produces a complete, immutable trace log
+- **Deterministic Replay**: Reproduce any agent run exactly for testing and debugging
+- **Type-Safe APIs**: Full type hints with mypy compliance
+- **Async-First**: Built for modern Python async/await patterns
+- **Minimal API**: Just 5 core primitives—no bloat
+
+### 🛡️ Production Features
+
+- **Security Hooks**: PII redaction, tool allow/deny lists, approval gates
+- **Memory Support**: Episodic, retrieval, and vector memory backends
+- **Policy System**: ReAct, Supervisor, Graph, and custom policies
+- **Error Handling**: Comprehensive error types with context
+- **CLI Tools**: Run, trace, replay, and test agents from the command line
+- **Trace Analysis**: Metrics, timeline visualization, step-by-step debugging, and search
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install RouteKitAI
+```
+
+For development with CLI tools:
+
+```bash
+pip install "RouteKitAI[dev]"
+```
+
+### Basic Example
+
+```python
+import asyncio
+from routekitai import Agent
+from routekitai.providers.local import FakeModel
+from routekitai.core.tools import EchoTool
+
+# Create a model
+model = FakeModel(name="test")
+model.add_response("Hello from routekitai!")
+
+# Create an agent
+agent = Agent(
+    name="my_agent",
+    model=model,
+    tools=[EchoTool()]
+)
+
+# Run the agent
+async def main():
+    result = await agent.run("Hello!")
+    print(result.output.content)
+    print(f"Trace ID: {result.trace_id}")
+
+asyncio.run(main())
+```
+
+### Graph-Based Workflow
+
+```python
+import asyncio
+from routekitai import Agent
+from routekitai.core.policies import GraphPolicy
+from routekitai.graphs import Graph, GraphNode, GraphEdge, NodeType
+from routekitai.providers.local import FakeModel
+from routekitai.core.tools import EchoTool
+
+# Create models and agents
+model1 = FakeModel(name="model1")
+model1.add_response("Processing input...")
+
+model2 = FakeModel(name="model2")
+model2.add_response("Finalizing result...")
+
+agent1 = Agent(name="agent1", model=model1, tools=[EchoTool()])
+agent2 = Agent(name="agent2", model=model2, tools=[])
+
+# Define a graph: agent1 -> tool -> agent2
+graph = Graph(
+    name="example_graph",
+    entry_node="start",
+    exit_node="end",
+    nodes=[
+        GraphNode(
+            id="start",
+            type=NodeType.MODEL,
+            agent_name="agent1",
+            output_mapping={"output": "processed_input"},
+        ),
+        GraphNode(
+            id="echo_tool",
+            type=NodeType.TOOL,
+            tool_name="echo",
+            input_mapping={"processed_input": "message"},
+            output_mapping={"result": "echo_result"},
+        ),
+        GraphNode(
+            id="end",
+            type=NodeType.MODEL,
+            agent_name="agent2",
+            input_mapping={"echo_result": "prompt"},
+        ),
+    ],
+    edges=[
+        GraphEdge(source="start", target="echo_tool"),
+        GraphEdge(source="echo_tool", target="end"),
+    ],
+)
+
+# Create agent with graph policy
+agent = Agent(
+    name="graph_agent",
+    model=model1,
+    policy=GraphPolicy(graph=graph)
+)
+
+# Run the agent
+async def main():
+    result = await agent.run("Process this task")
+    print(result.output.content)
+
+asyncio.run(main())
+```
+
+## 📚 Documentation
+
+- **[Architecture Guide](docs/architecture.md)**: Deep dive into RouteKitAI's design
+- **[Security & Governance](docs/security-and-governance.md)**: Security features and best practices
+- **[API Reference](https://RouteKitAI.readthedocs.io)**: Complete API documentation (coming soon)
+
+## 🎓 Examples
+
+Check out the [`examples/`](examples/) directory for complete examples:
+
+- **[Basic Agent](examples/hello_RouteKitAI.py)**: Simple agent with tools
+- **[Graph Orchestration](examples/graph_agent.py)**: Multi-agent workflow
+- **[Supervisor Pattern](examples/supervisor_agent.py)**: Supervisor delegating to sub-agents
+- **[Evaluation Harness](examples/eval_regression.py)**: Testing agents with datasets
+
+## 🛠️ CLI Commands
+
+RouteKitAI provides a CLI for common operations:
+
+```bash
+# Run an agent script
+RouteKitAI run agent_script.py
+
+# View a trace (multiple formats available)
+RouteKitAI trace <trace_id>                    # Table view (default)
+RouteKitAI trace <trace_id> --format timeline  # Timeline visualization
+RouteKitAI trace <trace_id> --format steps     # Step-by-step execution
+RouteKitAI trace <trace_id> --format json      # JSON output
+RouteKitAI trace <trace_id> --format raw       # Raw JSONL
+
+# Analyze trace metrics
+RouteKitAI trace-analyze <trace_id>            # Performance metrics, token usage, costs
+
+# Search traces
+RouteKitAI trace-search "error"                # Search all traces for "error"
+RouteKitAI trace-search "model" --trace-id abc # Search specific trace
+RouteKitAI trace-search "tool" --event-type tool_called  # Filter by event type
+
+# Replay a trace
+RouteKitAI replay <trace_id> --agent my_agent
+
+# Start web UI for trace visualization
+RouteKitAI serve                    # Start on default port 8080
+RouteKitAI serve --port 3000        # Custom port
+RouteKitAI serve --host 0.0.0.0     # Make accessible from network
+
+# Run sanity checks
+RouteKitAI test-agent
+```
+
+## 🏗️ Core Primitives
+
+RouteKitAI keeps it minimal with 5 core primitives:
+
+1. **Model**: LLM interface abstraction
+2. **Message**: Conversation message representation
+3. **Tool**: Callable function/tool definition
+4. **Agent**: Agent with model and tools
+5. **Runtime**: Orchestration and execution engine
+
+## 🧪 Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/MedGhassen/RouteKitAI.git
+cd RouteKitAI
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=RouteKitAI --cov-report=html
+
+# Run specific test file
+pytest tests/test_runtime.py
+```
+
+### Code Quality
+
+```bash
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/
+
+# Format code
+ruff format src/
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines (coming soon) and:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📋 Requirements
+
+- Python 3.11 or higher
+- Pydantic 2.0+
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+RouteKitAI is inspired by the need for testable, observable AI agent frameworks. Special thanks to the open-source community for their contributions and feedback.
+
+## 🔗 Links
+
+- **GitHub**: [https://github.com/MedGhassen/RouteKitAI](https://github.com/MedGhassen/RouteKitAI)
+- **Documentation**: [https://RouteKitAI.readthedocs.io](https://RouteKitAI.readthedocs.io) (coming soon)
+- **Issues**: [https://github.com/MedGhassen/RouteKitAI/issues](https://github.com/MedGhassen/RouteKitAI/issues)
+
+---
+
+<div align="center">
+
+Made with ❤️ by the Mohamed Ghassen Brahim
+
+</div>