@koi-language/koi 1.0.5 → 1.1.0

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

@@ -1,18 +1,16 @@
-package "demo.multi.event"
-
 role Calculator { can calculate }
-role Coordinator { can coordinate }
+role Coordinator { can coordinate, can delegate }
 
-// Agent con múltiples event handlers
-// Cada handler tiene su propio affordance (del playbook)
-Agent StatisticsCalculator : Calculator {
+// Agent with multiple event handlers
+// Each handler has its own affordance (from the playbook)
+agent StatisticsCalculator : Calculator {
   llm default = {
     provider: "openai",
     model: "gpt-4o-mini",
     temperature: 0.1
   }
 
-  // Event handler para calcular media
+  // Event handler to calculate the mean
   on mean(args: Json) {
     playbook """
     Calculate the arithmetic mean (average) of the numbers: ${JSON.stringify(args.numbers)}
@@ -22,7 +20,7 @@ Agent StatisticsCalculator : Calculator {
     """
   }
 
-  // Event handler para calcular mediana
+  // Event handler to calculate the median
   on median(args: Json) {
     playbook """
     Calculate the median (middle value) of ${JSON.stringify(args.numbers)}
@@ -32,7 +30,7 @@ Agent StatisticsCalculator : Calculator {
     """
   }
 
-  // Event handler para calcular desviación estándar
+  // Event handler to calculate the standard deviation
   on stddev(args: Json) {
     playbook """
     Calculate the standard deviation for ${JSON.stringify(args.numbers)}
@@ -44,19 +42,19 @@ Agent StatisticsCalculator : Calculator {
   }
 }
 
-Team CalculatorTeam {
-  calculator = StatisticsCalculator
+team CalculatorTeam {
+  calculator: StatisticsCalculator
 }
 
-// Orchestrator que decide qué evento enviar basándose en la intención
-Agent Orchestrator : Coordinator {
+// Orchestrator that decides which event to send based on intent
+agent Orchestrator : Coordinator {
   llm default = {
     provider: "openai",
     model: "gpt-4o-mini",
     temperature: 0.1
   }
 
-  uses Team CalculatorTeam
+  uses team CalculatorTeam
 
   on process(args: Json) {
     playbook """
@@ -85,12 +83,12 @@ Agent Orchestrator : Coordinator {
   }
 }
 
-Team OrchestratorTeam {
-  orchestrator = Orchestrator
+team OrchestratorTeam {
+  orchestrator: Orchestrator
 }
 
-Agent Main : Coordinator {
-  uses Team OrchestratorTeam
+agent Main : Coordinator {
+  uses team OrchestratorTeam
 
   on start(args: Json) {
     console.log("╔════════════════════════════════════════════╗")

package/examples/pipeline.koi

@@ -3,13 +3,11 @@
 // Shows multi-stage data processing
 // ============================================================
 
-package "demo.koi.pipeline"
-
 role Worker   { can execute }
 role Reviewer { can critique }
 role Lead     { can delegate }
 
-Agent Extractor : Worker {
+agent Extractor : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 300 }
 
   on extract(args: Json) {
@@ -37,7 +35,7 @@ Agent Extractor : Worker {
   }
 }
 
-Agent Transformer : Worker {
+agent Transformer : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 300 }
 
   on transform(args: Json) {
@@ -66,7 +64,7 @@ Agent Transformer : Worker {
   }
 }
 
-Agent Validator : Reviewer {
+agent Validator : Reviewer {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
 
   on validate(args: Json) {
@@ -96,7 +94,7 @@ Agent Validator : Reviewer {
   }
 }
 
-Agent Loader : Worker {
+agent Loader : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.2, max_tokens: 250 }
 
   on load(args: Json) {
@@ -122,34 +120,34 @@ Agent Loader : Worker {
   }
 }
 
-Team Pipeline {
-  extractor = Extractor
-  transformer = Transformer
-  validator = Validator
-  loader = Loader
+team Pipeline {
+  extractor: Extractor
+  transformer: Transformer
+  validator: Validator
+  loader: Loader
 }
 
-Agent Orchestrator : Lead {
-  uses Team Pipeline
+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
+      await send peers.event("extract").role(Worker).any()({ raw: raw }) timeout 30s
 
     const transformed =
-      await send peers.event("transform").role(Worker).any()({ data: extracted.data }) timeout 5s
+      await send peers.event("transform").role(Worker).any()({ data: extracted.data }) timeout 30s
 
     const validation =
-      await send peers.event("validate").role(Reviewer).any()({ data: transformed.data }) timeout 5s
+      await send peers.event("validate").role(Reviewer).any()({ data: transformed.data }) timeout 30s
 
     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
+      await send peers.event("load").role(Worker).any()({ data: transformed.data }) timeout 30s
 
     return {
       ok: true,

package/examples/prompt-demo.koi

@@ -0,0 +1,20 @@
+// Demo: Prompt User Action
+// Shows how agents can ask users for input during execution
+
+role Worker { can execute }
+
+agent Assistant : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on greet(args: Json) {
+    playbook """
+    
+    Ask the user for their name, then ask if they want to continue,
+    and if they do, ask which color they prefer among yellow, blue, or red, and then ask for their age.
+
+    Finally, give them a greeting and joke about their age however you like.
+    """
+  }
+}
+
+run Assistant.greet({})

package/examples/{registry-playbook-email-compositor.koi → registry-interactive-demo.koi}

@@ -1,13 +1,26 @@
 // Registry with Natural Language Playbooks Demo
 // Shows how agents can use registry operations naturally in playbooks
-package "registry.playbook.demo"
 
 role Worker { can execute, can registry }
 role Manager { can execute, can delegate }
 
 // Agent that uses natural language to interact with registry
-Agent UserManager : Worker {
+agent UserManager : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini" }
+  amnesia = true
+
+  on createAllUser(args: Json) {
+    playbook """
+    Create all given users via args, with the following attributes
+    - name, age, email
+
+    Save all to registry with key "user:id being id an unique identifier".
+    Include all fields plus a createdAt timestamp.
+    Return: { "success": true, "message": "Users created" }
+
+    DO NOT add print actions - just return the data. 
+    """
+  }
 
   on createUser(args: Json) {
     playbook """
@@ -80,7 +93,7 @@ Agent UserManager : Worker {
 
   on deleteUser(args: Json) {
     playbook """
-    Borra el usuario del registro con ID ${args.id}.
+    Delete the user from the registry with ID ${args.id}.
 
     EXACT STEPS:
     1. Use registry_delete with key "user:\${args.id}"
@@ -90,46 +103,33 @@ Agent UserManager : Worker {
 }
 
 // Team that groups our agents
-Team RegistryTeam {
-  userManager = UserManager
+team RegistryTeam {
+  userManager: UserManager
 }
 
 // Orchestrator - uses playbook, router finds UserManager automatically!
-Agent Demo : Manager {
+agent Demo : Manager {
   llm default = { provider: "openai", model: "gpt-4o-mini" }
-  uses Team RegistryTeam
+  uses team RegistryTeam
 
   on start(args: Json) {
     //SUPER IMPORTANT: DO NOT CHANGE THE FOLLOWING PROMPT AT ALL!!!!!!
     playbook """
-    Ejecuta un demo del registro de usuarios.
+    Run a user registry demo.
 
-    Muestra el header:
+    Show the header (just the very first time):
     ╔══════════════════════════════════════════════════╗
     ║  Registry with Playbook Demo                     ║
     ╚══════════════════════════════════════════════════╝
 
-    1️⃣ Crea estos usuarios:
-    - Alice: id=001, age=30, email=alice@example.com
-    - Bob: id=002, de 17 años, bob@example.com
-    - Charlie: id=003, age=25, email=charlie@example.com
-    - Diana: id=004, age is 35, diana@example.com
-    - Erika: id=005, age=28, email=erika@example.com
-    - Fernando: id=006, age=32, fernando@example.com
-    Muestra: "   ✅ X users created" X es la cantidad de usuarios que se crearon
-
-    2️⃣ Por cada usuario en la base de datos, escribe este correo:
-
-    Estimado (o Estimada si es chica, deducelo por el nombre),
+    Them ask the user what it wants: create / consult / modify / delete any user and do what the user wants.
+    Aks as many info as you need to the user to perform the action the user wants from you.
 
-    Como sabemos que usted tiene {x} años, le queremos dar la enhorabuena!
-    
-    Atentamente,
-    La empresa!!
+    After performing an action, ask the user if it want to continuer, and in that case ask again what it wants (loop)
 
-    Muestra cada correo que escribieste.
+    If the user wnats to list the users, for each one show in a markdown table: Mr or Ms depending on whether they are male or female (deduce this from the name) and then {the user's name}, age {their age}"
 
-    Muestra el footer:
+    Before exiting, print:
     ╔══════════════════════════════════════════════════╗
     ║  Demo completed successfully!                    ║
     ╚══════════════════════════════════════════════════╝

package/examples/registry-playbook-demo.koi

@@ -1,13 +1,13 @@
 // Registry with Natural Language Playbooks Demo
 // Shows how agents can use registry operations naturally in playbooks
-package "registry.playbook.demo"
 
 role Worker { can execute, can registry }
 role Manager { can execute, can delegate }
 
 // Agent that uses natural language to interact with registry
-Agent UserManager : Worker {
+agent UserManager : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini" }
+  amnesia = true
 
   on createAllUser(args: Json) {
     playbook """
@@ -18,7 +18,7 @@ Agent UserManager : Worker {
     Include all fields plus a createdAt timestamp.
     Return: { "success": true, "message": "Users created" }
 
-    DO NOT add print actions - just return the data.
+    DO NOT add print actions - just return the data. 
     """
   }
 
@@ -93,7 +93,7 @@ Agent UserManager : Worker {
 
   on deleteUser(args: Json) {
     playbook """
-    Borra el usuario del registro con ID ${args.id}.
+    Delete the user from the registry with ID ${args.id}.
 
     EXACT STEPS:
     1. Use registry_delete with key "user:\${args.id}"
@@ -103,55 +103,55 @@ Agent UserManager : Worker {
 }
 
 // Team that groups our agents
-Team RegistryTeam {
-  userManager = UserManager
+team RegistryTeam {
+  userManager: UserManager
 }
 
 // Orchestrator - uses playbook, router finds UserManager automatically!
-Agent Demo : Manager {
+agent Demo : Manager {
   llm default = { provider: "openai", model: "gpt-4o-mini" }
-  uses Team RegistryTeam
+  uses team RegistryTeam
 
   on start(args: Json) {
     //SUPER IMPORTANT: DO NOT CHANGE THE FOLLOWING PROMPT AT ALL!!!!!!
     playbook """
-    Ejecuta un demo del registro de usuarios.
+    Run a user registry demo.
 
-    Muestra el header:
+    Show the header:
     ╔══════════════════════════════════════════════════╗
     ║  Registry with Playbook Demo                     ║
     ╚══════════════════════════════════════════════════╝
 
-    1️⃣ Crea estos usuarios:
+    1️⃣ Create these users:
     - Alice: id=001, age=30, email=alice@example.com
-    - Bob: id=002, de 17 años, bob@example.com
+    - Bob: id=002, 17 years old, bob@example.com
     - Charlie: id=003, age=25, email=charlie@example.com
     - Diana: id=004, age is 35, diana@example.com
     - Erika: id=005, age=28, email=erika@example.com
     - Fernando: id=006, age=32, fernando@example.com
-    Muestra: "   ✅ X users created" X es la cantidad de usuarios que se crearon
+    Show: "   ✅ X users created" where X is the number of users that were created
 
-    2️⃣ Obtén el usuario 001
-    Muestra: "   ✅ Found user: {el nombre del usuario}, age {su edad}"
+    2️⃣ Get user 001
+    Show: "   ✅ Found user: {the user's name}, age {their age}"
 
-    3️⃣ Lista todos los usuarios
-    Muestra: "   ✅ Found {la cantidad de usuarios} users y luego por cada uno muestra en una tabla en markdown: sr o sra si es chico o chica (esto deducelo por el nombre) y luego {el nombre del usuario}, age {su edad}"
+    3️⃣ List all users
+    Show: "   ✅ Found {the number of users} users then for each one show in a markdown table: Mr or Ms depending on whether they are male or female (deduce this from the name) and then {the user's name}, age {their age}"
 
-    4️⃣ Busca usuarios mayores de 18 años
-    Muestra: "   ✅ Found {la cantidad encontrada} adults"
+    4️⃣ Search for users older than 18 years
+    Show: "   ✅ Found {the number found} adults"
 
-    5️⃣ Actualiza la edad de Bob (002) a 19 años
-    Luego obtén el usuario actualizado
-    Muestra: "   ✅ Bob is now {su nueva edad} years old"
+    5️⃣ Update Bob's age (002) to 19 years old
+    Then get the updated user
+    Show: "   ✅ Bob is now {his new age} years old"
 
-    6️⃣ Elimina a Charlie (003)
-    Luego lista los usuarios restantes
-    Muestra: "   ✅ Remaining users: {la cantidad restante}"
+    6️⃣ Delete Charlie (003)
+    Then list the remaining users
+    Show: "   ✅ Remaining users: {the remaining count}"
 
-    7️⃣ Vuelve a listar todos los usuarios como lo has hecho en el paso 3️⃣
-    Muestra los usuarios que hay en la tabla en markdown con el mismo formato que en el paso 3️⃣
+    7️⃣ List all users again as you did in step 3️⃣
+    Show the users in a markdown table with the same format as in step 3️⃣
 
-    Muestra el footer:
+    Show the footer:
     ╔══════════════════════════════════════════════════╗
     ║  Demo completed successfully!                    ║
     ╚══════════════════════════════════════════════════╝

package/examples/skill-import-test.koi

@@ -3,17 +3,15 @@
 // Tests importing Skills from external files
 // ============================================================
 
-package "demo.koi.import"
-
 // Import the Math Operations skill
 import "./skills/math-operations.koi"
 
-role Calculator { can calculate }
+role Calculator { can execute }
 
 // Agent that uses the imported MathOperations skill
-Agent MathAgent : Calculator {
+agent MathAgent : Calculator {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
-  uses Skill MathOperations
+  uses skill MathOperations
 
   on calculate(args: Json) {
     playbook """
@@ -26,13 +24,13 @@ Agent MathAgent : Calculator {
 }
 
 // Create a team
-Team MathTeam {
-  calculator = MathAgent
+team MathTeam {
+  calculator: MathAgent
 }
 
 // Demo runner
-Agent DemoRunner : Calculator {
-  uses Team MathTeam
+agent DemoRunner : Calculator {
+  uses team MathTeam
 
   on runTest(args: Json) {
     console.log("╔════════════════════════════════════════════╗")