Story 1.4: Agentic Iteration Loop & Limits

docs/stories/1.4.agentic-iteration-loop-limits.md

@@ -0,0 +1,133 @@
+# Story 1.4: Agentic Iteration Loop & Limits
+
+## Status
+✅ **Approved**
+
+## Story
+**As a** Rails Developer,
+**I want** to implement an agentic execution loop that allows agents to think through multiple reasoning iterations before returning a final result,
+**so that** I can enable multi-step reasoning capabilities while using max_iterations as a safety constraint to prevent infinite loops.
+
+## Acceptance Criteria
+1. Agent#execute method implements an iterative reasoning loop instead of single prompt-response
+2. Agent can "think" by conversing with itself across multiple iterations within a single execution
+3. Agent maintains conversation context and builds upon previous reasoning steps
+4. Agent returns final result before reaching max_iterations limit through self-awareness
+5. Each iteration increments interaction_count and updates last_interaction_at
+6. Agent can determine when task is complete and exit loop early
+7. Final execution result contains the agent's conclusion after iterative reasoning
+8. Loop gracefully handles max_iterations limit as a safety constraint
+9. Backward compatibility maintained for simple single-step use cases
+
+## Tasks / Subtasks
+
+- [ ] Implement agentic reasoning loop in Agent#execute method (AC: 1, 2, 3, 4, 6, 7, 9)
+  - [ ] Transform single prompt-response into iterative reasoning loop
+  - [ ] Implement conversation continuity using RubyLLM chat interface
+  - [ ] Add iteration-aware prompt templates for self-reasoning
+  - [ ] Implement task completion detection logic
+  - [ ] Add max_iterations awareness to prevent hitting limit
+  - [ ] Maintain backward compatibility for simple executions
+- [ ] Enhance execution tracking for multi-step reasoning (AC: 5, 8)
+  - [ ] Track each reasoning iteration with interaction_count
+  - [ ] Update last_interaction_at for each iteration
+  - [ ] Add basic iteration metadata
+- [ ] Add iteration loop control logic (AC: 4, 6, 8)
+  - [ ] Implement early termination when task is completed
+  - [ ] Add max_iterations safety constraint handling
+  - [ ] Implement reasoning step evaluation
+  - [ ] Add iteration limit warning system
+- [ ] Add comprehensive testing for agentic loop (AC: 1-9)
+  - [ ] Test multi-step reasoning functionality
+  - [ ] Test conversation continuity across iterations
+  - [ ] Test early termination scenarios
+  - [ ] Test max_iterations constraint behavior
+  - [ ] Test iteration tracking
+  - [ ] Test backward compatibility with single-step execution
+
+## Dev Notes
+
+**Development Decisions:**
+
+**Reasoning Pattern:** Continuous thought process (not question-answer exchanges)
+- Each iteration builds naturally upon previous reasoning
+- Agent uses phrases like "Let me think about...", "Building on that...", "Therefore..."
+- More natural flow mimics human problem-solving approach
+- No artificial question-answer overhead
+
+**Task Completion Detection:** Explicit completion markers with parsing
+- Agent must explicitly state completion using "TASK_COMPLETE: [final answer]" format
+- Ruby code extracts final answer from LLM response after detecting completion marker
+- Wrapper around existing ERB templates provides agentic reasoning instructions
+
+**Iteration Tracking:** Count all LLM calls (Option B)
+- Increment interaction_count for every LLM interaction regardless of content quality
+- Update last_interaction_at for each iteration
+- Simple and predictable tracking approach
+
+**Max Iterations Safety:** Meta-instruction injection for final iteration
+- When approaching max_iterations limit, inject additional instructions in system prompt/user message
+- Final iteration warning: "IMPORTANT: This is iteration X of X maximum. You MUST provide your final answer with TASK_COMPLETE: [answer] in this response."
+- Ensures agent gets fair warning to conclude reasoning and synthesize all previous iterations
+- Prevents abrupt termination and guarantees conclusive answer
+
+**Previous Story Insights:**
+- Single agent execution API completed in Story 1.3 with synchronous execution and RubyLLM integration
+- RubyLLM chat interface supports conversation continuity for multi-step conversations [Source: architecture/ruby_llm.md#Chat Interface Pattern]
+- Execution tracking system has interaction_count and last_interaction_at fields ready for iteration tracking
+- Agent model has max_iterations field (default: 5) already implemented for safety constraints
+- Template system supports @agent instance access for iteration-specific prompts
+
+**Data Models:**
+- **Catalyst::Agent**: Has max_iterations field (integer, default: 5, null: false) for safety constraint [Source: architecture/data-model.md#Primary Models]
+- **Catalyst::Execution**: Has interaction_count and last_interaction_at fields for tracking reasoning iterations [Source: architecture/data-model.md#Execution Tracking]
+- **RubyLLM Chat**: Maintains conversation context across multiple interactions [Source: architecture/ruby_llm.md#Chat Interface Pattern]
+
+**API Specifications:**
+- **Agent#execute method**: Transform from single prompt-response to iterative reasoning loop
+- **Reasoning loop**: Agent converses with itself to think through problems step-by-step
+- **Iteration tracking**: Each reasoning step increments interaction_count
+- **Task completion**: Agent determines when final result is ready
+- **Safety constraint**: max_iterations prevents infinite loops
+- **Final result**: Agent returns conclusion after iterative reasoning
+
+**Component Specifications:**
+- **Reasoning loop logic**: Implement within existing Agent#execute method structure [Source: architecture/execution-flow.md#Execution Flow Implementation]
+- **Conversation continuity**: Use RubyLLM chat interface for multi-step reasoning [Source: architecture/ruby_llm.md#Chat Interface Pattern]
+- **Iteration prompts**: Create iteration-aware ERB templates for self-reasoning
+- **Execution tracking**: Leverage existing interaction_count and last_interaction_at fields [Source: architecture/data-model.md#Interaction Tracking]
+- **Safety constraints**: Use max_iterations as upper bound for reasoning loop
+- **Error handling**: Maintain existing sanitization and status transition framework [Source: architecture/execution-flow.md#Error Handling and Security]
+
+**File Locations:**
+- Agent model: `/app/models/catalyst/agent.rb` - transform execute method into reasoning loop
+- Execution model: `/app/models/catalyst/execution.rb` - enhance iteration tracking
+- Prompt templates: `/app/ai/prompts/*.md.erb` - add iteration-aware templates
+- Test files: `/test/models/catalyst/agent_test.rb` - add agentic loop tests
+
+**Technical Constraints:**
+- Ruby on Rails 8 mountable engine architecture
+- RubyLLM ~> 1.3 for LLM integration with chat continuity
+- SQLite compatibility with JSON serialization for iteration metadata
+- Minitest framework for testing multi-step reasoning scenarios
+- Maintain synchronous execution pattern established in Story 1.3
+- max_iterations validation: greater_than: 0 already implemented
+
+### Testing
+- Test file locations: `/test/models/catalyst/agent_test.rb`
+- Test standards: Follow Rails testing conventions with fixtures and mocking
+- Testing frameworks: Rails minitest framework with RubyLLM.test_mode!
+- Specific requirements:
+  - Test agentic reasoning loop with multiple iterations
+  - Test conversation continuity across reasoning steps
+  - Test early termination when task is completed
+  - Test max_iterations safety constraint behavior
+  - Test interaction_count increments with each reasoning iteration
+  - Test backward compatibility with single-step execution
+  - Use RubyLLM.test_mode! for mocking multi-step conversations
+
+## Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-07-11 | 1.0 | Initial story creation for Epic 1.4 - Agentic Iteration Loop with max_iterations constraint | Bob (SM) |
+| 2025-07-11 | 1.1 | Marked as Approved and ready for development implementation | Bob (SM) |