@koi-language/koi 1.0.0

package/examples/sentiment.koi

@@ -0,0 +1,90 @@
+// ============================================================
+// Koi — Sentiment Analysis Skill Demo
+// Skill with agents using playbooks ONLY (LLM execution)
+// ============================================================
+
+package "demo.koi.sentiment"
+
+role Worker   { can execute, can propose }
+role Reviewer { can critique, can approve }
+
+Skill SentimentAnalysis {
+  affordance """
+  Analyzes text sentiment and returns positive/neutral/negative classification.
+  Uses 2 agents: Analyst (drafts analysis) + Reviewer (validates and normalizes).
+  Both agents use playbooks executed by LLM.
+  """
+
+  // Agent with ONLY playbook (LLM executes this)
+  Agent Analyst : Worker {
+    llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 300 }
+
+    on analyze(args: Json) {
+      playbook """
+You are a sentiment analysis expert. Analyze the sentiment of the text provided in args.text.
+
+Your task:
+1. Determine if the sentiment is positive, neutral, or negative
+2. Assign a confidence score between 0 and 1
+3. Provide a brief rationale (max 100 characters)
+
+Return ONLY this exact JSON structure (no markdown, no explanations):
+{
+  "label": "positive|neutral|negative",
+  "score": 0.85,
+  "rationale": "Brief explanation here"
+}
+
+Rules:
+- Base your analysis ONLY on the provided text
+- If ambiguous, use "neutral" with score ~0.5
+- Keep rationale under 100 characters
+      """
+    }
+  }
+
+  // Agent with ONLY playbook (LLM executes this)
+  Agent Reviewer : Reviewer {
+    llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.0, max_tokens: 200 }
+
+    on normalize(args: Json) {
+      playbook """
+You are a quality reviewer. Validate and normalize the sentiment analysis draft in args.draft.
+
+Your task:
+1. Ensure label is exactly "positive", "neutral", or "negative"
+2. Ensure score is a number between 0 and 1
+3. Ensure rationale is under 100 characters
+4. Fix any issues while preserving the original intent
+
+Return ONLY this exact JSON structure (no markdown, no explanations):
+{
+  "label": "positive|neutral|negative",
+  "score": 0.85,
+  "rationale": "Brief explanation here"
+}
+
+If the draft is missing fields, fill them conservatively (neutral, score 0.5).
+      """
+    }
+  }
+
+  Team Internal {
+    analyst  = Analyst
+    reviewer = Reviewer
+  }
+
+  export async function run(input: any): Promise<any> {
+    const text = "I absolutely love this product! It works perfectly and exceeded all my expectations."
+
+    const draft =
+      await send Internal.event("analyze").role(Worker).any()({ text: text }) timeout 15s
+
+    const final =
+      await send Internal.event("normalize").role(Reviewer).any()({ draft: draft }) timeout 10s
+
+    return final
+  }
+}
+
+run SentimentAnalysis.run({})

package/examples/simple.koi

@@ -0,0 +1,48 @@
+// ============================================================
+// Koi — Simple Example
+// Minimal example showing agent communication with procedural code
+// ============================================================
+
+package "demo.koi.simple"
+
+role Worker { can execute }
+role Lead   { can delegate }
+
+// Agent with procedural code only (no playbook)
+Agent Greeter : Worker {
+  on greet(args: Json) {
+    const name = args.name
+    return { message: "Hello, " + name + "!" }
+  }
+}
+
+// Agent with procedural code only (no playbook)
+Agent Processor : Worker {
+  on process(args: Json) {
+    const msg = args.message
+    const upper = "PROCESSED: " + msg
+    return { result: upper }
+  }
+}
+
+Team SimpleTeam {
+  greeter = Greeter
+  processor = Processor
+}
+
+// Orchestrator with procedural code
+Agent Orchestrator : Lead {
+  uses Team SimpleTeam
+
+  on start(args: Json) {
+    const greeting =
+      await send peers.event("greet").role(Worker).any()({ name: "Koi" }) timeout 5s
+
+    const processed =
+      await send peers.event("process").role(Worker).any()({ message: greeting.message }) timeout 5s
+
+    return processed
+  }
+}
+
+run Orchestrator.start({})

package/examples/skill-import-test.koi

@@ -0,0 +1,76 @@
+// ============================================================
+// Skill Import Test
+// Tests importing Skills from external files
+// ============================================================
+
+package "demo.koi.import"
+
+// Import the Math Operations skill
+import "./skills/math-operations.koi"
+
+role Calculator { can calculate }
+
+// Agent that uses the imported MathOperations skill
+Agent MathAgent : Calculator {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+  uses Skill MathOperations
+
+  on calculate(args: Json) {
+    playbook """
+    Perform the following calculation: ${JSON.stringify(args)}
+
+    Use the available math tools to compute the result.
+    Return the result as JSON with the operation and result fields.
+    """
+  }
+}
+
+// Create a team
+Team MathTeam {
+  calculator = MathAgent
+}
+
+// Demo runner
+Agent DemoRunner : Calculator {
+  uses Team MathTeam
+
+  on runTest(args: Json) {
+    console.log("╔════════════════════════════════════════════╗")
+    console.log("║  Skill Import Test                         ║")
+    console.log("║  Testing imported Math Operations          ║")
+    console.log("╚════════════════════════════════════════════╝\n")
+
+    // Test 1: Addition
+    console.log("📋 Test 1: Addition (5 + 3)")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const result1 =
+      await send peers.event("calculate").role(Calculator).any()({
+        operation: "add",
+        a: 5,
+        b: 3
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(result1, null, 2))
+
+    // Test 2: Multiplication
+    console.log("\n📋 Test 2: Multiplication (7 × 6)")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const result2 =
+      await send peers.event("calculate").role(Calculator).any()({
+        operation: "multiply",
+        a: 7,
+        b: 6
+      }) timeout 10s
+
+    console.log("Result:", JSON.stringify(result2, null, 2))
+
+    return {
+      success: true,
+      tests_completed: 2
+    }
+  }
+}
+
+run DemoRunner.runTest({})

package/examples/skills/advanced/index.koi

@@ -0,0 +1,95 @@
+// ============================================================
+// Advanced Skills Package
+// Entry point that exports all skills from this directory
+// ============================================================
+
+package "skills.advanced"
+
+// Re-export from other files in this directory
+// (In a future version, we could support automatic re-export)
+
+// For now, we define everything here as the main entry point
+
+role DataScientist { can analyze }
+
+// ============================================================
+// Statistical Analysis Skill
+// ============================================================
+
+Skill StatisticalAnalysis {
+  affordance """
+  Perform statistical analysis including mean, median, standard deviation
+  """
+
+  export async function calculateMean(args: any): Promise<any> {
+    const numbers = args.numbers || [];
+    if (numbers.length === 0) {
+      return { error: "No numbers provided" };
+    }
+
+    const sum = numbers.reduce((a, b) => a + b, 0);
+    const mean = sum / numbers.length;
+
+    return {
+      operation: "mean",
+      numbers: numbers,
+      result: mean
+    };
+  }
+
+  export async function calculateMedian(args: any): Promise<any> {
+    const numbers = args.numbers || [];
+    if (numbers.length === 0) {
+      return { error: "No numbers provided" };
+    }
+
+    const sorted = [...numbers].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 === 0
+      ? (sorted[mid - 1] + sorted[mid]) / 2
+      : sorted[mid];
+
+    return {
+      operation: "median",
+      numbers: numbers,
+      result: median
+    };
+  }
+
+  export async function calculateStdDev(args: any): Promise<any> {
+    const numbers = args.numbers || [];
+    if (numbers.length === 0) {
+      return { error: "No numbers provided" };
+    }
+
+    const mean = numbers.reduce((a, b) => a + b, 0) / numbers.length;
+    const variance = numbers.reduce((sum, num) => sum + Math.pow(num - mean, 2), 0) / numbers.length;
+    const stdDev = Math.sqrt(variance);
+
+    return {
+      operation: "stddev",
+      numbers: numbers,
+      mean: mean,
+      variance: variance,
+      result: stdDev
+    };
+  }
+}
+
+// ============================================================
+// Data Analysis Agent
+// ============================================================
+
+Agent DataAnalyzer : DataScientist {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 400 }
+  uses Skill StatisticalAnalysis
+
+  on analyze(args: Json) {
+    playbook """
+    Analyze this data: ${JSON.stringify(args)}
+
+    Use the available statistical tools to compute mean, median, and standard deviation.
+    Return a comprehensive analysis as JSON.
+    """
+  }
+}

package/examples/skills/math-operations.koi

@@ -0,0 +1,69 @@
+// ============================================================
+// Math Operations Skill
+// A reusable skill that provides math operations
+// ============================================================
+
+package "skills.math"
+
+Skill MathOperations {
+  affordance """
+  Perform mathematical operations like addition, subtraction, multiplication, and division
+  """
+
+  export async function add(args: any): Promise<any> {
+    const a = args.a || 0;
+    const b = args.b || 0;
+    console.log(`[add] ${a} + ${b} = ${a + b}`);
+    return {
+      operation: "addition",
+      a: a,
+      b: b,
+      result: a + b
+    };
+  }
+
+  export async function subtract(args: any): Promise<any> {
+    const a = args.a || 0;
+    const b = args.b || 0;
+    console.log(`[subtract] ${a} - ${b} = ${a - b}`);
+    return {
+      operation: "subtraction",
+      a: a,
+      b: b,
+      result: a - b
+    };
+  }
+
+  export async function multiply(args: any): Promise<any> {
+    const a = args.a || 0;
+    const b = args.b || 0;
+    console.log(`[multiply] ${a} × ${b} = ${a * b}`);
+    return {
+      operation: "multiplication",
+      a: a,
+      b: b,
+      result: a * b
+    };
+  }
+
+  export async function divide(args: any): Promise<any> {
+    const a = args.a || 0;
+    const b = args.b || 1;
+    if (b === 0) {
+      console.error(`[divide] Error: Division by zero`);
+      return {
+        operation: "division",
+        a: a,
+        b: b,
+        error: "Division by zero"
+      };
+    }
+    console.log(`[divide] ${a} ÷ ${b} = ${a / b}`);
+    return {
+      operation: "division",
+      a: a,
+      b: b,
+      result: a / b
+    };
+  }
+}

package/examples/skills/string-operations.koi

@@ -0,0 +1,56 @@
+// ============================================================
+// String Operations Skill
+// A reusable skill for string manipulation
+// ============================================================
+
+package "skills.string"
+
+Skill StringOperations {
+  affordance """
+  Perform string operations like uppercase, lowercase, reverse, and length
+  """
+
+  export async function toUpperCase(args: any): Promise<any> {
+    const text = args.text || "";
+    const result = text.toUpperCase();
+    console.log(`[toUpperCase] "${text}" → "${result}"`);
+    return {
+      operation: "toUpperCase",
+      original: text,
+      result: result
+    };
+  }
+
+  export async function toLowerCase(args: any): Promise<any> {
+    const text = args.text || "";
+    const result = text.toLowerCase();
+    console.log(`[toLowerCase] "${text}" → "${result}"`);
+    return {
+      operation: "toLowerCase",
+      original: text,
+      result: result
+    };
+  }
+
+  export async function reverse(args: any): Promise<any> {
+    const text = args.text || "";
+    const result = text.split('').reverse().join('');
+    console.log(`[reverse] "${text}" → "${result}"`);
+    return {
+      operation: "reverse",
+      original: text,
+      result: result
+    };
+  }
+
+  export async function getLength(args: any): Promise<any> {
+    const text = args.text || "";
+    const length = text.length;
+    console.log(`[getLength] "${text}" has ${length} characters`);
+    return {
+      operation: "length",
+      text: text,
+      length: length
+    };
+  }
+}

package/examples/task-chaining-demo.koi

@@ -0,0 +1,244 @@
+// ============================================================
+// Task Chaining Demo
+// Demonstrates automatic output→input chaining between tasks
+// ============================================================
+
+package "demo.koi.chaining"
+
+role Worker { can execute }
+role Assistant { can help }
+
+// ============================================================
+// Specialized Worker Agents
+// ============================================================
+
+Agent FrenchTranslator : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.2, max_tokens: 200 }
+
+  on translate(args: Json) {
+    playbook """
+    You are a specialized worker agent. Do NOT return actions, only direct results.
+
+    Translate the following text to French: ${JSON.stringify(args.text)}
+
+    Return ONLY valid JSON (NO actions field):
+    {
+      "translated": "text in French",
+      "original": "original text",
+      "language": "french"
+    }
+    """
+  }
+}
+
+Agent WordCounter : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+
+  on count(args: Json) {
+    playbook """
+    You are a specialized worker agent. Do NOT return actions, only direct results.
+
+    Count the number of words in this text: ${JSON.stringify(args.text)}
+
+    Return ONLY valid JSON (NO actions field):
+    {
+      "wordCount": <number>,
+      "text": "the text that was counted"
+    }
+    """
+  }
+}
+
+Agent TextFormatter : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+
+  on format(args: Json) {
+    playbook """
+    You are a specialized worker agent. Do NOT return actions, only direct results.
+
+    Convert this text to uppercase: ${JSON.stringify(args.text)}
+
+    Return ONLY valid JSON (NO actions field):
+    {
+      "formatted": "TEXT IN UPPERCASE",
+      "original": "original text"
+    }
+    """
+  }
+}
+
+Agent CharacterCounter : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+
+  on countChars(args: Json) {
+    playbook """
+    You are a specialized worker agent. Do NOT return actions, only direct results.
+
+    Count the number of characters in this text: ${JSON.stringify(args.text)}
+
+    Return ONLY valid JSON (NO actions field):
+    {
+      "charCount": <number>,
+      "text": "the text that was counted"
+    }
+    """
+  }
+}
+
+Agent DataValidator : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+
+  on validate(args: Json) {
+    playbook """
+    You are a specialized worker agent. Do NOT return actions, only direct results.
+
+    Validate this email: ${JSON.stringify(args.email)}
+
+    Check if it's a valid email format.
+
+    Return ONLY valid JSON (NO actions field):
+    {
+      "valid": true/false,
+      "email": "the email",
+      "message": "validation message"
+    }
+    """
+  }
+}
+
+// ============================================================
+// Regular Assistant - NO special orchestrator knowledge
+// ============================================================
+
+Agent TaskAssistant : Assistant {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 800 }
+
+  on helpUser(args: Json) {
+    playbook """
+    User request: ${args.request}
+
+    Help accomplish this request. If it requires multiple steps:
+    1. Break it down into sequential tasks
+    2. Chain outputs: use previous results as inputs for next tasks
+
+    The system will automatically:
+    - Execute each task
+    - Pass outputs to next task
+    - Route to appropriate team members
+
+    Return your plan or result as JSON.
+    """
+  }
+}
+
+// ============================================================
+// Team
+// ============================================================
+
+Team AssistantTeam {
+  taskAssistant = TaskAssistant
+}
+
+// ============================================================
+// Demo Runner
+// ============================================================
+
+Agent DemoRunner : Assistant {
+  uses Team AssistantTeam
+
+  on runDemo(args: Json) {
+    console.log("╔════════════════════════════════════════════╗")
+    console.log("║  Task Chaining Demo                        ║")
+    console.log("║  Output → Input Automatic Chaining         ║")
+    console.log("╚════════════════════════════════════════════╝\n")
+
+    // ============================================================
+    // Test 1: Translate → Count Words
+    // ============================================================
+    console.log("📋 Test 1: Translate to French → Count Words")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    console.log('Request: "Translate Hello world to French and then count the words"\n')
+
+    const test1 = await send peers.event("helpUser").role(Assistant).any()({
+      request: "Translate 'Hello world' to French and then count the words in the translation"
+    }) timeout 30s
+
+    console.log("✅ Result:")
+    console.log(JSON.stringify(test1, null, 2))
+    console.log("\nExpected flow:")
+    console.log("  1. FrenchTranslator → { translated: 'Bonjour monde' }")
+    console.log("  2. WordCounter(previousResult.translated) → { wordCount: 2 }")
+    console.log("\n")
+
+    // ============================================================
+    // Test 2: Format → Count Characters
+    // ============================================================
+    console.log("📋 Test 2: Format to Uppercase → Count Characters")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    console.log('Request: "Format hello to uppercase and count characters"\n')
+
+    const test2 = await send peers.event("helpUser").role(Assistant).any()({
+      request: "Format the word hello to uppercase and then count the characters"
+    }) timeout 30s
+
+    console.log("✅ Result:")
+    console.log(JSON.stringify(test2, null, 2))
+    console.log("\nExpected flow:")
+    console.log("  1. TextFormatter → { formatted: 'HELLO' }")
+    console.log("  2. CharacterCounter(previousResult.formatted) → { charCount: 5 }")
+    console.log("\n")
+
+    // ============================================================
+    // Test 3: Chain of 3 Tasks
+    // ============================================================
+    console.log("📋 Test 3: Three-Step Chain")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    console.log('Request: "Validate email, format it, count words"\n')
+
+    const test3 = await send peers.event("helpUser").role(Assistant).any()({
+      request: "Validate the email user@test.com, then format it to uppercase, then count how many words it has"
+    }) timeout 30s
+
+    console.log("✅ Result:")
+    console.log(JSON.stringify(test3, null, 2))
+    console.log("\nExpected flow:")
+    console.log("  1. DataValidator → { valid: true, email: 'user@test.com' }")
+    console.log("  2. TextFormatter(previousResult.email) → { formatted: 'USER@TEST.COM' }")
+    console.log("  3. WordCounter(previousResult.formatted) → { wordCount: 1 }")
+    console.log("\n")
+
+    // ============================================================
+    // Test 4: Complex Original Request
+    // ============================================================
+    console.log("📋 Test 4: Your Original Example")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    console.log('Request: "Traduce al frances y luego cuenta el numero de palabras"\n')
+
+    const test4 = await send peers.event("helpUser").role(Assistant).any()({
+      request: "Traduce 'artificial intelligence' al frances y luego cuenta el numero de palabras"
+    }) timeout 30s
+
+    console.log("✅ Result:")
+    console.log(JSON.stringify(test4, null, 2))
+    console.log("\nExpected flow:")
+    console.log("  1. FrenchTranslator → { translated: 'intelligence artificielle' }")
+    console.log("  2. WordCounter(previousResult.translated) → { wordCount: 2 }")
+    console.log("\n")
+
+    console.log("✅ All chaining tests completed!")
+    console.log("")
+    console.log("🔑 Key Points:")
+    console.log("  - LLM creates plan with chained actions")
+    console.log("  - Each action references previous results: $-{previousResult.field}")
+    console.log("  - Runtime resolves references before executing")
+    console.log("  - Output of action N becomes input of action N+1")
+    console.log("  - NO manual wiring needed!")
+
+    return {
+      success: true,
+      tests_completed: 4
+    }
+  }
+}
+
+run DemoRunner.runDemo({})