@aurite-ai/kai 0.2.0-dev.0

package/dist/templates/copilot-configs/claude-code/.claude/skills/verification/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: verification
+description: Verify agent code against organizational policies and best practices. Trigger this skill when the user says something like "verify my agent", "review agent code", "check compliance", "audit my agent", "check my agent against rules", or "validate agent implementation"
+---
+
+# Verify Agent
+
+## Purpose
+
+Verify agent code against business rules, security policies, and framework best practices from Kai's knowledge base. All analysis happens locally—code never leaves the user's machine.
+
+## When to Use
+
+Trigger this skill when the user asks to:
+- "verify my agent"
+- "review agent code"
+- "check compliance"
+- "audit my agent"
+- "check my agent against rules"
+- "validate agent implementation"
+
+## Process
+
+> **Note:** This skill assumes organizational and IT rules are already available in the conversation context from the `kai_prepare_context` call at conversation start (per CLAUDE.md rules).
+
+### Step 1: Load Framework Best Practices
+
+Check the `context-guide.md` for framework-specific best practices surfaced by `kai_prepare_context`:
+
+These files define best practices, required patterns, and anti-patterns specific to that framework. Load and reference them during verification.
+
+If framework best practices aren't available in `context/`, use the **documentation** skill (`.claude/skills/documentation/SKILL.md`) to search for relevant framework documentation.
+### Step 2: Discover Agent Files
+
+Locate agent implementation files in the project. Check these common locations:
+
+**Directories:**
+- `src/agent/`
+- `agent/`
+- `src/`
+- Project root
+
+**Key files to analyze:**
+- `graph.py` - Main workflow/graph definition
+- `tools.py` - Tool implementations
+- `state.py` - State schema definitions
+- `prompts.py` - Prompt templates
+- `nodes.py` - Node function implementations
+- `config.py` - Configuration and settings
+
+Use `list_files` or similar to discover the actual structure, then read relevant files.
+
+### Step 3: Verify Code Against Rules
+
+Analyze the agent code against all available rules:
+
+1. **Organizational rules** - Check code against company policies from conversation context
+2. **IT/Security rules** - Check code against security requirements from conversation context
+3. **Framework best practices** - Check code against patterns from the framework best practices in `context-guide.md`
+
+For each rule, determine:
+- ✅ **Pass** - Code complies with the rule
+- ⚠️ **Warning** - Potential concern worth reviewing
+- ❌ **Issue** - Clear violation that needs fixing
+
+### Step 4: Generate Report
+
+Output a structured verification report:
+
+```markdown
+# Agent Verification Report
+
+**Project:** [project name or path]
+**Date:** [current date]
+**Files analyzed:** [list of files]
+
+## Summary
+
+✅ X checks passed | ⚠️ Y warnings | ❌ Z issues
+
+## Findings
+
+### ✅ Passing
+- [Check name]: [Brief confirmation of compliance]
+
+### ⚠️ Warnings
+- [Check name]: [Description of concern]
+  - **Location:** [file:line if applicable]
+  - **Suggestion:** [How to address]
+
+### ❌ Issues
+- [Check name]: [Description of violation]
+  - **Location:** [file:line]
+  - **Rule:** [Which rule this violates]
+  - **Fix:** [Specific remediation steps]
+
+## Recommendations
+
+1. [Priority recommendation based on findings]
+2. [Additional improvements]
+```
+
+### Step 5: Export Report (Optional)
+
+After presenting the report, ask the user:
+
+> Would you like to save this verification report to a file?
+
+If the user confirms, save the report to:
+
+```
+reports/verification/YYYY-MM-DD_HH-MM-SS.md
+```
+
+- Use the current date and time for the filename (e.g., `2026-02-10_15-28-32.md`)
+- Create the `reports/verification/` directory if it doesn't exist
+- Confirm the save location to the user after writing
+
+## Notes
+
+- **Privacy first:** All code analysis happens locally. Nothing is sent to external services.
+- **Rules come from Kai:** The knowledge base provides organization-specific rules. Apply them as written.
+- **Framework best practices:** Don't duplicate framework best practices here—reference files in `context-guide.md`.
+- **Be specific:** Include file names and line numbers when reporting issues.
+- **Explain the "why":** Help developers understand why each rule matters.

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

@@ -0,0 +1,118 @@
+# LangGraph Agent Framework
+
+A minimal but functional LangGraph Python project demonstrating core agent patterns.
+
+## Overview
+
+This scaffold provides a working LangGraph agent with:
+- State management using TypedDict
+- Tool calling with the ReAct pattern
+- Conditional routing based on tool calls
+- 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 API key as an environment variable:
+
+```bash
+# For Anthropic (default)
+export ANTHROPIC_API_KEY="your-key-here"
+
+# Or for OpenAI
+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; print(run_agent('Your prompt here'))"
+```
+
+## Project Structure
+
+```
+langgraph/
+├── README.md              # This file
+├── pyproject.toml         # Project configuration
+├── main.py                # Entry point
+└── src/
+    └── agent/
+        ├── __init__.py    # Package exports
+        ├── state.py       # State TypedDict definition
+        ├── tools.py       # Tool definitions (implement your scenario tools here)
+        └── graph.py       # Main StateGraph definition
+```
+
+## Extending the Agent
+
+### Adding New Tools
+
+1. Define your tool in `src/agent/tools.py`:
+
+```python
+@tool
+def my_new_tool(param: str) -> str:
+    """Description of what the tool does.
+
+    Args:
+        param: Description of the parameter
+    """
+    return "result"
+```
+
+2. Add it to the `tools` list in the same file.
+
+### Modifying State
+
+Edit `src/agent/state.py` to add new state fields:
+
+```python
+class AgentState(TypedDict):
+    messages: Annotated[list[AnyMessage], operator.add]
+    my_new_field: str  # Add new fields here
+```
+
+### Changing the Graph Structure
+
+Edit `src/agent/graph.py` to:
+- Add new nodes with `builder.add_node()`
+- Add new edges with `builder.add_edge()` or `builder.add_conditional_edges()`
+
+## Learning Resources
+
+- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
+- [LangChain Tools Guide](https://python.langchain.com/docs/modules/tools/)
+- See `.claude/rules/langgraph.md` for patterns and best practices

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

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+LangGraph Agent Entry Point
+
+This script demonstrates how to run the LangGraph agent with example queries.
+It shows both interactive conversation and programmatic usage patterns.
+
+Usage:
+    # Run with default examples
+    python main.py
+
+    # Import and use programmatically
+    from src.agent import run_agent
+    result = run_agent("What is 10 + 5?")
+"""
+
+import sys
+
+from langchain_core.messages import HumanMessage
+
+
+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 ANTHROPIC_API_KEY='your-key-here'")
+        print("  # or")
+        print("  export OPENAI_API_KEY='your-key-here'")
+        sys.exit(1)
+
+    print("=" * 50)
+    print("LangGraph Agent 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 = run_agent(query)
+            print(f"Agent: {response}\n")
+        except Exception as e:
+            print(f"Error: {e}\n")
+
+    # Demonstrate more detailed usage with state inspection
+    print("-" * 50)
+    print("Detailed execution example:")
+    print("-" * 50)
+
+    agent = create_agent()
+
+    # Run with full state tracking
+    initial_state = {
+        "messages": [HumanMessage(content="What is 25 multiplied by 4?")],
+        "tool_call_count": 0,
+    }
+
+    print(f"\nInitial query: {initial_state['messages'][0].content}")
+
+    # Execute the agent
+    final_state = agent.invoke(initial_state)
+
+    # Show the conversation flow
+    print("\nConversation flow:")
+    for i, msg in enumerate(final_state["messages"]):
+        msg_type = type(msg).__name__
+        # Handle content that may be a string or list (e.g., tool call blocks)
+        raw_content = msg.content
+        if isinstance(raw_content, list):
+            content = (
+                str(raw_content)[:100] + "..."
+                if len(str(raw_content)) > 100
+                else str(raw_content)
+            )
+        else:
+            content = (
+                raw_content[:100] + "..." if len(raw_content) > 100 else raw_content
+            )
+        print(f"  {i + 1}. [{msg_type}] {content}")
+
+    print(f"\nTotal tool calls: {final_state['tool_call_count']}")
+    print(f"Final answer: {final_state['messages'][-1].content}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,29 @@
+[project]
+name = "langgraph-agent"
+version = "0.1.0"
+description = "A minimal LangGraph agent scaffold for learning and testing"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "langgraph>=0.2.0",
+    "langchain>=0.3.0",
+    "langchain-anthropic>=0.2.0",
+    "langchain-openai>=0.2.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/langgraph/src/agent/__init__.py

@@ -0,0 +1,31 @@
+"""
+LangGraph Agent Package
+
+This package provides a minimal but functional LangGraph agent that demonstrates
+core patterns including state management, tool calling, and conditional routing.
+
+Example usage:
+    from agent import run_agent, create_agent
+
+    # Quick run with a message
+    result = run_agent("What is 15 + 27?")
+    print(result)
+
+    # Or get the compiled graph for more control
+    agent = create_agent()
+    result = agent.invoke({"messages": [HumanMessage(content="Hello")]})
+"""
+
+from .graph import create_agent, run_agent
+from .state import AgentState
+from .tools import add, divide, multiply, tools
+
+__all__ = [
+    "create_agent",
+    "run_agent",
+    "AgentState",
+    "tools",
+    "add",
+    "multiply",
+    "divide",
+]

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

@@ -0,0 +1,257 @@
+"""
+LangGraph Agent Definition
+
+This module defines the main StateGraph for the agent. It implements a standard
+ReAct-style (Reasoning + Acting) agent pattern where the LLM can decide to
+either respond directly or call tools to gather information.
+
+Key Concepts:
+- StateGraph: The container for nodes and edges
+- Nodes: Functions that perform work (LLM calls, tool execution)
+- Edges: Connections that determine flow between nodes
+- Conditional edges: Dynamic routing based on state
+
+Graph Structure:
+    START → call_model → [should_continue] → execute_tools → call_model
+                      ↘                                   ↗
+                        → END (if no tool calls)
+"""
+
+import os
+from typing import Literal
+
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+from langgraph.graph import END, START, StateGraph
+
+from .state import AgentState
+from .tools import tools, tools_by_name
+
+
+def get_model():
+    """
+    Initialize the LLM with tool binding.
+
+    This function creates the chat model and binds the available tools to it.
+    The model will include tool definitions in its context, allowing it to
+    decide when and how to call tools.
+
+    Returns:
+        A chat model instance with tools bound.
+
+    Note:
+        Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable.
+        Defaults to Anthropic if ANTHROPIC_API_KEY is set.
+    """
+    # Try Anthropic first (preferred), then fall back to OpenAI
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        from langchain_anthropic import ChatAnthropic
+
+        model = ChatAnthropic(model="claude-sonnet-4-5-20250929", temperature=0)
+    elif os.environ.get("OPENAI_API_KEY"):
+        from langchain_openai import ChatOpenAI
+
+        model = ChatOpenAI(model="gpt-4o", temperature=0)
+    else:
+        raise ValueError(
+            "No API key found. Set ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable."
+        )
+
+    # Bind tools to the model so it knows what tools are available
+    return model.bind_tools(tools)
+
+
+# System prompt that instructs the agent on its behavior
+SYSTEM_PROMPT = """You are a helpful assistant that can perform arithmetic operations.
+
+When asked to do math, use the available tools (add, multiply, divide) to compute the answer.
+Always show your work by using the appropriate tool calls.
+
+Be concise in your responses."""
+
+
+def call_model(state: AgentState) -> dict:
+    """
+    Node that calls the LLM to generate a response.
+
+    This node takes the current conversation state, prepends a system message,
+    and asks the LLM to generate a response. The LLM may decide to:
+    1. Respond directly to the user
+    2. Call one or more tools to gather information
+
+    Args:
+        state: Current agent state containing messages and metadata
+
+    Returns:
+        State update dict with the new AI message appended to messages
+
+    Note:
+        The return value is a partial state update. Since messages uses
+        operator.add as its reducer, the new message will be appended
+        to the existing list, not replace it.
+    """
+    model = get_model()
+
+    # Prepend system message to guide the model's behavior
+    messages_with_system = [SystemMessage(content=SYSTEM_PROMPT)] + state["messages"]
+
+    # Invoke the model and get response
+    response = model.invoke(messages_with_system)
+
+    # Return state update - the reducer will append this to existing messages
+    return {"messages": [response]}
+
+
+def execute_tools(state: AgentState) -> dict:
+    """
+    Node that executes tool calls from the LLM's response.
+
+    When the LLM decides to call tools, this node:
+    1. Extracts tool calls from the last AI message
+    2. Executes each tool with the provided arguments
+    3. Returns ToolMessage results for each call
+
+    Args:
+        state: Current agent state (last message should have tool_calls)
+
+    Returns:
+        State update dict with ToolMessages for each tool call result,
+        and incremented tool_call_count
+
+    Note:
+        ToolMessage includes tool_call_id to match results with calls.
+        This is important for the LLM to understand which result
+        corresponds to which tool call.
+    """
+    # Get the last message which contains the tool calls
+    last_message: AIMessage = state["messages"][-1]
+
+    # Execute each tool call and collect results
+    tool_results = []
+    for tool_call in last_message.tool_calls:
+        # Look up the tool by name
+        tool = tools_by_name[tool_call["name"]]
+
+        # Execute the tool with provided arguments
+        result = tool.invoke(tool_call["args"])
+
+        # Create a ToolMessage with the result
+        # tool_call_id links this result back to the specific call
+        tool_results.append(
+            ToolMessage(
+                content=str(result),
+                tool_call_id=tool_call["id"],
+            )
+        )
+
+    # Return state update with tool results and incremented count
+    current_count = state.get("tool_call_count", 0)
+    return {
+        "messages": tool_results,
+        "tool_call_count": current_count + len(tool_results),
+    }
+
+
+def should_continue(state: AgentState) -> Literal["execute_tools", "__end__"]:
+    """
+    Conditional edge function to determine next step.
+
+    This function examines the last message to decide whether to:
+    - Execute tools (if the LLM made tool calls)
+    - End the conversation (if the LLM gave a final response)
+
+    Args:
+        state: Current agent state
+
+    Returns:
+        "execute_tools" if there are tool calls to process,
+        END if the conversation should terminate
+
+    Note:
+        This is a routing function used by add_conditional_edges().
+        It doesn't modify state, just returns the next node name.
+    """
+    last_message = state["messages"][-1]
+
+    # Check if the model made any tool calls
+    if hasattr(last_message, "tool_calls") and last_message.tool_calls:
+        return "execute_tools"
+
+    # No tool calls means the model is done - end the conversation
+    return END
+
+
+def create_agent() -> StateGraph:
+    """
+    Build and compile the agent graph.
+
+    This function constructs the StateGraph by:
+    1. Creating a new StateGraph with our state schema
+    2. Adding nodes for each processing step
+    3. Connecting nodes with edges (both direct and conditional)
+    4. Compiling the graph for execution
+
+    Returns:
+        A compiled StateGraph ready for invocation
+
+    Graph structure:
+        START → call_model → [should_continue] → execute_tools → call_model
+                          ↘                                   ↗
+                            → END (if no tool calls)
+    """
+    # Step 1: Create the graph builder with our state schema
+    builder = StateGraph(AgentState)
+
+    # Step 2: Add nodes
+    # Each node is a function that takes state and returns state updates
+    builder.add_node("call_model", call_model)
+    builder.add_node("execute_tools", execute_tools)
+
+    # Step 3: Add edges
+    # START → call_model: Entry point
+    builder.add_edge(START, "call_model")
+
+    # call_model → [conditional]: Check if we need to execute tools
+    builder.add_conditional_edges(
+        "call_model",
+        should_continue,
+        # Map of return values to destination nodes
+        # The function returns either "execute_tools" or END
+        ["execute_tools", END],
+    )
+
+    # execute_tools → call_model: After executing tools, go back to the model
+    builder.add_edge("execute_tools", "call_model")
+
+    # Step 4: Compile the graph
+    # IMPORTANT: Must compile before the graph can be invoked
+    return builder.compile()
+
+
+def run_agent(user_message: str) -> str:
+    """
+    Convenience function to run the agent with a single message.
+
+    Args:
+        user_message: The user's input message
+
+    Returns:
+        The agent's final response as a string
+
+    Example:
+        >>> result = run_agent("What is 25 * 4?")
+        >>> print(result)
+        "25 * 4 = 100"
+    """
+    agent = create_agent()
+
+    # Create initial state with the user's message
+    initial_state = {
+        "messages": [HumanMessage(content=user_message)],
+        "tool_call_count": 0,
+    }
+
+    # Run the agent to completion
+    final_state = agent.invoke(initial_state)
+
+    # Return the last message content (the agent's response)
+    return final_state["messages"][-1].content