language-operator 0.1.53 → 0.1.54

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 362d72d195bf272f98204cba33e7f8bf6513c7544a6bf6d6369c2ef1b9cfe793
-  data.tar.gz: d75edb537a7bec08fbba3a6b96dc05e9ecdbf62d7e80b9d33176f365623f4542
+  metadata.gz: cc9f8e717ca6bd8f00386094494b88f2f2e3050239b9d476ba9519868d82df58
+  data.tar.gz: b15364fd16e4a9793263a8d861999d3c0a9188c2db3c6122176462a6b934c753
 SHA512:
-  metadata.gz: 7c3c378dfb4a013a1590b7c3295ad7f948a74d076f9ae38e50d587c7dfc26f254669c2586ff02aaa6fd8f1c5b933d67f627d7777f950f5bcacf59575b56c6da1
-  data.tar.gz: 7f956e31db63897853f31d237181c54f85b6c352d350ce4d3347bffaec0d4aaca7d2a2082b9c0092bd0f7972938271d9309e85ecb835679fca9e19008ec6dc2f
+  metadata.gz: 62729e36597f476b960c64b589a2e426ef5fe54f51e7db91d0ab91cdbc05a916fc000bc94c1e828e9839e2f6bff95a31f42f3c330006a008bc9c1e2a2fd63e03
+  data.tar.gz: a5472ea444b2d6bf58316c638b03b22365bd51e6b635a3eb3b2cb2d458a540e802def9e7d86243ec72bf958924b1c4441485ea8cf9121c7d96647a9bf046cec9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    language-operator (0.1.53)
+    language-operator (0.1.54)
       faraday (~> 2.0)
       k8s-ruby (~> 0.17)
       mcp (~> 0.4)

data/lib/language_operator/templates/agent_synthesis.tmpl

@@ -77,8 +77,8 @@ This is attempt {{.AttemptNumber}} of {{.MaxAttempts}}. The user is counting on
 
 **Runtime Context:**
 - All agent messages and output are automatically logged to stdout
-- Agents have access to a workspace directory for file operations
 - LLM responses are captured and available in agent execution context
+- File operations should use neural tasks that delegate to the workspace tool (see examples below)
 
 ## DSL v1 Reference Examples
 
@@ -174,16 +174,72 @@ agent "data-pipeline" do
 
   main do |inputs|
     extracted = execute_task(:extract_data, inputs: inputs)
-    transformed = execute_task(:transform_data, inputs: extracted)
+    transformed = execute_task(:transform_data, inputs: transformed)
     result = execute_task(:load_data, inputs: transformed)
     result
   end
 end
 ```
 
+### Example 4: Stateful Agent with Workspace File Operations
+```ruby
+require 'language_operator'
+
+agent "story-builder" do
+  description "Build a story one sentence at a time"
+  mode :scheduled
+  schedule "0 * * * *"
+
+  # Neural task - LLM reads file using workspace tool
+  task :read_existing_story,
+    instructions: "Read the story.txt file from workspace. If it doesn't exist, return empty string. Return the content and count of sentences.",
+    inputs: {},
+    outputs: { content: 'string', sentence_count: 'integer' }
+
+  # Neural task - LLM generates creative continuation
+  task :generate_next_sentence,
+    instructions: "Generate exactly one new sentence to continue this story. Maintain consistent tone and style. Only output the new sentence.",
+    inputs: { existing_content: 'string' },
+    outputs: { sentence: 'string' }
+
+  # Neural task - LLM writes file using workspace tool
+  task :append_to_story,
+    instructions: "Append the new sentence to story.txt in workspace. If the file has existing content, add a newline first.",
+    inputs: { sentence: 'string' },
+    outputs: { success: 'boolean', total_sentences: 'integer' }
+
+  main do |inputs|
+    # Read current state from workspace
+    story_data = execute_task(:read_existing_story)
+
+    # Generate new content based on what exists
+    new_sentence = execute_task(:generate_next_sentence,
+                                inputs: { existing_content: story_data[:content] })
+
+    # Persist to workspace for next run
+    result = execute_task(:append_to_story,
+                         inputs: { sentence: new_sentence[:sentence] })
+
+    { sentence: new_sentence[:sentence], total: result[:total_sentences] }
+  end
+
+  output do |outputs|
+    puts "Added sentence: #{outputs[:sentence]}"
+    puts "Story now has #{outputs[:total]} sentences"
+  end
+end
+```
+
+**File Operations Best Practices:**
+- **NEVER** use direct Ruby file operations (`File.read`, `File.write`, `File.open`, `Dir.pwd`, etc.) in agent code
+- **ALWAYS** delegate file operations to neural tasks with clear natural language instructions
+- File operations require the LLM to reason about paths, content, and state - use the workspace tool via neural tasks
+- The workspace tool provides: `read_file`, `write_file`, `list_directory`, `create_directory`, `get_file_info`, `search_files`
+- Example pattern: `task :read_data, instructions: "read data.json from workspace and parse it", inputs: {}, outputs: { data: 'hash' }`
+
 ## Your Task: Generate DSL v1 Agent
 
-Using the THREE CONCRETE EXAMPLES above (daily-report, code-reviewer, data-pipeline) as reference patterns, generate WORKING Ruby DSL code for the agent described in the user instructions.
+Using the FOUR CONCRETE EXAMPLES above (daily-report, code-reviewer, data-pipeline, story-builder) as reference patterns, generate WORKING Ruby DSL code for the agent described in the user instructions.
 
 **CRITICAL REQUIREMENTS:**
 - DO NOT output placeholder text like "Brief description extracted from instructions" or "CRON_EXPRESSION"
@@ -250,6 +306,9 @@ end
 - ✓ Are all task names, descriptions, and logic SPECIFIC to the user's request?
 - ✓ Did you AVOID outputting placeholders like "task_name" or "CRON_EXPRESSION"?
 - ✓ Does the code actually DO what the user asked for?
+- ✓ Did you use NEURAL TASKS (not symbolic code blocks) for all file operations?
+- ✓ Did you NEVER use File.read, File.write, Dir.pwd, or other direct file APIs?
+- ✓ For workspace operations, did you write clear instructions for the LLM to use the workspace tool?
 
 If you cannot answer YES to all of the above, re-read the user instructions and generate FUNCTIONAL code.
 

data/lib/language_operator/templates/schema/agent_dsl_openapi.yaml

@@ -2,7 +2,7 @@
 :openapi: 3.0.3
 :info:
   :title: Language Operator Agent API
-  :version: 0.1.53
+  :version: 0.1.54
   :description: HTTP API endpoints exposed by Language Operator reactive agents
   :contact:
     :name: Language Operator

data/lib/language_operator/templates/schema/agent_dsl_schema.json

@@ -3,7 +3,7 @@
   "$id": "https://github.com/language-operator/language-operator-gem/schema/agent-dsl.json",
   "title": "Language Operator Agent DSL",
   "description": "Schema for defining autonomous AI agents using the Language Operator DSL",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "type": "object",
   "properties": {
     "name": {

data/lib/language_operator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LanguageOperator
-  VERSION = '0.1.53'
+  VERSION = '0.1.54'
 end

data/synth/002/README.md

@@ -36,16 +36,24 @@ mode :scheduled
 schedule "*/10 * * * *"  # Every 10 minutes
 ```
 
-Validates that agents can run on a schedule using cron syntax:
+Validates that agents can run on a schedule using Kubernetes CronJobs:
 - ✅ **Mode dispatch** - Runtime recognizes `:scheduled` mode
-- ✅ **Cron parsing** - Schedule expression is parsed correctly
-- ✅ **Scheduler integration** - `rufus-scheduler` integration works
-- ✅ **Repeated execution** - Agent runs multiple times automatically
+- ✅ **Cron parsing** - Schedule expression is used by Kubernetes CronJob
+- ✅ **Kubernetes-native** - CronJob creates pods on schedule
+- ✅ **Execute once and exit** - Each pod runs the task once, then terminates
+- ✅ **Repeated execution** - Kubernetes creates new pods per schedule
 
 ### 3. Complete Neural Execution Flow
 ```
 ┌─────────────────────────────────────────────────────────┐
-│  Scheduler Triggers (every 10 minutes)                  │
+│  Kubernetes CronJob Triggers (every 10 minutes)         │
+│  Creates new pod for this execution                     │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│  Pod Starts → Agent Runtime Loads                       │
+│  Mode: scheduled → Execute once and exit                │
 └────────────────────┬────────────────────────────────────┘
                      │
                      ▼
@@ -75,6 +83,12 @@ Validates that agents can run on a schedule using cron syntax:
 ┌─────────────────────────────────────────────────────────┐
 │  Output Block Processes Result                          │
 │  puts outputs[:fortune]                                 │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│  Agent Exits → Pod Terminates                           │
+│  Kubernetes waits for next cron schedule                │
 └─────────────────────────────────────────────────────────┘
 ```
 
@@ -133,100 +147,6 @@ This test proves the foundation for learning:
 
 **The critical insight**: Because `execute_task(:generate_fortune)` works the same whether the task is neural or symbolic, we can replace implementations without breaking the `main` block.
 
-### No Other Framework Can Do This
-
-| Framework | Neural Execution | Symbolic Execution | Transparent Evolution |
-|-----------|-----------------|-------------------|---------------------|
-| **Language Operator** | ✅ Instructions-based tasks | ✅ Code blocks | ✅ Contract abstraction |
-| LangChain | ❌ Chains are static | ✅ Python code | ❌ No abstraction |
-| AutoGen | ✅ Conversational | ❌ No symbolic optimization | ❌ No contracts |
-| CrewAI | ✅ Agents with prompts | ❌ No learning | ❌ No abstraction |
-
-## What It Doesn't Test
-
-This test intentionally **does not** validate:
-- ❌ Learning/re-synthesis (future tests)
-- ❌ MCP tool integration in neural tasks (future tests)
-- ❌ Complex multi-task workflows (future tests)
-- ❌ Error recovery and re-synthesis (future tests)
-- ❌ Hybrid neural-symbolic agents (future tests)
-
-## Success Criteria
-
-✅ **Agent synthesizes with neural task** - Instructions-based task definition works
-✅ **Scheduled mode activates** - Agent runs on cron schedule
-✅ **Neural task executes** - LLM is invoked with instructions
-✅ **Output schema validated** - LLM response matches `{ fortune: 'string' }`
-✅ **Output appears** - Fortune is logged to stdout
-✅ **Repeated execution** - Agent runs multiple times (every 10 minutes)
-
-## Connection to DSL v1 Proposal
-
-From [dsl-v1.md](../requirements/proposals/dsl-v1.md):
-
-> **Critical Property:** The caller cannot tell which implementation is used. The contract is the interface.
-
-This test proves that property works in practice:
-
-**Contract (Stable):**
-```ruby
-task :generate_fortune,
-  inputs: {},
-  outputs: { fortune: 'string' }
-```
-
-**Implementation (Neural - for now):**
-```ruby
-instructions: "Generate a random fortune for the user"
-```
-
-**Caller (Unaware):**
-```ruby
-main do |inputs|
-  fortune_data = execute_task(:generate_fortune)  # Works regardless of implementation
-  { fortune: fortune_data[:fortune] }
-end
-```
-
-The `main` block doesn't know (and doesn't care) whether `:generate_fortune` is neural or symbolic. This is the **organic function abstraction** that enables real-time synthesis and learning.
-
-## Running the Test
-
-```bash
-# Execute the synthesized agent
-ruby synth/002/agent.rb
-
-# Expected behavior:
-# - Agent starts in scheduled mode
-# - Every 10 minutes, generates and prints a fortune
-# - Runs continuously until stopped
-```
-
-## What Success Looks Like
-
-```
-[INFO] Loading agent: test-agent
-[INFO] Mode: scheduled (*/10 * * * *)
-[INFO] Scheduler started
-[INFO] Executing main block (scheduled trigger)
-[INFO] Executing task: generate_fortune (neural)
-[INFO] Calling LLM with instructions: "Generate a random fortune for the user"
-[INFO] LLM returned: {:fortune=>"A journey of a thousand miles begins with a single step."}
-[INFO] Validating output schema: { fortune: 'string' } ✓
-[INFO] Task returned: {:fortune=>"A journey of a thousand miles begins with a single step."}
-[INFO] Processing output
-A journey of a thousand miles begins with a single step.
-[INFO] Agent execution complete, waiting for next schedule
-[INFO] Next run: 2025-11-16 14:20:00
-...
-[INFO] Executing main block (scheduled trigger)
-[INFO] Executing task: generate_fortune (neural)
-[INFO] Calling LLM with instructions: "Generate a random fortune for the user"
-[INFO] LLM returned: {:fortune=>"Fortune favors the bold."}
-[INFO] Validating output schema: { fortune: 'string' } ✓
-Fortune favors the bold.
-```
-
 ## The Organic Function In Action
 
 **What makes this revolutionary:**
@@ -237,51 +157,4 @@ Fortune favors the bold.
 4. **Learning Ready**: After N runs, system can observe patterns and synthesize symbolic implementation
 5. **Zero Breaking Changes**: When re-synthesized, `main` block never changes
 
-**This is what "living code" means**: Code that starts neural (flexible, works immediately) and becomes symbolic (fast, cheap) through observation, all while maintaining a stable contract.
-
----
-
-**Status**: ✅ VALIDATED - Neural organic functions work
-
-**Next**: Test 003+ will validate learning, re-synthesis, and progressive neural→symbolic evolution
-
----
-
-## Technical Deep Dive
-
-### How Neural Execution Works
-
-When `execute_task(:generate_fortune)` is called:
-
-1. **Task Lookup**: Runtime finds task definition in agent
-2. **Type Check**: Task has `instructions`, no code block → Neural execution
-3. **Prompt Construction**:
-   ```
-   You are an AI agent executing a task.
-
-   Task: generate_fortune
-   Instructions: Generate a random fortune for the user
-
-   Inputs: {}
-
-   You must return a response matching this schema:
-   { fortune: 'string' }
-
-   [Available tools if any MCP servers connected]
-   ```
-4. **LLM Invocation**: Send prompt to configured LLM (via `ruby_llm`)
-5. **Response Parsing**: Extract structured output from LLM response
-6. **Schema Validation**: Ensure response matches `{ fortune: 'string' }`
-7. **Return**: Validated output returned to caller
-
-### What This Enables Later
-
-Once this works, the learning system can:
-
-1. **Observe Execution**: Collect OpenTelemetry traces showing what the LLM did
-2. **Detect Patterns**: Analyze if LLM behavior is deterministic
-3. **Synthesize Code**: Generate symbolic implementation from observed pattern
-4. **Re-Deploy**: Update ConfigMap with learned code
-5. **Transparent Evolution**: `main` block continues working identically
-
-**This test proves step 1 works** (neural execution). Future tests prove steps 2-5.
+**This is what "living code" means**: Code that starts neural (flexible, works immediately) and becomes symbolic (fast, cheap) through observation, all while maintaining a stable contract.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: language-operator
 version: !ruby/object:Gem::Version
-  version: 0.1.53
+  version: 0.1.54
 platform: ruby
 authors:
 - James Ryan