koboi-agent 0.1.0__tar.gz

koboi_agent-0.1.0/LICENSE

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

koboi_agent-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: koboi-agent
+Version: 0.1.0
+Summary: Universal configurable AI agent framework — production-grade, YAML-driven, open-source ready.
+Author: Koboi Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/koboi-ai/koboi-agent
+Project-URL: Repository, https://github.com/koboi-ai/koboi-agent
+Project-URL: Documentation, https://github.com/koboi-ai/koboi-agent#readme
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: tracing
+Requires-Dist: langfuse<3.0,>=2.0; extra == "tracing"
+Provides-Extra: tui
+Requires-Dist: rich>=13.0; extra == "tui"
+Requires-Dist: textual>=0.40; extra == "tui"
+Requires-Dist: click>=8.0; extra == "tui"
+Requires-Dist: prompt_toolkit>=3.0; extra == "tui"
+Requires-Dist: rapidfuzz>=3.0; extra == "tui"
+Provides-Extra: eval-ragas
+Requires-Dist: ragas>=0.2; extra == "eval-ragas"
+Requires-Dist: datasets>=2.14; extra == "eval-ragas"
+Provides-Extra: eval-gaia
+Requires-Dist: datasets>=2.14; extra == "eval-gaia"
+Requires-Dist: pandas>=2.0; extra == "eval-gaia"
+Provides-Extra: eval-swe-bench
+Requires-Dist: datasets>=2.14; extra == "eval-swe-bench"
+Requires-Dist: pandas>=2.0; extra == "eval-swe-bench"
+Provides-Extra: eval-deepeval
+Requires-Dist: deepeval>=0.20; extra == "eval-deepeval"
+Provides-Extra: eval-all
+Requires-Dist: ragas>=0.2; extra == "eval-all"
+Requires-Dist: datasets>=2.14; extra == "eval-all"
+Requires-Dist: pandas>=2.0; extra == "eval-all"
+Requires-Dist: deepeval>=0.20; extra == "eval-all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: langfuse<3.0,>=2.0; extra == "all"
+Requires-Dist: rich>=13.0; extra == "all"
+Requires-Dist: textual>=0.40; extra == "all"
+Requires-Dist: click>=8.0; extra == "all"
+Requires-Dist: prompt_toolkit>=3.0; extra == "all"
+Requires-Dist: rapidfuzz>=3.0; extra == "all"
+Requires-Dist: ragas>=0.2; extra == "all"
+Requires-Dist: datasets>=2.14; extra == "all"
+Requires-Dist: pandas>=2.0; extra == "all"
+Requires-Dist: deepeval>=0.20; extra == "all"
+Requires-Dist: pytest>=7.0; extra == "all"
+Requires-Dist: pytest-asyncio>=0.23; extra == "all"
+Requires-Dist: pytest-cov; extra == "all"
+Requires-Dist: pytest-benchmark>=4.0; extra == "all"
+Requires-Dist: ruff>=0.4.0; extra == "all"
+Requires-Dist: mypy>=1.0; extra == "all"
+Dynamic: license-file
+
+# koboi-agent
+
+Configurable AI agent framework. YAML-driven config, async Python 3.10+, multi-provider LLM (OpenAI, Anthropic, Cloudflare).
+
+## Features
+
+- **Multi-provider LLM**: OpenAI, Anthropic, Cloudflare Workers AI
+- **YAML-driven config** with `${ENV_VAR}` interpolation
+- **Built-in tools**: calculator, filesystem, shell, web search, memory, git, subagent, task
+- **Hook lifecycle**: 15 event types for logging, guardrails, telemetry
+- **RAG pipeline**: chunking (fixed/sentence/paragraph/semantic), retrieval (keyword/semantic/hybrid), augmentation
+- **Guardrails**: input/output validation, rate limiting, approval workflows, policy engine
+- **Multi-agent orchestration**: keyword/LLM/hybrid routing, sequential/parallel execution
+- **Context management**: truncation, smart truncation, key facts, sliding window
+- **MCP** client (stdio + HTTP) and server support
+- **Evaluation**: BFCL, GAIA, SWE-bench, RAGAS, DeepEval scorers
+- **Terminal UI** (Textual): chat, command palette, diff view, session management
+
+## Quickstart
+
+### Install
+
+```bash
+pip install -e ".[dev,tui]"
+```
+
+### Set your API key
+
+```bash
+cp .env.example .env
+# Edit .env and set OPENAI_API_KEY
+```
+
+### Run the CLI
+
+```bash
+koboi chat configs/simple_chat.yaml
+```
+
+### Run programmatically
+
+```python
+import asyncio
+from koboi import KoboiAgent
+
+async def main():
+    async with KoboiAgent.from_config("configs/simple_chat.yaml") as agent:
+        result = await agent.run("What is 2 + 2?")
+        print(result.content)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+Agents are configured via YAML. Key sections:
+
+```yaml
+agent:
+  name: "my-agent"
+  system_prompt: "You are helpful."
+  max_iterations: 10
+  mode: "chat"  # chat | plan | act | auto
+
+llm:
+  provider: "openai"        # openai | anthropic | cloudflare
+  model: "gpt-4o-mini"
+  api_key: "${OPENAI_API_KEY}"
+  base_url: "${OPENAI_BASE_URL:}"
+
+tools:
+  builtin: [calculator, web_search, memory_store, memory_recall]
+  custom:
+    - module: "my_tools"
+
+context:
+  strategy: "sliding_window"  # noop | truncation | smart_truncation | key_facts | sliding_window
+  max_context_tokens: 8000
+
+rag:
+  enabled: true
+  chunker: "paragraph"       # fixed | sentence | paragraph
+  retriever: "keyword"       # keyword | semantic
+  top_k: 3
+  documents:
+    - path: "./data/sample/product_catalog.md"
+
+guardrails:
+  input:
+    max_length: 10000
+  rate_limit:
+    max_calls_per_minute: 20
+
+harness:
+  doom_loop:
+    consecutive_identical_threshold: 3
+  telemetry: true
+  carryover: true
+```
+
+See `configs/` for full examples and `.claude/skills/yaml-config.md` for the complete schema.
+
+## Testing
+
+```bash
+pytest                        # all tests
+pytest tests/test_config.py   # single file
+pytest -k "hook"              # by keyword
+pytest --cov=koboi            # with coverage
+```
+
+## Examples
+
+`examples/` contains 28 numbered scripts covering every feature:
+
+| Range | Features |
+|-------|----------|
+| 01-04 | Basic chat and tool use |
+| 05-08 | Context management and RAG |
+| 09-10 | MCP client/server |
+| 11-14 | Policy, hooks, skills, custom tools |
+| 15-16 | Multi-agent orchestration |
+| 17 | Anthropic provider |
+| 18-20 | Harness (telemetry, doom loop, carryover) |
+| 21-24 | Evaluation, production setup, SWE-bench, config-driven orchestration |
+| 25-28 | Subagent delegation, task management, benchmarks, custom RAG |
+
+Run any example:
+
+```bash
+python examples/01_simple_chat.py              # automatic mode
+python examples/01_simple_chat.py -m interactive  # interactive mode
+```
+
+## Architecture
+
+For a detailed architecture overview (agent loop lifecycle, hook system, tool pipeline, extension points), see **[docs/architecture.md](docs/architecture.md)**.
+
+`KoboiAgent` (`facade.py`) is the single entry point. It assembles:
+
+- **AgentCore** (`loop.py`) -- async agent loop
+- **RetryClient** (`client.py`) -- LLM HTTP transport with retry
+- **ToolRegistry** (`tools/`) -- tool registration and execution
+- **HookChain** (`hooks/`) -- lifecycle event dispatch (15 events)
+- **ContextManager** (`context/`) -- context window strategies
+- **AugmentationStrategy** (`rag/`) -- RAG pipeline
+- **Guardrails** (`guardrails/`) -- input/output validation
+- **PolicyEngine** (`harness/`) -- rule-based tool filtering
+- **SkillRegistry** (`skills/`) -- skill discovery
+- **ModeManager** (`modes.py`) -- chat/plan/act/auto modes
+- **TrustDatabase** (`trust.py`) -- graduated permissions
+- **Orchestrator** (`orchestration/`) -- multi-agent coordination
+- **SubAgentManager** (`subagent.py`) -- parallel sub-agent delegation
+- **MCP clients** (`mcp/`) -- external tool servers
+
+All subsystems are configured from a single YAML file via `Config` (`config.py`).
+
+## License
+
+MIT

koboi_agent-0.1.0/README.md

@@ -0,0 +1,160 @@
+# koboi-agent
+
+Configurable AI agent framework. YAML-driven config, async Python 3.10+, multi-provider LLM (OpenAI, Anthropic, Cloudflare).
+
+## Features
+
+- **Multi-provider LLM**: OpenAI, Anthropic, Cloudflare Workers AI
+- **YAML-driven config** with `${ENV_VAR}` interpolation
+- **Built-in tools**: calculator, filesystem, shell, web search, memory, git, subagent, task
+- **Hook lifecycle**: 15 event types for logging, guardrails, telemetry
+- **RAG pipeline**: chunking (fixed/sentence/paragraph/semantic), retrieval (keyword/semantic/hybrid), augmentation
+- **Guardrails**: input/output validation, rate limiting, approval workflows, policy engine
+- **Multi-agent orchestration**: keyword/LLM/hybrid routing, sequential/parallel execution
+- **Context management**: truncation, smart truncation, key facts, sliding window
+- **MCP** client (stdio + HTTP) and server support
+- **Evaluation**: BFCL, GAIA, SWE-bench, RAGAS, DeepEval scorers
+- **Terminal UI** (Textual): chat, command palette, diff view, session management
+
+## Quickstart
+
+### Install
+
+```bash
+pip install -e ".[dev,tui]"
+```
+
+### Set your API key
+
+```bash
+cp .env.example .env
+# Edit .env and set OPENAI_API_KEY
+```
+
+### Run the CLI
+
+```bash
+koboi chat configs/simple_chat.yaml
+```
+
+### Run programmatically
+
+```python
+import asyncio
+from koboi import KoboiAgent
+
+async def main():
+    async with KoboiAgent.from_config("configs/simple_chat.yaml") as agent:
+        result = await agent.run("What is 2 + 2?")
+        print(result.content)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+Agents are configured via YAML. Key sections:
+
+```yaml
+agent:
+  name: "my-agent"
+  system_prompt: "You are helpful."
+  max_iterations: 10
+  mode: "chat"  # chat | plan | act | auto
+
+llm:
+  provider: "openai"        # openai | anthropic | cloudflare
+  model: "gpt-4o-mini"
+  api_key: "${OPENAI_API_KEY}"
+  base_url: "${OPENAI_BASE_URL:}"
+
+tools:
+  builtin: [calculator, web_search, memory_store, memory_recall]
+  custom:
+    - module: "my_tools"
+
+context:
+  strategy: "sliding_window"  # noop | truncation | smart_truncation | key_facts | sliding_window
+  max_context_tokens: 8000
+
+rag:
+  enabled: true
+  chunker: "paragraph"       # fixed | sentence | paragraph
+  retriever: "keyword"       # keyword | semantic
+  top_k: 3
+  documents:
+    - path: "./data/sample/product_catalog.md"
+
+guardrails:
+  input:
+    max_length: 10000
+  rate_limit:
+    max_calls_per_minute: 20
+
+harness:
+  doom_loop:
+    consecutive_identical_threshold: 3
+  telemetry: true
+  carryover: true
+```
+
+See `configs/` for full examples and `.claude/skills/yaml-config.md` for the complete schema.
+
+## Testing
+
+```bash
+pytest                        # all tests
+pytest tests/test_config.py   # single file
+pytest -k "hook"              # by keyword
+pytest --cov=koboi            # with coverage
+```
+
+## Examples
+
+`examples/` contains 28 numbered scripts covering every feature:
+
+| Range | Features |
+|-------|----------|
+| 01-04 | Basic chat and tool use |
+| 05-08 | Context management and RAG |
+| 09-10 | MCP client/server |
+| 11-14 | Policy, hooks, skills, custom tools |
+| 15-16 | Multi-agent orchestration |
+| 17 | Anthropic provider |
+| 18-20 | Harness (telemetry, doom loop, carryover) |
+| 21-24 | Evaluation, production setup, SWE-bench, config-driven orchestration |
+| 25-28 | Subagent delegation, task management, benchmarks, custom RAG |
+
+Run any example:
+
+```bash
+python examples/01_simple_chat.py              # automatic mode
+python examples/01_simple_chat.py -m interactive  # interactive mode
+```
+
+## Architecture
+
+For a detailed architecture overview (agent loop lifecycle, hook system, tool pipeline, extension points), see **[docs/architecture.md](docs/architecture.md)**.
+
+`KoboiAgent` (`facade.py`) is the single entry point. It assembles:
+
+- **AgentCore** (`loop.py`) -- async agent loop
+- **RetryClient** (`client.py`) -- LLM HTTP transport with retry
+- **ToolRegistry** (`tools/`) -- tool registration and execution
+- **HookChain** (`hooks/`) -- lifecycle event dispatch (15 events)
+- **ContextManager** (`context/`) -- context window strategies
+- **AugmentationStrategy** (`rag/`) -- RAG pipeline
+- **Guardrails** (`guardrails/`) -- input/output validation
+- **PolicyEngine** (`harness/`) -- rule-based tool filtering
+- **SkillRegistry** (`skills/`) -- skill discovery
+- **ModeManager** (`modes.py`) -- chat/plan/act/auto modes
+- **TrustDatabase** (`trust.py`) -- graduated permissions
+- **Orchestrator** (`orchestration/`) -- multi-agent coordination
+- **SubAgentManager** (`subagent.py`) -- parallel sub-agent delegation
+- **MCP clients** (`mcp/`) -- external tool servers
+
+All subsystems are configured from a single YAML file via `Config` (`config.py`).
+
+## License
+
+MIT

koboi_agent-0.1.0/koboi/__init__.py

@@ -0,0 +1,121 @@
+"""koboi — Universal configurable AI agent framework.
+
+Usage:
+    from koboi import KoboiAgent
+
+    agent = KoboiAgent.from_config("configs/sales_agent.yaml")
+    result = await agent.run("What products are available?")
+"""
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version as _get_version
+    __version__ = _get_version("koboi-agent")
+except Exception:
+    __version__ = "0.1.0"
+
+# --- Eager imports: lightweight, always needed ---
+from koboi.config import Config, ConfigBuilder
+from koboi.facade import KoboiAgent
+from koboi.types import (
+    RiskLevel, ToolDefinition, ToolCall, ToolResult,
+    TokenUsage, AgentResponse, RunResult,
+    GuardrailResult, AuditEntry, RateLimitConfig,
+    RoutingDecision, AgentResult, OrchestratorResult, AgentBlueprint, AgentDef,
+    MCPToolInfo, SkillDefinition,
+    EvalScore, EvalResult, EvalCase,
+)
+from koboi.client import RetryClient, Client, ClientError, RetryClientError
+from koboi.memory import ConversationMemory, MemoryBackend
+from koboi.tools.registry import ToolRegistry, tool, register_decorated
+from koboi.logger import AgentLogger
+from koboi.tokens import estimate_tokens, estimate_single
+from koboi.exceptions import (
+    AgentError, AgentMaxIterationsError, AgentGuardrailError,
+    AgentToolError, AgentTimeoutError, AgentStreamError, AgentAbortedError,
+)
+from koboi.events import (
+    StreamEvent, TextDeltaEvent, ToolCallEvent, ToolResultEvent,
+    IterationEvent, CompleteEvent, ErrorEvent,
+    RoutingDecisionEvent, AgentDispatchEvent, AgentResultEvent, OrchestrationCompleteEvent,
+)
+from koboi.hooks import HookEvent, HookContext, Hook, HookChain, HookOutcome, AgentInfo
+from koboi.hooks.callback_hook import CallbackHook
+
+# --- Lazy imports: heavier subsystems, loaded on first access ---
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # LLM
+    "LLMClient": ("koboi.llm.base", "LLMClient"),
+    "LLMError": ("koboi.llm.base", "LLMError"),
+    "LLMConnectionError": ("koboi.llm.base", "LLMConnectionError"),
+    "LLMAuthenticationError": ("koboi.llm.base", "LLMAuthenticationError"),
+    "LLMRateLimitError": ("koboi.llm.base", "LLMRateLimitError"),
+    "LLMServerError": ("koboi.llm.base", "LLMServerError"),
+    "LLMInvalidRequestError": ("koboi.llm.base", "LLMInvalidRequestError"),
+    "LLMResponseParseError": ("koboi.llm.base", "LLMResponseParseError"),
+    "create_client": ("koboi.llm.factory", "create_client"),
+    # Orchestration
+    "BaseRouter": ("koboi.orchestration.router", "BaseRouter"),
+    "KeywordRouter": ("koboi.orchestration.router", "KeywordRouter"),
+    "LLMRouter": ("koboi.orchestration.router", "LLMRouter"),
+    "HybridRouter": ("koboi.orchestration.router", "HybridRouter"),
+    "Orchestrator": ("koboi.orchestration.orchestrator", "Orchestrator"),
+    "QualityEvaluator": ("koboi.orchestration.orchestrator", "QualityEvaluator"),
+    "AgentFactory": ("koboi.orchestration.factory", "AgentFactory"),
+    "DynamicAgentBuilder": ("koboi.orchestration.factory", "DynamicAgentBuilder"),
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        import importlib
+        module = importlib.import_module(module_path)
+        return getattr(module, attr_name)
+    raise AttributeError(f"module 'koboi' has no attribute {name!r}")
+
+
+# Discover and load external plugins at import time
+try:
+    from koboi.plugins import discover_plugins as _discover_plugins
+    _discover_plugins()
+except Exception:
+    pass  # Plugin discovery is best-effort
+
+__all__ = [
+    # Core
+    "__version__", "KoboiAgent", "Config", "ConfigBuilder",
+    # Orchestration
+    "BaseRouter", "KeywordRouter", "LLMRouter", "HybridRouter",
+    "Orchestrator", "QualityEvaluator", "AgentFactory", "DynamicAgentBuilder",
+    # Types
+    "RiskLevel", "ToolDefinition", "ToolCall", "ToolResult",
+    "TokenUsage", "AgentResponse", "RunResult",
+    "GuardrailResult", "AuditEntry", "RateLimitConfig",
+    "RoutingDecision", "AgentResult", "OrchestratorResult", "AgentBlueprint", "AgentDef",
+    "MCPToolInfo", "SkillDefinition",
+    "EvalScore", "EvalResult", "EvalCase",
+    # Client
+    "RetryClient", "Client", "ClientError", "RetryClientError",
+    # Memory
+    "ConversationMemory", "MemoryBackend",
+    # Tools
+    "ToolRegistry", "tool", "register_decorated",
+    # Logging
+    "AgentLogger",
+    # Tokens
+    "estimate_tokens", "estimate_single",
+    # Exceptions
+    "AgentError", "AgentMaxIterationsError", "AgentGuardrailError",
+    "AgentToolError", "AgentTimeoutError", "AgentStreamError", "AgentAbortedError",
+    # Events
+    "StreamEvent", "TextDeltaEvent", "ToolCallEvent", "ToolResultEvent",
+    "IterationEvent", "CompleteEvent", "ErrorEvent",
+    "RoutingDecisionEvent", "AgentDispatchEvent", "AgentResultEvent", "OrchestrationCompleteEvent",
+    # Hooks
+    "HookEvent", "HookContext", "Hook", "HookChain", "HookOutcome", "AgentInfo", "CallbackHook",
+    # LLM
+    "LLMClient", "LLMError", "LLMConnectionError", "LLMAuthenticationError",
+    "LLMRateLimitError", "LLMServerError", "LLMInvalidRequestError", "LLMResponseParseError",
+    "create_client",
+]

koboi_agent-0.1.0/koboi/__main__.py

@@ -0,0 +1,16 @@
+"""Allow running koboi as `python -m koboi`."""
+from __future__ import annotations
+
+try:
+    from koboi.tui.app import main
+except ImportError:
+    import sys
+    print(
+        "Error: TUI dependencies not installed.\n"
+        "Install with: pip install koboi-agent[tui]",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+if __name__ == "__main__":
+    main()

koboi_agent-0.1.0/koboi/cli.py

@@ -0,0 +1,28 @@
+"""koboi/cli -- Console-script entry point with graceful TUI-dep handling."""
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    """Entry point for the ``koboi`` console script."""
+    try:
+        from koboi.tui.app import main as tui_main
+    except ImportError:
+        print(
+            "Error: TUI dependencies (click, rich, textual) are not installed.\n"
+            "\n"
+            "Install them with:\n"
+            "    pip install koboi-agent[tui]\n"
+            "\n"
+            "Or install everything:\n"
+            "    pip install koboi-agent[all]\n",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    tui_main()
+
+
+if __name__ == "__main__":
+    main()