@koi-language/koi 1.0.0

package/examples/registry-demo.koi

@@ -0,0 +1,184 @@
+// Registry Demo - Shared data store between agents
+package "registry.demo"
+
+role Worker { can execute }
+
+// Agent that writes data to the registry
+Agent Writer : Worker {
+  on saveUser(args: Json) {
+    const userId = args.id
+    const userData = {
+      name: args.name,
+      age: args.age,
+      email: args.email,
+      createdAt: Date.now()
+    }
+
+    await registry.set("user:" + userId, userData)
+
+    console.log("✅ Saved user:", userId)
+    return { saved: true, userId: userId }
+  }
+
+  on saveConfig(args: Json) {
+    await registry.set("config:app", {
+      theme: args.theme || "dark",
+      language: args.language || "en",
+      notifications: args.notifications !== false
+    })
+
+    console.log("✅ Saved config")
+    return { saved: true }
+  }
+}
+
+// Agent that reads data from the registry
+Agent Reader : Worker {
+  on getUser(args: Json) {
+    const userId = args.id
+    const user = await registry.get("user:" + userId)
+
+    if (!user) {
+      console.log("❌ User not found:", userId)
+      return { found: false, userId: userId }
+    }
+
+    console.log("📖 Retrieved user:", user.name)
+    return { found: true, user: user }
+  }
+
+  on getConfig(args: Json) {
+    const config = await registry.get("config:app")
+
+    if (!config) {
+      console.log("⚙️  No config found, using defaults")
+      return { found: false, config: null }
+    }
+
+    console.log("⚙️  Retrieved config:", JSON.stringify(config))
+    return { found: true, config: config }
+  }
+
+  on listUsers(args: Json) {
+    const userKeys = await registry.keys("user:")
+    console.log("📋 Found", userKeys.length, "users")
+
+    const users = []
+    for (const key of userKeys) {
+      const user = await registry.get(key)
+      users.push({ id: key.replace("user:", ""), ...user })
+    }
+
+    return { count: users.length, users: users }
+  }
+}
+
+// Agent that searches the registry
+Agent Searcher : Worker {
+  on findAdults(args: Json) {
+    const results = await registry.search({
+      age: { $gte: 18 }
+    })
+
+    console.log("🔍 Found", results.length, "adults")
+
+    const adults = results.map(r => ({
+      id: r.key.replace("user:", ""),
+      ...r.value
+    }))
+
+    return { count: adults.length, adults: adults }
+  }
+
+  on findByName(args: Json) {
+    const results = await registry.search({
+      name: { $regex: args.pattern }
+    })
+
+    console.log("🔍 Found", results.length, "matching users")
+
+    const matches = results.map(r => ({
+      id: r.key.replace("user:", ""),
+      ...r.value
+    }))
+
+    return { count: matches.length, matches: matches }
+  }
+}
+
+// Orchestrator that coordinates the demo
+Agent Demo : Worker {
+  on start(args: Json) {
+    console.log("═════════════════════════════════════════════")
+    console.log("  Registry Demo - Shared Data Store")
+    console.log("═════════════════════════════════════════════")
+    console.log("")
+
+    // 1. Save some users
+    console.log("1️⃣  Saving users...")
+    await Writer.handle("saveUser", { id: "001", name: "Alice", age: 30, email: "alice@example.com" })
+    await Writer.handle("saveUser", { id: "002", name: "Bob", age: 25, email: "bob@example.com" })
+    await Writer.handle("saveUser", { id: "003", name: "Charlie", age: 17, email: "charlie@example.com" })
+    await Writer.handle("saveUser", { id: "004", name: "Diana", age: 35, email: "diana@example.com" })
+    console.log("")
+
+    // 2. Save config
+    console.log("2️⃣  Saving config...")
+    await Writer.handle("saveConfig", { theme: "light", language: "es", notifications: true })
+    console.log("")
+
+    // 3. Read individual user
+    console.log("3️⃣  Reading user...")
+    const userResult = await Reader.handle("getUser", { id: "001" })
+    console.log("   User:", JSON.stringify(userResult.user, null, 2))
+    console.log("")
+
+    // 4. Read config
+    console.log("4️⃣  Reading config...")
+    const configResult = await Reader.handle("getConfig", {})
+    console.log("   Config:", JSON.stringify(configResult.config, null, 2))
+    console.log("")
+
+    // 5. List all users
+    console.log("5️⃣  Listing all users...")
+    const listResult = await Reader.handle("listUsers", {})
+    for (const user of listResult.users) {
+      console.log("   -", user.name, "(" + user.age + " years old)")
+    }
+    console.log("")
+
+    // 6. Search for adults
+    console.log("6️⃣  Searching for adults (age >= 18)...")
+    const adultsResult = await Searcher.handle("findAdults", {})
+    for (const adult of adultsResult.adults) {
+      console.log("   -", adult.name, "(" + adult.age + " years old)")
+    }
+    console.log("")
+
+    // 7. Search by name pattern
+    console.log("7️⃣  Searching for names containing 'a'...")
+    const searchResult = await Searcher.handle("findByName", { pattern: "a" })
+    for (const match of searchResult.matches) {
+      console.log("   -", match.name)
+    }
+    console.log("")
+
+    // 8. Show stats
+    console.log("8️⃣  Registry stats...")
+    const stats = await registry.stats()
+    console.log("   Backend:", stats.backend)
+    console.log("   Entries:", stats.count)
+    console.log("   File:", stats.file)
+    console.log("   Size:", stats.size, "bytes")
+    console.log("")
+
+    console.log("═════════════════════════════════════════════")
+    console.log("  Demo Complete!")
+    console.log("  Data persisted to:", stats.file)
+    console.log("═════════════════════════════════════════════")
+
+    return { success: true }
+  }
+}
+
+run Demo.start({})

package/examples/registry-playbook-demo.koi

@@ -0,0 +1,162 @@
+// 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 {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  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 """
+    Create a new user with:
+    - name: ${args.name}
+    - age: ${args.age}
+    - email: ${args.email}
+
+    Save to registry with key "user:${args.id}".
+    Include all fields plus a createdAt timestamp.
+    Return: { "success": true, "message": "User created" }
+
+    DO NOT add print actions - just return the data.
+    """
+  }
+
+  on getUser(args: Json) {
+    playbook """
+    Get user ${args.id} from registry.
+
+    Use registry_get with key "user:${args.id}".
+    Extract the .value field from the registry_get result (which contains the user data).
+    Return ONLY the user data object (name, age, email, createdAt) without any wrapper.
+    """
+  }
+
+  on listAllUsers(args: Json) {
+    playbook """
+    List all users in the registry.
+
+    EXACT STEPS:
+    1. Use registry_search with an empty query {} to get ALL users, store with ID "a1"
+    2. Extract just the user data (the .value field) from each result
+    3. Return: { "count": <count from a1>, "users": <array of user value objects, NOT the full {key, value} wrappers> }
+
+    Example: If a1.output.results = [{key: "user:001", value: {name: "Alice", age: 30}}, ...]
+    Then return: { "count": 2, "users": [{name: "Alice", age: 30}, ...] }
+
+    CRITICAL: Extract ONLY the .value objects so caller can access with .users[0].name directly
+    DO NOT use format action - return a real array!
+    """
+  }
+
+  on findAdults(args: Json) {
+    playbook """
+    Find all users aged 18 or older using registry search with query: { "age": { "$gte": 18 } }
+
+    EXACT STEPS:
+    1. Use registry_search with query: { "age": { "$gte": 18 } }
+    2. Return: { "count": [count from search], "adults": [results array] }
+
+    DO NOT add print actions - just return the data!
+    """
+  }
+
+  on updateUserAge(args: Json) {
+    playbook """
+    Update user ${args.id}'s age to ${args.age}.
+
+    EXACT STEPS:
+    1. Use registry_get with key "user:${args.id}", store with ID "a1"
+    2. Take the full user object from \${a1.output.value}
+    3. Modify ONLY the age field to ${args.age}, keep all other fields (name, email, createdAt, etc.)
+    4. Use registry_set with key "user:${args.id}" and the complete updated object
+    5. Return: { "success": true, "message": "Age updated" }
+
+    CRITICAL: Preserve ALL existing fields when saving!
+    """
+  }
+
+  on deleteUser(args: Json) {
+    playbook """
+    Borra el usuario del registro con ID ${args.id}.
+
+    EXACT STEPS:
+    1. Use registry_delete with key "user:\${args.id}"
+    2. Return: { "success": true, "message": "User deleted" }
+    """
+  }
+}
+
+// Team that groups our agents
+Team RegistryTeam {
+  userManager = UserManager
+}
+
+// Orchestrator - uses playbook, router finds UserManager automatically!
+Agent Demo : Manager {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+  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.
+
+    Muestra el header:
+    ╔══════════════════════════════════════════════════╗
+    ║  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️⃣ Obtén el usuario 001
+    Muestra: "   ✅ Found user: {el nombre del usuario}, age {su edad}"
+
+    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}"
+
+    4️⃣ Busca usuarios mayores de 18 años
+    Muestra: "   ✅ Found {la cantidad encontrada} 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"
+
+    6️⃣ Elimina a Charlie (003)
+    Luego lista los usuarios restantes
+    Muestra: "   ✅ Remaining users: {la cantidad restante}"
+
+    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️⃣
+
+    Muestra el footer:
+    ╔══════════════════════════════════════════════════╗
+    ║  Demo completed successfully!                    ║
+    ╚══════════════════════════════════════════════════╝
+    """
+  }
+}
+
+run Demo.start({})

package/examples/registry-playbook-email-compositor-2.koi

@@ -0,0 +1,140 @@
+// 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 {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on createUser(args: Json) {
+    playbook """
+    Create a new user with ALL fields from args:
+    - name: ${args.name}
+    - age: ${args.age}
+    - email: ${args.email}
+    - birthdate: ${args.birthdate} (if provided)
+    - id: ${args.id}
+
+    Save to registry with key "user:${args.id}".
+    CRITICAL: Include ALL fields from args (name, age, email, birthdate, id) plus a createdAt timestamp.
+    Return: { "success": true, "message": "User created" }
+
+    DO NOT add print actions - just return the data.
+    """
+  }
+
+  on getUser(args: Json) {
+    playbook """
+    Get user ${args.id} from registry.
+
+    Use registry_get with key "user:${args.id}".
+    Extract the .value field from the registry_get result (which contains the user data).
+    Return ONLY the user data object (name, age, email, createdAt) without any wrapper.
+    """
+  }
+
+  on listAllUsers(args: Json) {
+    playbook """
+    List all users in the registry.
+
+    EXACT STEPS:
+    1. Use registry_search with an empty query {} to get ALL users, store with ID "a1"
+    2. Extract just the user data (the .value field) from each result
+    3. Return: { "count": <count from a1>, "users": <array of user value objects, NOT the full {key, value} wrappers> }
+
+    Example: If a1.output.results = [{key: "user:001", value: {name: "Alice", age: 30}}, ...]
+    Then return: { "count": 2, "users": [{name: "Alice", age: 30}, ...] }
+
+    CRITICAL: Extract ONLY the .value objects so caller can access with .users[0].name directly
+    DO NOT use format action - return a real array!
+    """
+  }
+
+  on findAdults(args: Json) {
+    playbook """
+    Find all users aged 18 or older using registry search with query: { "age": { "$gte": 18 } }
+
+    EXACT STEPS:
+    1. Use registry_search with query: { "age": { "$gte": 18 } }
+    2. Return: { "count": [count from search], "adults": [results array] }
+
+    DO NOT add print actions - just return the data!
+    """
+  }
+
+  on updateUserAge(args: Json) {
+    playbook """
+    Update user ${args.id}'s age to ${args.age}.
+
+    EXACT STEPS:
+    1. Use registry_get with key "user:${args.id}", store with ID "a1"
+    2. Take the full user object from \${a1.output.value}
+    3. Modify ONLY the age field to ${args.age}, keep all other fields (name, email, createdAt, etc.)
+    4. Use registry_set with key "user:${args.id}" and the complete updated object
+    5. Return: { "success": true, "message": "Age updated" }
+
+    CRITICAL: Preserve ALL existing fields when saving!
+    """
+  }
+
+  on deleteUser(args: Json) {
+    playbook """
+    Borra el usuario del registro con ID ${args.id}.
+
+    EXACT STEPS:
+    1. Use registry_delete with key "user:\${args.id}"
+    2. Return: { "success": true, "message": "User deleted" }
+    """
+  }
+}
+
+// Team that groups our agents
+Team RegistryTeam {
+  userManager = UserManager
+}
+
+// Orchestrator - uses playbook, router finds UserManager automatically!
+Agent Demo : Manager {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+  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.
+
+    Muestra el header:
+    ╔══════════════════════════════════════════════════╗
+    ║  Registry with Playbook Demo                     ║
+    ╚══════════════════════════════════════════════════╝
+
+    1️⃣ Crea estos usuarios:
+    - Alice: id=001, birthdate=1985-12-05, email=alice@example.com
+    - Bob: id=002, fecha de nacimiento: 12 de abril de 2001, bob@example.com
+    - Moema: id=003, birth date: 1992 enero 29, email=charlie@example.com
+    - Diana: id=004, birthdate: 12 del 12 del 12, diana@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) <nombre persona>,
+
+    Como sabemos que usted tiene {x} años, le queremos dar la enhorabuena!
+    
+    Atentamente,
+    La empresa!!
+
+    Muestra cada correo que escribieste.
+
+    Muestra el footer:
+    ╔══════════════════════════════════════════════════╗
+    ║  Demo completed successfully!                    ║
+    ╚══════════════════════════════════════════════════╝
+    """
+  }
+}
+
+run Demo.start({})

package/examples/registry-playbook-email-compositor.koi

@@ -0,0 +1,140 @@
+// 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 {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on createUser(args: Json) {
+    playbook """
+    Create a new user with:
+    - name: ${args.name}
+    - age: ${args.age}
+    - email: ${args.email}
+
+    Save to registry with key "user:${args.id}".
+    Include all fields plus a createdAt timestamp.
+    Return: { "success": true, "message": "User created" }
+
+    DO NOT add print actions - just return the data.
+    """
+  }
+
+  on getUser(args: Json) {
+    playbook """
+    Get user ${args.id} from registry.
+
+    Use registry_get with key "user:${args.id}".
+    Extract the .value field from the registry_get result (which contains the user data).
+    Return ONLY the user data object (name, age, email, createdAt) without any wrapper.
+    """
+  }
+
+  on listAllUsers(args: Json) {
+    playbook """
+    List all users in the registry.
+
+    EXACT STEPS:
+    1. Use registry_search with an empty query {} to get ALL users, store with ID "a1"
+    2. Extract just the user data (the .value field) from each result
+    3. Return: { "count": <count from a1>, "users": <array of user value objects, NOT the full {key, value} wrappers> }
+
+    Example: If a1.output.results = [{key: "user:001", value: {name: "Alice", age: 30}}, ...]
+    Then return: { "count": 2, "users": [{name: "Alice", age: 30}, ...] }
+
+    CRITICAL: Extract ONLY the .value objects so caller can access with .users[0].name directly
+    DO NOT use format action - return a real array!
+    """
+  }
+
+  on findAdults(args: Json) {
+    playbook """
+    Find all users aged 18 or older using registry search with query: { "age": { "$gte": 18 } }
+
+    EXACT STEPS:
+    1. Use registry_search with query: { "age": { "$gte": 18 } }
+    2. Return: { "count": [count from search], "adults": [results array] }
+
+    DO NOT add print actions - just return the data!
+    """
+  }
+
+  on updateUserAge(args: Json) {
+    playbook """
+    Update user ${args.id}'s age to ${args.age}.
+
+    EXACT STEPS:
+    1. Use registry_get with key "user:${args.id}", store with ID "a1"
+    2. Take the full user object from \${a1.output.value}
+    3. Modify ONLY the age field to ${args.age}, keep all other fields (name, email, createdAt, etc.)
+    4. Use registry_set with key "user:${args.id}" and the complete updated object
+    5. Return: { "success": true, "message": "Age updated" }
+
+    CRITICAL: Preserve ALL existing fields when saving!
+    """
+  }
+
+  on deleteUser(args: Json) {
+    playbook """
+    Borra el usuario del registro con ID ${args.id}.
+
+    EXACT STEPS:
+    1. Use registry_delete with key "user:\${args.id}"
+    2. Return: { "success": true, "message": "User deleted" }
+    """
+  }
+}
+
+// Team that groups our agents
+Team RegistryTeam {
+  userManager = UserManager
+}
+
+// Orchestrator - uses playbook, router finds UserManager automatically!
+Agent Demo : Manager {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+  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.
+
+    Muestra el header:
+    ╔══════════════════════════════════════════════════╗
+    ║  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),
+
+    Como sabemos que usted tiene {x} años, le queremos dar la enhorabuena!
+    
+    Atentamente,
+    La empresa!!
+
+    Muestra cada correo que escribieste.
+
+    Muestra el footer:
+    ╔══════════════════════════════════════════════════╗
+    ║  Demo completed successfully!                    ║
+    ╚══════════════════════════════════════════════════╝
+    """
+  }
+}
+
+run Demo.start({})