@koi-language/koi 1.0.6 → 1.1.0

package/examples/sentiment.koi

@@ -1,90 +0,0 @@
-// ============================================================
-// 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

@@ -1,48 +0,0 @@
-// ============================================================
-// 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/task-chaining-demo.koi

@@ -1,244 +0,0 @@
-// ============================================================
-// 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({})

package/examples/test-await.koi

@@ -1,22 +0,0 @@
-package "test"
-
-role Worker { can execute }
-
-Agent A : Worker {
-on test(args: Json) {
-const x = 5
-return { x: x }
-}
-}
-
-Team T {
-a = A
-}
-
-Agent B : Worker {
-uses Team T
-on start(args: Json) {
-const result = await send peers.event("test").role(Worker).any()({}) timeout 2s
-return result
-}
-}

package/examples/test-crypto-sha256.koi

@@ -1,196 +0,0 @@
-package "test.crypto.sha256"
-
-// Import crypto-js from npm for SHA256 hashing
-import "crypto-js"
-
-role SecurityAgent { can hash, can verify }
-
-Agent HashAgent : SecurityAgent {
-  on hashPassword(args: Json) {
-    console.log("=".repeat(60))
-    console.log("Crypto SHA256 Test - Password Hashing")
-    console.log("=".repeat(60))
-
-    const password = args.password
-    console.log("\nOriginal password:", password)
-
-    // Hash with SHA256 (using chained method syntax)
-    const hash = crypto_js.SHA256(password).toString()
-    console.log("SHA256 hash:", hash)
-
-    // Hash with SHA512 for comparison
-    const hash512 = crypto_js.SHA512(password).toString()
-    console.log("SHA512 hash:", hash512)
-
-    // Hash with MD5 (less secure, for demonstration)
-    const hashMD5 = crypto_js.MD5(password).toString()
-    console.log("MD5 hash:", hashMD5)
-
-    return {
-      password: password,
-      sha256: hash,
-      sha512: hash512,
-      md5: hashMD5
-    }
-  }
-
-  on verifyHash(args: Json) {
-    console.log("\n" + "=".repeat(60))
-    console.log("Hash Verification Test")
-    console.log("=".repeat(60))
-
-    const input = args.input
-    const expectedHash = args.expectedHash
-
-    console.log("\nInput:", input)
-    console.log("Expected hash:", expectedHash)
-
-    // Calculate hash (using chained method syntax)
-    const calculatedHash = crypto_js.SHA256(input).toString()
-    console.log("Calculated hash:", calculatedHash)
-
-    // Verify
-    const isValid = calculatedHash == expectedHash
-    console.log("Hash matches:", isValid)
-
-    return {
-      input: input,
-      expectedHash: expectedHash,
-      calculatedHash: calculatedHash,
-      isValid: isValid
-    }
-  }
-
-  on hashData(args: Json) {
-    console.log("\n" + "=".repeat(60))
-    console.log("Data Integrity Test - JSON Hashing")
-    console.log("=".repeat(60))
-
-    const data = args.data
-    console.log("\nOriginal data:", JSON.stringify(data))
-
-    // Convert to JSON string and hash (using chained method syntax)
-    const dataString = JSON.stringify(data)
-    const hash = crypto_js.SHA256(dataString).toString()
-    console.log("SHA256 hash:", hash)
-
-    // Simulate data tampering
-    const tamperedData = { name: data.name, age: 99, email: data.email }
-    const tamperedString = JSON.stringify(tamperedData)
-    const tamperedHash = crypto_js.SHA256(tamperedString).toString()
-    console.log("\nTampered data:", JSON.stringify(tamperedData))
-    console.log("Tampered hash:", tamperedHash)
-    console.log("Hashes match:", hash == tamperedHash)
-
-    return {
-      original: {
-        data: data,
-        hash: hash
-      },
-      tampered: {
-        data: tamperedData,
-        hash: tamperedHash
-      },
-      isCompromised: hash != tamperedHash
-    }
-  }
-
-  on compareAlgorithms(args: Json) {
-    console.log("\n" + "=".repeat(60))
-    console.log("Algorithm Comparison Test")
-    console.log("=".repeat(60))
-
-    const text = args.text
-    console.log("\nText to hash:", text)
-
-    // Hash with different algorithms (using chained method syntax)
-    const md5 = crypto_js.MD5(text).toString()
-    const sha1 = crypto_js.SHA1(text).toString()
-    const sha256 = crypto_js.SHA256(text).toString()
-    const sha512 = crypto_js.SHA512(text).toString()
-    const sha3 = crypto_js.SHA3(text).toString()
-
-    console.log("\nMD5 (32 chars):", md5)
-    console.log("SHA1 (40 chars):", sha1)
-    console.log("SHA256 (64 chars):", sha256)
-    console.log("SHA512 (128 chars):", sha512)
-    console.log("SHA3 (64 chars):", sha3)
-
-    console.log("\nHash lengths:")
-    console.log("  MD5:", md5.length, "characters")
-    console.log("  SHA1:", sha1.length, "characters")
-    console.log("  SHA256:", sha256.length, "characters")
-    console.log("  SHA512:", sha512.length, "characters")
-    console.log("  SHA3:", sha3.length, "characters")
-
-    return {
-      text: text,
-      hashes: {
-        md5: md5,
-        sha1: sha1,
-        sha256: sha256,
-        sha512: sha512,
-        sha3: sha3
-      }
-    }
-  }
-}
-
-Team HashTeam {
-  hasher = HashAgent
-}
-
-Agent Coordinator : SecurityAgent {
-  uses Team HashTeam
-
-  on runTests(args: Json) {
-    console.log("\n" + "█".repeat(60))
-    console.log("█" + " ".repeat(58) + "█")
-    console.log("█" + "  Crypto-JS SHA256 Integration Test Suite".padEnd(58) + "█")
-    console.log("█" + " ".repeat(58) + "█")
-    console.log("█".repeat(60))
-
-    // Test 1: Hash password
-    const result1 = await send peers.event("hashPassword").role(SecurityAgent).any()({
-      password: "MySecurePassword123!"
-    }) timeout 10s
-
-    // Test 2: Verify hash
-    const result2 = await send peers.event("verifyHash").role(SecurityAgent).any()({
-      input: "MySecurePassword123!",
-      expectedHash: result1.sha256
-    }) timeout 10s
-
-    // Test 3: Hash structured data
-    const result3 = await send peers.event("hashData").role(SecurityAgent).any()({
-      data: {
-        name: "Alice",
-        age: 30,
-        email: "alice@example.com"
-      }
-    }) timeout 10s
-
-    // Test 4: Compare algorithms
-    const result4 = await send peers.event("compareAlgorithms").role(SecurityAgent).any()({
-      text: "The quick brown fox jumps over the lazy dog"
-    }) timeout 10s
-
-    console.log("\n" + "█".repeat(60))
-    console.log("█" + " ".repeat(58) + "█")
-    console.log("█" + "  All Crypto Tests Completed Successfully!".padEnd(58) + "█")
-    console.log("█" + " ".repeat(58) + "█")
-    console.log("█".repeat(60))
-
-    return {
-      success: true,
-      tests: {
-        passwordHashing: result1,
-        hashVerification: result2,
-        dataIntegrity: result3,
-        algorithmComparison: result4
-      }
-    }
-  }
-}
-
-run Coordinator.runTests({})

package/examples/test-delegation.koi

@@ -1,41 +0,0 @@
-// Test delegation with explicit data passing
-package "test.delegation"
-
-role Worker { can execute }
-
-// Specialist that saves users
-Agent Saver : Worker {
-  llm default = { provider: "openai", model: "gpt-4o-mini" }
-
-  on saveUser(args: Json) {
-    playbook """
-    Save a user to registry with key "user:${args.id}".
-    User data: name="${args.name}", age=${args.age}
-
-    Return: { "saved": true, "id": "${args.id}", "name": "${args.name}" }
-    """
-  }
-}
-
-// Team containing the saver
-Team SaverTeam {
-  saver = Saver
-}
-
-// Orchestrator that delegates
-Agent Orchestrator : Worker {
-  llm default = { provider: "openai", model: "gpt-4o-mini" }
-  uses Team SaverTeam
-
-  on start(args: Json) {
-    playbook """
-    Delegate the task of saving a user named "TestUser" with ID "123" and age 25.
-
-    CRITICAL: Pass data: { "id": "123", "name": "TestUser", "age": 25 }
-
-    Return the result from the delegation.
-    """
-  }
-}
-
-run Orchestrator.start({})