diff --git a/docs/stories/1.4.agentic-iteration-loop-limits.md b/docs/stories/1.4.agentic-iteration-loop-limits.md new file mode 100644 index 0000000..12bb55c --- /dev/null +++ b/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) | \ No newline at end of file