@aurite-ai/kai 0.2.0-dev.0

package/dist/templates/frameworks/langgraph/src/agent/state.py

@@ -0,0 +1,65 @@
+"""
+Agent State Definition
+
+This module defines the state schema for the LangGraph agent using TypedDict.
+State is the shared data structure that flows through the graph, representing
+the current snapshot of your application at any point.
+
+Key Concepts:
+- TypedDict provides type hints for state keys
+- Annotated types with reducers control how updates are applied
+- Default reducer overwrites; operator.add appends to lists
+- MessagesState is a common pattern for chat-based agents
+"""
+
+import operator
+from typing import Annotated
+
+from langchain_core.messages import AnyMessage
+from typing_extensions import TypedDict
+
+
+class AgentState(TypedDict):
+    """
+    State schema for the agent.
+
+    This TypedDict defines all the data that flows through the graph.
+    Each key can have a reducer function that determines how updates
+    are merged with existing state.
+
+    Attributes:
+        messages: List of conversation messages. Uses operator.add as reducer,
+                  meaning new messages are appended to the existing list rather
+                  than replacing it. This is essential for maintaining conversation
+                  history across multiple turns.
+
+        tool_call_count: Tracks how many tool calls have been made. Uses default
+                         reducer (overwrite), so each update replaces the previous
+                         value. Useful for limiting tool call loops.
+
+    Example state flow:
+        Initial: {"messages": [HumanMessage("Hi")], "tool_call_count": 0}
+        After LLM: {"messages": [HumanMessage("Hi"), AIMessage("Hello!")], "tool_call_count": 0}
+        After tool: {"messages": [..., ToolMessage("result")], "tool_call_count": 1}
+    """
+
+    # Messages use operator.add as a reducer, which appends new messages
+    # to the existing list rather than replacing it entirely.
+    # This is critical for maintaining conversation history.
+    messages: Annotated[list[AnyMessage], operator.add]
+
+    # Tool call count uses the default reducer (overwrite).
+    # Each update replaces the previous value.
+    tool_call_count: int
+
+
+# Alternative: You could also use the built-in MessagesState for simpler cases:
+#
+# from langgraph.graph import MessagesState
+#
+# class AgentState(MessagesState):
+#     """Extends MessagesState with additional fields."""
+#     tool_call_count: int
+#
+# MessagesState already includes 'messages' with the add_messages reducer,
+# which handles message ID tracking and deduplication.

package/dist/templates/frameworks/langgraph/src/agent/tools.py

@@ -0,0 +1,30 @@
+"""
+Tool Definitions
+
+Tools are functions the LLM can call. Use the @tool decorator.
+See pattern below - implement your scenario-specific tools here.
+"""
+
+from langchain_core.tools import tool
+
+# Example tool pattern (implement your own for your scenario):
+#
+# @tool
+# def my_tool(param: str) -> str:
+#     """Brief description for the LLM.
+#
+#     Args:
+#         param: Description of the parameter
+#
+#     Returns:
+#         Description of what is returned
+#     """
+#     # Implementation
+#     return result
+
+
+# Add your tools to this list
+tools = []
+
+# Dictionary for quick tool lookup by name
+tools_by_name = {tool.name: tool for tool in tools}

package/dist/templates/frameworks/openai/README.md

@@ -0,0 +1,131 @@
+# OpenAI Agents Framework
+
+A minimal but functional OpenAI Agents SDK project demonstrating core agent patterns.
+
+## Overview
+
+This scaffold provides a working OpenAI agent with:
+- Basic agent setup with instructions
+- Tool calling with function decorators
+- Multi-agent handoffs for routing
+- Conversation management patterns
+- Well-commented code for learning
+
+## Requirements
+
+- Python 3.11+
+- `uv` (recommended) or `pip`
+
+## Setup
+
+### Using uv (Recommended)
+
+```bash
+# Create and activate virtual environment
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+uv pip install -e .
+```
+
+### Using pip
+
+```bash
+# Create and activate virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -e .
+```
+
+## Configuration
+
+Set your OpenAI API key as an environment variable:
+
+```bash
+export OPENAI_API_KEY="your-key-here"
+```
+
+## Running the Agent
+
+```bash
+# Run with default example
+python main.py
+
+# Or import and use programmatically
+python -c "from src.agent import run_agent; import asyncio; asyncio.run(run_agent('Your prompt here'))"
+```
+
+## Project Structure
+
+```
+openai/
+├── README.md              # This file
+├── pyproject.toml         # Project configuration
+├── main.py                # Entry point
+└── src/
+    └── agent/
+        ├── __init__.py    # Package exports
+        ├── tools.py       # Tool definitions (implement your scenario tools here)
+        └── agents.py      # Agent definitions and runner
+```
+
+## Extending the Agent
+
+### Adding New Tools
+
+1. Define your tool in `src/agent/tools.py`:
+
+```python
+from typing import Annotated
+from pydantic import BaseModel, Field
+from agents import function_tool
+
+class MyResult(BaseModel):
+    value: str = Field(description="The result value")
+
+@function_tool
+def my_new_tool(param: Annotated[str, "Description of the parameter"]) -> MyResult:
+    """Description of what the tool does."""
+    return MyResult(value="result")
+```
+
+2. Add it to the agent's `tools` list in `src/agent/agents.py`.
+
+### Adding New Agents
+
+Edit `src/agent/agents.py` to add specialist agents:
+
+```python
+specialist_agent = Agent(
+    name="Specialist Agent",
+    handoff_description="Handles specific domain tasks",
+    instructions="You are an expert in...",
+    tools=[my_tool],
+)
+
+# Add to triage agent's handoffs
+triage_agent = Agent(
+    name="Triage Agent",
+    instructions="Route requests to specialists.",
+    handoffs=[specialist_agent],
+)
+```
+
+### Conversation Management
+
+The example uses manual history management with `result.to_input_list()`. For persistent conversations, consider:
+
+- **SQLiteSession**: Local session storage
+- **conversation_id**: Server-managed conversations
+- **previous_response_id**: Lightweight continuation
+
+See the OpenAI Agents documentation for details.
+
+## Learning Resources
+
+- [OpenAI Agents SDK Documentation](https://github.com/openai/openai-agents-python)
+- [OpenAI API Reference](https://platform.openai.com/docs/api-reference)
+- See `.claude/rules/openai-agents.md` for patterns and best practices

package/dist/templates/frameworks/openai/main.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+OpenAI Agents SDK Entry Point
+
+This script demonstrates how to run the OpenAI agent with example queries.
+It shows both simple execution and multi-turn conversation patterns.
+
+Usage:
+    # Run with default examples
+    python main.py
+
+    # Import and use programmatically
+    from src.agent import run_agent
+    import asyncio
+    result = asyncio.run(run_agent("What is 10 + 5?"))
+"""
+
+import asyncio
+import sys
+from agents import Runner
+
+
+async def main():
+    """Run the agent with example queries."""
+    # Import here to catch any configuration errors early
+    try:
+        from src.agent import create_agent, run_agent
+    except ValueError as e:
+        print(f"Configuration error: {e}")
+        print("\nPlease set your API key:")
+        print("  export OPENAI_API_KEY='your-key-here'")
+        sys.exit(1)
+
+    print("=" * 50)
+    print("OpenAI Agents SDK Demo")
+    print("=" * 50)
+
+    # Example queries that demonstrate tool usage
+    example_queries = [
+        "What is 15 + 27?",
+        "Calculate 8 * 12",
+        "What is 100 divided by 4?",
+    ]
+
+    print("\nRunning example queries...\n")
+
+    for query in example_queries:
+        print(f"User: {query}")
+        try:
+            response = await run_agent(query)
+            print(f"Agent: {response}\n")
+        except Exception as e:
+            print(f"Error: {e}\n")
+
+    # Demonstrate multi-turn conversation
+    print("-" * 50)
+    print("Multi-turn conversation example:")
+    print("-" * 50)
+
+    agent = create_agent()
+
+    # First turn
+    print("\nUser: What city is the Golden Gate Bridge in?")
+    result = await Runner.run(agent, "What city is the Golden Gate Bridge in?")
+    print(f"Agent: {result.final_output}")
+
+    # Second turn - using conversation history
+    print("\nUser: What state is it in?")
+    inputs = result.to_input_list() + [
+        {"role": "user", "content": "What state is it in?"}
+    ]
+    result = await Runner.run(agent, inputs)
+    print(f"Agent: {result.final_output}")
+
+    # Show conversation summary
+    print(f"\nTotal messages in conversation: {len(result.to_input_list())}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/dist/templates/frameworks/openai/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "openai-agent"
+version = "0.1.0"
+description = "A minimal OpenAI Agents SDK scaffold for learning and testing"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "openai-agents>=0.1.0",
+    "openai>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

package/dist/templates/frameworks/openai/src/agent/__init__.py

@@ -0,0 +1,18 @@
+"""
+OpenAI Agents SDK Package
+
+This package provides a simple agent setup with tools and multi-agent routing.
+"""
+
+from .agents import create_agent, run_agent, triage_agent
+from .tools import add, divide, multiply, subtract
+
+__all__ = [
+    "create_agent",
+    "run_agent",
+    "triage_agent",
+    "add",
+    "subtract",
+    "multiply",
+    "divide",
+]

package/dist/templates/frameworks/openai/src/agent/agents.py

@@ -0,0 +1,122 @@
+"""
+Agent Definitions and Runner
+
+This module defines the agents and provides convenience functions for running them.
+
+The OpenAI Agents SDK uses:
+- Agent: Defines an agent with name, instructions, tools, and handoffs
+- Runner: Executes agents with the agent loop (LLM calls, tool execution, handoffs)
+
+Agent Patterns:
+1. Single Agent: One agent with tools
+2. Handoffs: Specialist agents that take over the conversation
+3. Agents as Tools: Orchestrator calls specialists as tools (not shown here)
+"""
+
+import os
+
+from agents import Agent, Runner
+
+from .tools import add, divide, multiply, subtract
+
+
+def _check_api_key():
+    """Verify that the OpenAI API key is set."""
+    if not os.getenv("OPENAI_API_KEY"):
+        raise ValueError(
+            "OPENAI_API_KEY environment variable is not set. "
+            "Please set it with: export OPENAI_API_KEY='your-key-here'"
+        )
+
+
+# Define specialist agents for multi-agent routing
+# These agents handle specific types of requests
+
+math_agent = Agent(
+    name="Math Agent",
+    handoff_description="Specialist agent for mathematical calculations and problems",
+    instructions=(
+        "You are a math expert. Solve mathematical problems step by step. "
+        "Use the available tools to perform calculations. "
+        "Explain your reasoning clearly."
+    ),
+    tools=[add, subtract, multiply, divide],
+)
+
+general_agent = Agent(
+    name="General Agent",
+    handoff_description="General purpose agent for non-mathematical questions",
+    instructions=(
+        "You are a helpful general assistant. "
+        "Answer questions clearly and concisely. "
+        "If a question requires mathematical calculation, "
+        "explain that you've been handed off from the triage agent."
+    ),
+)
+
+# Define the main triage agent that routes to specialists
+# This demonstrates the handoff pattern
+
+triage_agent = Agent(
+    name="Triage Agent",
+    instructions=(
+        "You are a routing agent. Analyze each user request and hand off to the "
+        "appropriate specialist agent:\n"
+        "- Math Agent: For calculations, equations, and mathematical problems\n"
+        "- General Agent: For all other questions\n\n"
+        "Always hand off to a specialist - do not answer directly."
+    ),
+    handoffs=[math_agent, general_agent],
+)
+
+
+def create_agent() -> Agent:
+    """Create and return the main agent.
+
+    This is a convenience function that checks configuration and returns
+    the triage agent. Modify this to return a different agent if needed.
+
+    Returns:
+        The configured agent ready to run
+
+    Raises:
+        ValueError: If OPENAI_API_KEY is not set
+    """
+    _check_api_key()
+    return triage_agent
+
+
+async def run_agent(user_input: str | list[dict]) -> str:
+    """Run the agent with the given input and return the final output.
+
+    This is a convenience function for simple agent execution. For more control,
+    use Runner.run() directly with the agent.
+
+    Args:
+        user_input: Either a string message or a list of message dicts
+                   (for multi-turn conversations)
+
+    Returns:
+        The agent's final output as a string
+
+    Raises:
+        ValueError: If OPENAI_API_KEY is not set
+        Exception: If the agent execution fails
+    """
+    agent = create_agent()
+    result = await Runner.run(agent, user_input)
+    return result.final_output
+
+
+# Example: Creating a simple single-agent setup (alternative to triage)
+# Uncomment and modify create_agent() to use this instead
+
+# simple_agent = Agent(
+#     name="Calculator Agent",
+#     instructions=(
+#         "You are a helpful calculator assistant. "
+#         "Use the available tools to perform calculations. "
+#         "Show your work step by step."
+#     ),
+#     tools=[add, subtract, multiply, divide],
+# )

package/dist/templates/frameworks/openai/src/agent/tools.py

@@ -0,0 +1,100 @@
+"""
+Tool Definitions
+
+This module defines the tools available to the agent. Tools are Python functions
+decorated with @function_tool that the agent can call to perform actions.
+
+The OpenAI Agents SDK automatically:
+- Converts function signatures to tool schemas
+- Handles tool calling and result passing
+- Validates inputs using type hints and Pydantic models
+
+To add a new tool:
+1. Define a function with clear type hints
+2. Add a descriptive docstring (becomes tool description)
+3. Decorate with @function_tool
+4. Add to the agent's tools list in agents.py
+"""
+
+from typing import Annotated
+
+from agents import function_tool
+
+
+# Example: Simple function tool with primitive return type
+@function_tool
+def add(
+    a: Annotated[float, "The first number"],
+    b: Annotated[float, "The second number"],
+) -> float:
+    """Add two numbers together.
+
+    Args:
+        a: The first number to add
+        b: The second number to add
+
+    Returns:
+        The sum of a and b
+    """
+    return a + b
+
+
+@function_tool
+def subtract(
+    a: Annotated[float, "The first number"],
+    b: Annotated[float, "The second number"],
+) -> float:
+    """Subtract the second number from the first.
+
+    Args:
+        a: The number to subtract from
+        b: The number to subtract
+
+    Returns:
+        The difference (a - b)
+    """
+    return a - b
+
+
+@function_tool
+def multiply(
+    a: Annotated[float, "The first number"],
+    b: Annotated[float, "The second number"],
+) -> float:
+    """Multiply two numbers together.
+
+    Args:
+        a: The first number to multiply
+        b: The second number to multiply
+
+    Returns:
+        The product of a and b
+    """
+    return a * b
+
+
+@function_tool
+def divide(
+    a: Annotated[float, "The numerator"],
+    b: Annotated[float, "The denominator"],
+) -> float:
+    """Divide the first number by the second.
+
+    Args:
+        a: The number to divide (numerator)
+        b: The number to divide by (denominator)
+
+    Returns:
+        The quotient (a / b)
+
+    Raises:
+        ValueError: If b is zero
+    """
+    if b == 0:
+        raise ValueError("Cannot divide by zero")
+    return a / b
+
+
+# List of all tools to export
+# Add new tools here to make them available for import
+tools = [add, subtract, multiply, divide]

package/dist/templates/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Template access utilities for file-based templates.
+ *
+ * Templates are stored as files in the templates/ directory and are
+ * read from the filesystem at runtime. This makes templates easier
+ * to maintain and edit compared to embedding them as strings.
+ */
+/**
+ * A template file with its relative path and content.
+ */
+export interface TemplateFile {
+    path: string;
+    content: string;
+}
+/**
+ * Framework template metadata.
+ */
+export interface FrameworkTemplate {
+    id: string;
+    name: string;
+    description: string;
+    path: string;
+}
+/**
+ * Copilot config template metadata.
+ */
+export interface CopilotConfigTemplate {
+    id: string;
+    name: string;
+    description: string;
+    path: string;
+}
+/**
+ * Available framework templates.
+ */
+export declare const FRAMEWORK_TEMPLATES: FrameworkTemplate[];
+/**
+ * Available copilot configuration templates.
+ */
+export declare const COPILOT_CONFIG_TEMPLATES: CopilotConfigTemplate[];
+/**
+ * Get a framework template by ID.
+ */
+export declare function getFrameworkTemplate(id: string): FrameworkTemplate | undefined;
+/**
+ * Get a copilot config template by ID.
+ */
+export declare function getCopilotConfigTemplate(id: string): CopilotConfigTemplate | undefined;
+/**
+ * List all available frameworks.
+ */
+export declare function listFrameworks(): FrameworkTemplate[];
+/**
+ * List all available copilot configs.
+ */
+export declare function listCopilotConfigs(): CopilotConfigTemplate[];
+/**
+ * Get project-level template files (.env template, .gitignore).
+ */
+export declare function getProjectFiles(): Promise<TemplateFile[]>;
+/**
+ * Get LangGraph framework files.
+ */
+export declare function getLangGraphFiles(): Promise<TemplateFile[]>;
+/**
+ * Get OpenAI framework files.
+ */
+export declare function getOpenAIFiles(): Promise<TemplateFile[]>;
+/**
+ * Get Claude Code configuration files.
+ */
+export declare function getClaudeCodeFiles(): Promise<TemplateFile[]>;
+/**
+ * Get knowledge base seed files.
+ */
+export declare function getKnowledgeBaseFiles(): Promise<TemplateFile[]>;
+/**
+ * Get template files for a framework.
+ */
+export declare function getFrameworkFiles(frameworkId: string): Promise<TemplateFile[]>;
+/**
+ * Get config files for a copilot.
+ */
+export declare function getCopilotConfigFiles(copilotId: string): Promise<TemplateFile[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AA8FD;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAiB,EAclD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,qBAAqB,EAO3D,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAE9E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAEtF;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,iBAAiB,EAAE,CAEpD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,qBAAqB,EAAE,CAE5D;AAkED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAc/D;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAIjE;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAI9D;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAIlE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAIrE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CASpF;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAOtF"}