@koi-language/koi 1.0.0

package/examples/directory-import-test.koi

@@ -0,0 +1,84 @@
+// ============================================================
+// Directory Import Test
+// Tests importing from directories (looks for index.koi)
+// ============================================================
+
+package "demo.koi.directory"
+
+// Import from directory - automatically finds index.koi
+import "./skills/advanced"
+
+role Worker { can work }
+
+// Agent that uses skills from the directory import
+Agent StatisticsProcessor : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 300 }
+  uses Skill StatisticalAnalysis
+
+  on process(args: Json) {
+    playbook """
+    Process statistical analysis for: ${JSON.stringify(args)}
+
+    Pass the "numbers" array to the tool and return the result.
+    """
+  }
+}
+
+Team WorkerTeam {
+  processor = StatisticsProcessor
+  analyzer = DataAnalyzer  // Agent from the imported directory
+}
+
+// Demo runner
+Agent DemoRunner : Worker {
+  uses Team WorkerTeam
+
+  on runTest(args: Json) {
+    console.log("╔════════════════════════════════════════════╗")
+    console.log("║  Directory Import Test                     ║")
+    console.log("║  import \"./skills/advanced\"                ║")
+    console.log("╚════════════════════════════════════════════╝\n")
+
+    // Test 1: Calculate mean using skill directly
+    console.log("📋 Test 1: Calculate mean of [10, 20, 30, 40, 50]")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const meanResult =
+      await send peers.event("process").role(Worker).any()({
+        operation: "mean",
+        numbers: [10, 20, 30, 40, 50]
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(meanResult, null, 2))
+
+    // Test 2: Calculate median
+    console.log("\n📋 Test 2: Calculate median of [1, 3, 5, 7, 9, 11]")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const medianResult =
+      await send peers.event("process").role(Worker).any()({
+        operation: "median",
+        numbers: [1, 3, 5, 7, 9, 11]
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(medianResult, null, 2))
+
+    // Test 3: Use the imported DataAnalyzer agent
+    console.log("\n📋 Test 3: Full analysis using DataAnalyzer agent!!!!")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const analysisResult =
+      await send peers.event("analyze").role(DataScientist).any()({
+        numbers: [15, 25, 35, 45, 55, 65, 75]
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(analysisResult, null, 2))
+
+    return {
+      success: true,
+      tests_completed: 3
+    }
+  }
+}
+
+run DemoRunner.runTest({})

package/examples/hello-world-claude.koi

@@ -0,0 +1,52 @@
+// ============================================================
+// Koi — Hello World with Claude
+// Using Anthropic's Claude instead of OpenAI
+// ============================================================
+
+package "demo.koi.helloworld.claude"
+
+role Worker { can execute }
+
+// Agent with playbook using Claude
+Agent Greeter : Worker {
+  llm default = { provider: "anthropic", model: "claude-3-5-haiku-20241022", temperature: 0.7, max_tokens: 200 }
+
+  on greet(args: Json) {
+    playbook """
+    You are a friendly greeter. Generate a warm, creative greeting for the person whose name is in args.name.
+
+    Return a JSON object with this exact structure:
+    {
+      "greeting": "Your creative greeting here",
+      "language": "english",
+      "style": "friendly"
+    }
+
+    Make the greeting unique and warm, but keep it under 50 words.
+    """
+  }
+}
+
+Team HelloTeam {
+  greeter = Greeter
+}
+
+// Orchestrator with procedural code
+Agent Orchestrator : Worker {
+  uses Team HelloTeam
+
+  on start(args: Json) {
+    const name = args.name
+
+    const result =
+      await send peers.event("greet").role(Worker).any()({ name: name }) timeout 30s
+
+    return {
+      success: true,
+      name: name,
+      response: result
+    }
+  }
+}
+
+run Orchestrator.start({ name: "World" })

package/examples/hello-world.koi

@@ -0,0 +1,52 @@
+// ============================================================
+// Koi — Hello World with LLM Playbook
+// Simple example showing playbook execution with real LLM
+// ============================================================
+
+package "demo.koi.helloworld"
+
+role Worker { can execute }
+
+// Agent with playbook only (will execute with LLM)
+Agent Greeter : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.7, max_tokens: 200 }
+
+  on greet(args: Json) {
+    playbook """
+    You are a friendly greeter. Generate a warm, creative greeting for the person whose name is in args.name.
+
+    Return a JSON object with this exact structure:
+    {
+      "greeting": "Your creative greeting here",
+      "language": "english",
+      "style": "friendly"
+    }
+
+    Make the greeting unique and warm, but keep it under 50 words.
+    """
+  }
+}
+
+Team HelloTeam {
+  greeter = Greeter
+}
+
+// Orchestrator with procedural code
+Agent Orchestrator : Worker {
+  uses Team HelloTeam
+
+  on start(args: Json) {
+    const name = args.name
+
+    const result =
+      await send peers.event("greet").role(Worker).any()({ name: name }) timeout 30s
+
+    return {
+      success: true,
+      name: name,
+      response: result
+    }
+  }
+}
+
+run Orchestrator.start({ name: "World" })

package/examples/hello.koi

@@ -0,0 +1,24 @@
+// Minimal test
+package "test"
+
+role Worker { can execute }
+
+Agent Test : Worker {
+on test(args: Json) {
+return { ok: true }
+}
+}
+
+Team T {
+t = Test
+}
+
+Agent Orch : Worker {
+uses Team T
+on start(args: Json) {
+const r = await send peers.event("test").role(Worker).any()({}) timeout 2s
+return r
+}
+}
+
+run Orch.start({})

package/examples/mcp-example.koi

@@ -0,0 +1,70 @@
+// ============================================================
+// Koi — MCP (Model Context Protocol) Example
+// Demonstrates using MCP addresses to reference remote agents
+// ============================================================
+
+package "demo.koi.mcp"
+
+role Worker { can execute }
+role Lead   { can delegate }
+
+// Local agent
+Agent LocalProcessor : Worker {
+  on process(args: Json) {
+    const data = args.data
+    const processed = "LOCAL: " + data
+    return { result: processed, source: "local" }
+  }
+}
+
+// Team with both local and remote (MCP) agents
+Team HybridTeam {
+  // Regular local agent
+  local = LocalProcessor
+
+  // Remote agents via MCP addresses
+  // Format: mcp://server/path
+  remote1 = mcp://agent.local/processor
+  remote2 = mcp://service.local/analyzer
+}
+
+// Orchestrator that uses both local and remote agents
+Agent Orchestrator : Lead {
+  uses Team HybridTeam
+
+  on start(args: Json) {
+    const data = args.data
+
+    // This will try local first, then MCP agents
+    const result =
+      await send peers.event("process").role(Worker).any()({ data: data }) timeout 10s
+
+    return {
+      success: true,
+      result: result
+    }
+  }
+
+  on processAll(args: Json) {
+    const data = args.data
+
+    // Process with ALL agents (local + MCP)
+    const results =
+      await send peers.event("process").role(Worker).all()({ data: data }) timeout 15s
+
+    return {
+      success: true,
+      count: 3,
+      results: results
+    }
+  }
+}
+
+// Example with MCP skill reference
+Team DistributedTeam {
+  orchestrator = Orchestrator
+  // Reference a remote skill
+  sentiment = mcp://skills.local/sentiment-analysis
+}
+
+run Orchestrator.start({ data: "Hello from Koi with MCP support!" })

package/examples/multi-event-handler-test.koi

@@ -0,0 +1,144 @@
+package "demo.multi.event"
+
+role Calculator { can calculate }
+role Coordinator { can coordinate }
+
+// Agent con múltiples event handlers
+// Cada handler tiene su propio affordance (del playbook)
+Agent StatisticsCalculator : Calculator {
+  llm default = {
+    provider: "openai",
+    model: "gpt-4o-mini",
+    temperature: 0.1
+  }
+
+  // Event handler para calcular media
+  on mean(args: Json) {
+    playbook """
+    Calculate the arithmetic mean (average) of the numbers: ${JSON.stringify(args.numbers)}
+
+    Sum all numbers and divide by the count.
+    IMPORTANT: Actually perform the calculation and return ONLY: { "operation": "mean", "result": <numeric_value> }
+    """
+  }
+
+  // Event handler para calcular mediana
+  on median(args: Json) {
+    playbook """
+    Calculate the median (middle value) of ${JSON.stringify(args.numbers)}
+
+    Sort numbers, find middle. If even count, average two middle values.
+    Return: { "operation": "median", "result": <numeric_value> }
+    """
+  }
+
+  // Event handler para calcular desviación estándar
+  on stddev(args: Json) {
+    playbook """
+    Calculate the standard deviation for ${JSON.stringify(args.numbers)}
+
+    DO NOT return a plan. Perform the actual calculation and return only the result.
+    Formula: sqrt(sum((x - mean)²) / n)
+    Return ONLY: { "operation": "stddev", "result": <numeric_result> }
+    """
+  }
+}
+
+Team CalculatorTeam {
+  calculator = StatisticsCalculator
+}
+
+// Orchestrator que decide qué evento enviar basándose en la intención
+Agent Orchestrator : Coordinator {
+  llm default = {
+    provider: "openai",
+    model: "gpt-4o-mini",
+    temperature: 0.1
+  }
+
+  uses Team CalculatorTeam
+
+  on process(args: Json) {
+    playbook """
+    Process this statistical request: ${JSON.stringify(args)}
+
+    You have access to Calculator agents with these event handlers:
+    - "mean" event: Calculate arithmetic mean/average
+    - "median" event: Calculate median (middle value)
+    - "stddev" event: Calculate standard deviation (measure of spread)
+
+    Based on the user's request description in "operation", determine which statistical calculation is needed.
+    Then delegate by returning an action:
+
+    {
+      "actions": [
+        {
+          "title": "Calculating <operation>",
+          "intent": "<choose: calculate mean | calculate median | calculate standard deviation>",
+          "data": { "numbers": ${JSON.stringify(args.numbers)} }
+        }
+      ]
+    }
+
+    The system will route to the appropriate event handler based on the intent.
+    """
+  }
+}
+
+Team OrchestratorTeam {
+  orchestrator = Orchestrator
+}
+
+Agent Main : Coordinator {
+  uses Team OrchestratorTeam
+
+  on start(args: Json) {
+    console.log("╔════════════════════════════════════════════╗")
+    console.log("║  Multi Event Handler Test                  ║")
+    console.log("║  Semantic routing to event handlers        ║")
+    console.log("╚════════════════════════════════════════════╝\n")
+
+    // Test 1: Request mean calculation
+    console.log("📋 Test 1: Calculate average of numbers")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const meanResult =
+      await send peers.event("process").role(Coordinator).any()({
+        operation: "calculate the average",
+        numbers: [10, 20, 30, 40, 50]
+      }) timeout 30s
+
+    console.log("Result:", JSON.stringify(meanResult, null, 2))
+
+    // Test 2: Request median calculation
+    console.log("\n📋 Test 2: Find the middle value")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const medianResult =
+      await send peers.event("process").role(Coordinator).any()({
+        operation: "find the middle value",
+        numbers: [1, 3, 5, 7, 9, 11]
+      }) timeout 30s
+
+    console.log("Result:", JSON.stringify(medianResult, null, 2))
+
+    // Test 3: Request standard deviation
+    console.log("\n📋 Test 3: Calculate spread of data")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const stddevResult =
+      await send peers.event("process").role(Coordinator).any()({
+        operation: "measure how spread out the numbers are",
+        numbers: [10, 20, 30, 40, 50]
+      }) timeout 30s
+
+    console.log("Result:", JSON.stringify(stddevResult, null, 2))
+
+    return {
+      success: true,
+      tests_completed: 3
+    }
+  }
+}
+
+run Main.start({})

package/examples/new-import-test.koi

@@ -0,0 +1,89 @@
+// ============================================================
+// New Import System Test
+// Tests the new simplified import syntax
+// ============================================================
+
+package "demo.koi.new.import"
+
+// New import syntax - imports everything (Skills, Agents, Roles, Teams)
+import "./skills/math-operations.koi"
+import "@koi-lang/common-skills"
+
+role Worker { can work }
+
+// Agent that uses imported skills from both local and npm package
+Agent DataProcessor : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 300 }
+  // Comma-separated syntax (cleaner!)
+  uses Skill MathOperations, DataValidation, DataTransformation
+
+  on process(args: Json) {
+    playbook """
+    Process the request: ${JSON.stringify(args)}
+
+    Use the available tools (math, validation, transformation) to complete the task.
+    Return the result as JSON.
+    """
+  }
+}
+
+Team WorkerTeam {
+  processor = DataProcessor
+  // Also use the imported EmailValidator agent
+  emailValidator = EmailValidator
+}
+
+// Demo runner
+Agent DemoRunner : Worker {
+  uses Team WorkerTeam
+
+  on runTest(args: Json) {
+    console.log("╔════════════════════════════════════════════╗")
+    console.log("║  New Import System Test                    ║")
+    console.log("║  Local files + npm packages                ║")
+    console.log("╚════════════════════════════════════════════╝\n")
+
+    // Test 1: Use local skill (math)
+    console.log("📋 Test 1: Math operation from local skill")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const mathResult =
+      await send peers.event("process").role(Worker).any()({
+        operation: "add",
+        a: 15,
+        b: 27
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(mathResult, null, 2))
+
+    // Test 2: Use npm package skill (validation)
+    console.log("\n📋 Test 2: Email validation from npm package")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const validationResult =
+      await send peers.event("process").role(Worker).any()({
+        operation: "validateEmail",
+        email: "test@example.com"
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(validationResult, null, 2))
+
+    // Test 3: Use imported agent directly
+    console.log("\n📋 Test 3: Using imported EmailValidator agent")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const agentResult =
+      await send peers.event("validate").role(Validator).any()({
+        email: "invalid-email"
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(agentResult, null, 2))
+
+    return {
+      success: true,
+      tests_completed: 3
+    }
+  }
+}
+
+run DemoRunner.runTest({})

package/examples/pipeline.koi

@@ -0,0 +1,162 @@
+// ============================================================
+// Koi — Data Pipeline Example
+// Shows multi-stage data processing
+// ============================================================
+
+package "demo.koi.pipeline"
+
+role Worker   { can execute }
+role Reviewer { can critique }
+role Lead     { can delegate }
+
+Agent Extractor : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 300 }
+
+  on extract(args: Json) {
+    playbook """
+    You are a data extraction specialist. Extract and structure the raw input data from args.raw.
+
+    Your task:
+    1. Parse the raw input text
+    2. Identify key information (content, metadata, timestamp)
+    3. Calculate the text length
+    4. Structure it into a clean data object
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "extracted": true,
+      "data": {
+        "text": "the raw text content",
+        "length": 42,
+        "timestamp": "2026-01-21"
+      }
+    }
+
+    Use the current date for timestamp. Be precise and thorough.
+    """
+  }
+}
+
+Agent Transformer : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 300 }
+
+  on transform(args: Json) {
+    playbook """
+    You are a data transformation specialist. Transform the extracted data from args.data into an enriched format.
+
+    Your task:
+    1. Take the extracted data (text, length, timestamp)
+    2. Apply business rules and enrichments
+    3. Add a "processed_at" field with the timestamp
+    4. Mark the data as enriched
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "transformed": true,
+      "data": {
+        "text": "the original text",
+        "length": 42,
+        "enriched": true,
+        "processed_at": "timestamp from args.data"
+      }
+    }
+
+    Preserve all original data fields while adding enrichment.
+    """
+  }
+}
+
+Agent Validator : Reviewer {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+
+  on validate(args: Json) {
+    playbook """
+    You are a data quality validator. Validate that the transformed data in args.data meets quality requirements.
+
+    Your validation rules:
+    1. Check that "enriched" field is true
+    2. Ensure all required fields are present (text, length, enriched, processed_at)
+    3. Verify data types are correct
+    4. Check that text is not empty and length is positive
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "valid": true,
+      "message": "Data passes validation"
+    }
+
+    OR if validation fails:
+    {
+      "valid": false,
+      "message": "Specific reason for failure"
+    }
+
+    Be strict but fair in validation.
+    """
+  }
+}
+
+Agent Loader : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.2, max_tokens: 250 }
+
+  on load(args: Json) {
+    playbook """
+    You are a data loading specialist. Load the validated data from args.data into the final destination.
+
+    Your task:
+    1. Take the validated data
+    2. Prepare it for storage in the database
+    3. Return metadata about the load operation
+    4. Include the full data in the response
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "loaded": true,
+      "records": 1,
+      "destination": "database",
+      "data": { ...the full data from args.data... }
+    }
+
+    Confirm successful loading with appropriate metadata.
+    """
+  }
+}
+
+Team Pipeline {
+  extractor = Extractor
+  transformer = Transformer
+  validator = Validator
+  loader = Loader
+}
+
+Agent Orchestrator : Lead {
+  uses Team Pipeline
+
+  on start(args: Json) {
+    const raw = args.input
+
+    const extracted =
+      await send peers.event("extract").role(Worker).any()({ raw: raw }) timeout 5s
+
+    const transformed =
+      await send peers.event("transform").role(Worker).any()({ data: extracted.data }) timeout 5s
+
+    const validation =
+      await send peers.event("validate").role(Reviewer).any()({ data: transformed.data }) timeout 5s
+
+    if validation.valid == false {
+      return { ok: false, error: validation.message }
+    }
+
+    const loaded =
+      await send peers.event("load").role(Worker).any()({ data: transformed.data }) timeout 5s
+
+    return {
+      ok: true,
+      pipeline: "complete",
+      result: loaded
+    }
+  }
+}
+
+run Orchestrator.start({ input: "Sample data to process through pipeline" })