@aurite-ai/kai 0.2.0-dev.0

package/dist/templates/index.js

@@ -0,0 +1,270 @@
+/**
+ * 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.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// =============================================================================
+// Template Directory Resolution
+// =============================================================================
+// Cache the templates directory path
+let _templatesDir = null;
+/**
+ * Get the absolute path to the templates directory.
+ *
+ * Works for both:
+ * - Development: templates/ relative to src/templates/
+ * - Bundled CJS: templates/ relative to the bundle location
+ * - npm installed: templates/ in package directory
+ * - Docker: via KAI_TEMPLATES_DIR environment variable
+ */
+function getTemplatesDir() {
+    // Return cached value if available
+    if (_templatesDir) {
+        return _templatesDir;
+    }
+    // 1. Check KAI_TEMPLATES_DIR env var first (Docker, explicit config)
+    const envPath = process.env.KAI_TEMPLATES_DIR;
+    if (envPath) {
+        _templatesDir = envPath;
+        return _templatesDir;
+    }
+    // 2. Try to detect from module location
+    // In CJS bundles, import.meta.url is empty/undefined
+    // In ESM development, we use import.meta.url
+    // Check if we're in a CJS bundle (import.meta.url will be undefined or empty)
+    // biome-ignore lint/suspicious/noExplicitAny: CJS/ESM compatibility check
+    const metaUrl = import.meta?.url;
+    if (metaUrl) {
+        // ESM mode (development or tsc compiled)
+        const __filename = fileURLToPath(metaUrl);
+        const __dirname = path.dirname(__filename);
+        // Development: templates/ is at apps/mcp/templates/ (up from src/templates/)
+        if (__dirname.includes('src')) {
+            _templatesDir = path.resolve(__dirname, '..', '..', 'templates');
+            return _templatesDir;
+        }
+        // TSC compiled: dist/templates/index.js -> templates are in dist/templates/
+        // __dirname = dist/templates, templates are at dist/templates/copilot-configs/, etc.
+        if (__dirname.includes('dist')) {
+            _templatesDir = __dirname;
+            return _templatesDir;
+        }
+        // ESM bundled fallback
+        _templatesDir = path.resolve(__dirname, 'templates');
+        return _templatesDir;
+    }
+    // CJS mode (bundled)
+    // In bundled CJS with esbuild, we need to find templates/ relative to the bundle
+    // The bundle is at dist/kai-mcp.cjs, templates are at dist/templates/
+    // Try __dirname first (available in CJS context, more reliable than process.argv)
+    // In bundled CJS, __dirname points to the directory containing the bundle
+    // biome-ignore lint/suspicious/noExplicitAny: CJS global check
+    const cjsDirname = typeof __dirname !== 'undefined' ? __dirname : undefined;
+    if (cjsDirname) {
+        _templatesDir = path.resolve(cjsDirname, 'templates');
+        return _templatesDir;
+    }
+    // Fallback: Use process.argv[1] which is the path to the script being executed
+    // This works for `node dist/kai-mcp.cjs` and npx scenarios
+    // but may fail when loaded as a library or in some test runners
+    const scriptPath = process.argv[1];
+    if (scriptPath) {
+        const scriptDir = path.dirname(scriptPath);
+        _templatesDir = path.resolve(scriptDir, 'templates');
+        return _templatesDir;
+    }
+    // Last resort: use cwd
+    _templatesDir = path.resolve(process.cwd(), 'templates');
+    return _templatesDir;
+}
+// =============================================================================
+// Template Metadata
+// =============================================================================
+/**
+ * Available framework templates.
+ */
+export const FRAMEWORK_TEMPLATES = [
+    {
+        id: 'langgraph',
+        name: 'LangGraph',
+        description: 'Python agent framework using LangGraph for stateful workflows',
+        path: 'frameworks/langgraph',
+    },
+    {
+        id: 'openai',
+        name: 'OpenAI Agent SDK',
+        description: 'Python agent framework using OpenAI Agents SDK for tool calling and multi-agent handoffs',
+        path: 'frameworks/openai',
+    },
+];
+/**
+ * Available copilot configuration templates.
+ */
+export const COPILOT_CONFIG_TEMPLATES = [
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        description: 'Configuration for Claude Code (formerly Cline)',
+        path: 'copilot-configs/claude-code',
+    },
+];
+/**
+ * Get a framework template by ID.
+ */
+export function getFrameworkTemplate(id) {
+    return FRAMEWORK_TEMPLATES.find((t) => t.id === id);
+}
+/**
+ * Get a copilot config template by ID.
+ */
+export function getCopilotConfigTemplate(id) {
+    return COPILOT_CONFIG_TEMPLATES.find((t) => t.id === id);
+}
+/**
+ * List all available frameworks.
+ */
+export function listFrameworks() {
+    return [...FRAMEWORK_TEMPLATES];
+}
+/**
+ * List all available copilot configs.
+ */
+export function listCopilotConfigs() {
+    return [...COPILOT_CONFIG_TEMPLATES];
+}
+// =============================================================================
+// File Reading Utilities
+// =============================================================================
+/**
+ * Recursively read all files from a directory.
+ * Returns TemplateFile[] with relative paths.
+ */
+async function readDirectoryRecursive(dirPath, basePath = '') {
+    const files = [];
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            const relativePath = basePath ? path.join(basePath, entry.name) : entry.name;
+            if (entry.isDirectory()) {
+                // Recursively read subdirectory
+                const subFiles = await readDirectoryRecursive(fullPath, relativePath);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile()) {
+                // Read file content
+                const content = await fs.readFile(fullPath, 'utf-8');
+                files.push({
+                    path: relativePath,
+                    content,
+                });
+            }
+        }
+    }
+    catch (error) {
+        // Log template read failures for debugging
+        // ENOENT (directory doesn't exist) is expected in some scenarios, log as debug
+        const isNotFound = error.code === 'ENOENT';
+        if (isNotFound) {
+            console.warn(`[kai] Template directory not found: ${dirPath}`);
+        }
+        else {
+            console.error(`[kai] Failed to read template directory: ${dirPath}`, error);
+        }
+        // Return empty array - caller should handle gracefully
+    }
+    return files;
+}
+/**
+ * Read a single template file.
+ */
+async function readTemplateFile(relativePath) {
+    const templatesDir = getTemplatesDir();
+    const fullPath = path.join(templatesDir, relativePath);
+    try {
+        return await fs.readFile(fullPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// Public API: Get Template Files
+// =============================================================================
+/**
+ * Get project-level template files (.env template, .gitignore).
+ */
+export async function getProjectFiles() {
+    const files = [];
+    const envContent = await readTemplateFile('project-env');
+    if (envContent) {
+        files.push({ path: '.env', content: envContent });
+    }
+    const gitignoreContent = await readTemplateFile('project-gitignore');
+    if (gitignoreContent) {
+        files.push({ path: '.gitignore', content: gitignoreContent });
+    }
+    return files;
+}
+/**
+ * Get LangGraph framework files.
+ */
+export async function getLangGraphFiles() {
+    const templatesDir = getTemplatesDir();
+    const frameworkDir = path.join(templatesDir, 'frameworks', 'langgraph');
+    return readDirectoryRecursive(frameworkDir);
+}
+/**
+ * Get OpenAI framework files.
+ */
+export async function getOpenAIFiles() {
+    const templatesDir = getTemplatesDir();
+    const frameworkDir = path.join(templatesDir, 'frameworks', 'openai');
+    return readDirectoryRecursive(frameworkDir);
+}
+/**
+ * Get Claude Code configuration files.
+ */
+export async function getClaudeCodeFiles() {
+    const templatesDir = getTemplatesDir();
+    const configDir = path.join(templatesDir, 'copilot-configs', 'claude-code');
+    return readDirectoryRecursive(configDir);
+}
+/**
+ * Get knowledge base seed files.
+ */
+export async function getKnowledgeBaseFiles() {
+    const templatesDir = getTemplatesDir();
+    const kbDir = path.join(templatesDir, 'knowledge-base');
+    return readDirectoryRecursive(kbDir);
+}
+/**
+ * Get template files for a framework.
+ */
+export async function getFrameworkFiles(frameworkId) {
+    switch (frameworkId) {
+        case 'langgraph':
+            return getLangGraphFiles();
+        case 'openai':
+            return getOpenAIFiles();
+        default:
+            throw new Error(`Unknown framework: ${frameworkId}`);
+    }
+}
+/**
+ * Get config files for a copilot.
+ */
+export async function getCopilotConfigFiles(copilotId) {
+    switch (copilotId) {
+        case 'claude-code':
+            return getClaudeCodeFiles();
+        default:
+            throw new Error(`Unknown copilot: ${copilotId}`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/templates/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/knowledge-base/langgraph-best-practices.mdc

@@ -0,0 +1,277 @@
+---
+type: knowledge
+title: LangGraph Best Practices
+summary: >
+  Comprehensive reference for building LangGraph agent workflows including core
+  concepts, graph construction patterns, state management, advanced patterns
+  like Send API and Command, and production-ready code examples.
+created_at: "2026-02-10T00:00:00Z"
+updated_at: "2026-02-10T00:00:00Z"
+
+source:
+  file: langgraph-best-practices.mdc
+  project: null
+  path: null
+
+classification:
+  category: reference
+  confidence: 1.0
+  reasoning: >
+    Seed content providing technical reference documentation for the LangGraph
+    framework. Covers API patterns, state management, and code examples.
+  topics:
+    - LangGraph
+    - Agent Workflows
+    - State Management
+    - Python AI Agents
+    - Structured Output
+
+status: active
+---
+
+# LangGraph Best Practices
+
+## Core Concepts
+
+LangGraph models agent workflows as graphs with three key components:
+
+1. **State**: A shared data structure representing the current snapshot of your application
+   - Use TypedDict or Pydantic BaseModel for schema definition
+   - Define reducers to specify how updates are applied to each state key
+   - Default reducer overwrites values; use Annotated types for custom reducers (e.g., operator.add for lists)
+   - For message-based workflows, use MessagesState or the add_messages reducer
+
+2. **Nodes**: Functions that encode logic and perform computation
+   - Accept state as input, perform work, return state updates
+   - Can be synchronous or asynchronous Python functions
+   - Can accept optional config (RunnableConfig) and runtime (Runtime) parameters
+   - Nodes do the work - they contain LLM calls or regular code
+   - Add nodes with builder.add_node("node_name", node_function)
+
+3. **Edges**: Functions that determine which node executes next
+   - Edges tell what to do next based on current state
+   - Normal edges: Direct transitions with add_edge("node_a", "node_b")
+   - Conditional edges: Dynamic routing with add_conditional_edges("node_a", routing_function)
+   - Use START constant for entry points, END for terminal nodes
+   - Multiple outgoing edges execute destination nodes in parallel
+
+## Graph Construction Pattern
+
+1. Define State schema (TypedDict or Pydantic model)
+2. Create StateGraph: builder = StateGraph(State)
+3. Add nodes: builder.add_node("name", function)
+4. Add edges: builder.add_edge(START, "first_node") and builder.add_edge("node_a", "node_b")
+5. Add conditional edges if needed: builder.add_conditional_edges("node", routing_func)
+6. Compile: graph = builder.compile()
+
+## State Management
+
+- **Multiple Schemas**: Use InputState, OutputState, OverallState, and PrivateState for different node communication patterns
+- **Reducers**: Annotate state keys with reducer functions to control update behavior
+  - Default: Overwrite existing value
+  - operator.add: Append to lists
+  - add_messages: Smart message list management with ID tracking
+- **MessagesState**: Prebuilt state for chat applications with messages key using add_messages reducer
+
+## Advanced Patterns
+
+- **Send API**: For map-reduce patterns, return Send objects from conditional edges to dynamically create parallel branches
+- **Command**: Combine state updates and routing in a single node by returning Command(update={...}, goto="next_node")
+  - Use Command when you need both state updates AND routing decisions
+  - Requires type annotation: Command[Literal["node_name"]]
+  - Command adds dynamic edges but doesn't override static edges
+- **Subgraphs**: Use Command.PARENT to navigate from subgraph nodes to parent graph nodes
+
+## Execution Model
+
+- Graph uses message passing with discrete "super-steps"
+- Nodes in parallel are part of same super-step
+- Sequential nodes belong to separate super-steps
+- Execution terminates when all nodes are inactive and no messages in transit
+
+## Important Requirements
+
+- **MUST compile graph** before use: graph = builder.compile()
+- Use START constant for entry points, END for terminal nodes
+- Import required: from langgraph.graph import StateGraph, START, END
+- For messages: from langgraph.graph.message import add_messages
+- For commands: from langgraph.types import Command, Send
+
+## LLM Usage
+
+When calling llms, such as through ChatAnthropic, always specify structured output and call the models with .with_structured_output. Also specify method="json_schema".
+
+Here is an example code snippet:
+```
+from langchain_anthropic import ChatAnthropic
+from pydantic import BaseModel, Field
+
+model = ChatAnthropic(model="claude-sonnet-4-5-20250929")
+
+class Movie(BaseModel):
+    """A movie with details."""
+    title: str = Field(..., description="The title of the movie")
+    year: int = Field(..., description="The year the movie was released")
+    director: str = Field(..., description="The director of the movie")
+    rating: float = Field(..., description="The movie's rating out of 10")
+
+model_with_structure = model.with_structured_output(Movie, method="json_schema")
+response = model_with_structure.invoke("Provide details about the movie Inception")
+```
+In this code snippet, response will contain an object like Movie(title='Inception', year=2010, director='Christopher Nolan', rating=8.8)
+
+Generate production-ready, well-structured LangGraph workflows following these patterns.
+
+Here is an example workflow for reference:
+
+# Step 1: Define tools and model
+
+from langchain.tools import tool
+from langchain.chat_models import init_chat_model
+
+
+model = init_chat_model(
+    "claude-sonnet-4-5-20250929",
+    temperature=0
+)
+
+
+# Define tools
+@tool
+def multiply(a: int, b: int) -> int:
+    """Multiply a and b.
+
+    Args:
+        a: First int
+        b: Second int
+    """
+    return a * b
+
+
+@tool
+def add(a: int, b: int) -> int:
+    """Adds a and b.
+
+    Args:
+        a: First int
+        b: Second int
+    """
+    return a + b
+
+
+@tool
+def divide(a: int, b: int) -> float:
+    """Divide a and b.
+
+    Args:
+        a: First int
+        b: Second int
+    """
+    return a / b
+
+
+# Augment the LLM with tools
+tools = [add, multiply, divide]
+tools_by_name = {tool.name: tool for tool in tools}
+model_with_tools = model.bind_tools(tools)
+
+# Step 2: Define state
+
+from langchain.messages import AnyMessage
+from typing_extensions import TypedDict, Annotated
+import operator
+
+
+class MessagesState(TypedDict):
+    messages: Annotated[list[AnyMessage], operator.add]
+    llm_calls: int
+
+# Step 3: Define model node
+from langchain.messages import SystemMessage
+
+
+def llm_call(state: dict):
+    """LLM decides whether to call a tool or not"""
+
+    return {
+        "messages": [
+            model_with_tools.invoke(
+                [
+                    SystemMessage(
+                        content="You are a helpful assistant tasked with performing arithmetic on a set of inputs."
+                    )
+                ]
+                + state["messages"]
+            )
+        ],
+        "llm_calls": state.get('llm_calls', 0) + 1
+    }
+
+
+# Step 4: Define tool node
+
+from langchain.messages import ToolMessage
+
+
+def tool_node(state: dict):
+    """Performs the tool call"""
+
+    result = []
+    for tool_call in state["messages"][-1].tool_calls:
+        tool = tools_by_name[tool_call["name"]]
+        observation = tool.invoke(tool_call["args"])
+        result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"]))
+    return {"messages": result}
+
+# Step 5: Define logic to determine whether to end
+
+from typing import Literal
+from langgraph.graph import StateGraph, START, END
+
+
+# Conditional edge function to route to the tool node or end based upon whether the LLM made a tool call
+def should_continue(state: MessagesState) -> Literal["tool_node", END]:
+    """Decide if we should continue the loop or stop based upon whether the LLM made a tool call"""
+
+    messages = state["messages"]
+    last_message = messages[-1]
+
+    # If the LLM makes a tool call, then perform an action
+    if last_message.tool_calls:
+        return "tool_node"
+
+    # Otherwise, we stop (reply to the user)
+    return END
+
+# Step 6: Build agent
+
+# Build workflow
+agent_builder = StateGraph(MessagesState)
+
+# Add nodes
+agent_builder.add_node("llm_call", llm_call)
+agent_builder.add_node("tool_node", tool_node)
+
+# Add edges to connect nodes
+agent_builder.add_edge(START, "llm_call")
+agent_builder.add_conditional_edges(
+    "llm_call",
+    should_continue,
+    ["tool_node", END]
+)
+agent_builder.add_edge("tool_node", "llm_call")
+
+# Compile the agent
+agent = agent_builder.compile()
+
+
+from IPython.display import Image, display
+# Show the agent
+display(Image(agent.get_graph(xray=True).draw_mermaid_png()))
+
+# Invoke
+from langchain.messages import HumanMessage
+messages = [HumanMessage(content="Add 3 and 4.")]
+messages = agent.invoke({"messages": messages})
+for m in messages["messages"]:
+    m.pretty_print()