# File Output Implementation Plan

## Overview

This plan implements file writing and return functionality for report-writing agents, enabling reports to be saved as files and returned through the Gradio ChatInterface.

## Current State Analysis

✅ **Report Generation**: All agents generate markdown strings  
✅ **File Output Integration**: `event_to_chat_message()` supports file paths  
✅ **Graph Orchestrator**: Can handle file paths in results  
❌ **File Writing**: No agents write files to disk  
❌ **File Service**: No utility service for saving reports  

---

## Implementation Plan

### PROJECT 1: File Writing Service
**Goal**: Create a reusable service for saving reports to files

#### Activity 1.1: Create Report File Service
**File**: `src/services/report_file_service.py` (NEW)

**Tasks**:
1. Create `ReportFileService` class
2. Implement `save_report()` method
   - Accepts: report content (str), filename (optional), output_dir (optional)
   - Returns: file path (str)
   - Uses temp directory by default
   - Supports custom output directory
   - Handles file naming with timestamps
3. Implement `save_report_multiple_formats()` method
   - Save as .md (always)
   - Optionally save as .html, .pdf (future)
4. Add configuration support
   - Read from settings
   - Enable/disable file saving
   - Configurable output directory
5. Add error handling and logging
6. Add file cleanup utilities (optional)

**Line-level subtasks**:
- Line 1-20: Imports and class definition
- Line 21-40: `__init__()` method with settings
- Line 41-80: `save_report()` method
  - Line 41-50: Input validation
  - Line 51-60: Directory creation
  - Line 61-70: File writing
  - Line 71-80: Error handling
- Line 81-100: `save_report_multiple_formats()` method
- Line 101-120: Helper methods (filename generation, cleanup)

---

### PROJECT 2: Configuration Updates
**Goal**: Add settings for file output functionality

#### Activity 2.1: Update Settings Model
**File**: `src/utils/config.py`

**Tasks**:
1. Add `save_reports_to_file: bool` field (default: True)
2. Add `report_output_directory: str | None` field (default: None, uses temp)
3. Add `report_file_format: Literal["md", "md_html", "md_pdf"]` field (default: "md")
4. Add `report_filename_template: str` field (default: "report_{timestamp}_{query_hash}.md")

**Line-level subtasks**:
- Line 166-170: Add `save_reports_to_file` field after TTS config
- Line 171-175: Add `report_output_directory` field
- Line 176-180: Add `report_file_format` field
- Line 181-185: Add `report_filename_template` field

---

### PROJECT 3: Graph Orchestrator Integration
**Goal**: Integrate file writing into graph execution

#### Activity 3.1: Update Graph Orchestrator
**File**: `src/orchestrator/graph_orchestrator.py`

**Tasks**:
1. Import `ReportFileService` at top
2. Initialize service in `__init__()` (optional, can be lazy)
3. Modify `_execute_agent_node()` for synthesizer node
   - After `long_writer_agent.write_report()`, save to file
   - Return dict with `{"message": report, "file": file_path}`
4. Update final event generation to handle file paths
   - Already implemented, verify it works correctly

**Line-level subtasks**:
- Line 1-35: Add import for `ReportFileService`
- Line 119-148: Update `__init__()` to accept optional file service
- Line 589-650: Modify `_execute_agent_node()` synthesizer handling
  - Line 642-645: After `write_report()`, add file saving
  - Line 646-650: Return dict with file path
- Line 534-564: Verify final event generation handles file paths (already done)

---

### PROJECT 4: Research Flow Integration
**Goal**: Integrate file writing into research flows

#### Activity 4.1: Update IterativeResearchFlow
**File**: `src/orchestrator/research_flow.py`

**Tasks**:
1. Import `ReportFileService` at top
2. Add optional file service to `__init__()`
3. Modify `_create_final_report()` method
   - After `writer_agent.write_report()`, save to file if enabled
   - Return string (backward compatible) OR dict with file path

**Line-level subtasks**:
- Line 1-50: Add import for `ReportFileService`
- Line 48-120: Update `__init__()` to accept optional file service
- Line 622-667: Modify `_create_final_report()` method
  - Line 647-652: After `write_report()`, add file saving
  - Line 653-667: Return report string (keep backward compatible for now)

#### Activity 4.2: Update DeepResearchFlow
**File**: `src/orchestrator/research_flow.py`

**Tasks**:
1. Add optional file service to `__init__()` (if not already)
2. Modify `_create_final_report()` method
   - After `long_writer_agent.write_report()` or `proofreader_agent.proofread()`, save to file
   - Return string (backward compatible) OR dict with file path

**Line-level subtasks**:
- Line 670-750: Update `DeepResearchFlow.__init__()` to accept optional file service
- Line 954-1005: Modify `_create_final_report()` method
  - Line 979-983: After `write_report()`, add file saving
  - Line 984-989: After `proofread()`, add file saving
  - Line 990-1005: Return report string (keep backward compatible)

---

### PROJECT 5: Agent Factory Integration
**Goal**: Make file service available to agents if needed

#### Activity 5.1: Update Agent Factory (Optional)
**File**: `src/agent_factory/agents.py`

**Tasks**:
1. Add optional file service parameter to agent creation functions (if needed)
2. Pass file service to agents that need it (currently not needed, agents return strings)

**Line-level subtasks**:
- Not required - agents return strings, file writing happens at orchestrator level

---

### PROJECT 6: Testing & Validation
**Goal**: Ensure file output works end-to-end

#### Activity 6.1: Unit Tests
**File**: `tests/unit/services/test_report_file_service.py` (NEW)

**Tasks**:
1. Test `save_report()` with default settings
2. Test `save_report()` with custom directory
3. Test `save_report()` with custom filename
4. Test error handling (permission errors, disk full, etc.)
5. Test file cleanup

**Line-level subtasks**:
- Line 1-30: Test fixtures and setup
- Line 31-60: Test basic save functionality
- Line 61-90: Test custom directory
- Line 91-120: Test error handling

#### Activity 6.2: Integration Tests
**File**: `tests/integration/test_file_output_integration.py` (NEW)

**Tasks**:
1. Test graph orchestrator with file output
2. Test research flows with file output
3. Test Gradio ChatInterface receives file paths
4. Test file download in Gradio UI

**Line-level subtasks**:
- Line 1-40: Test setup with mock orchestrator
- Line 41-80: Test file generation in graph execution
- Line 81-120: Test file paths in AgentEvent
- Line 121-160: Test Gradio message conversion

---

## Implementation Order

1. **PROJECT 2** (Configuration) - Foundation
2. **PROJECT 1** (File Service) - Core functionality
3. **PROJECT 3** (Graph Orchestrator) - Primary integration point
4. **PROJECT 4** (Research Flows) - Secondary integration points
5. **PROJECT 6** (Testing) - Validation
6. **PROJECT 5** (Agent Factory) - Not needed, skip

---

## File Changes Summary

### New Files
- `src/services/report_file_service.py` - File writing service
- `tests/unit/services/test_report_file_service.py` - Unit tests
- `tests/integration/test_file_output_integration.py` - Integration tests

### Modified Files
- `src/utils/config.py` - Add file output settings
- `src/orchestrator/graph_orchestrator.py` - Add file saving after report generation
- `src/orchestrator/research_flow.py` - Add file saving in both flows

---

## Gradio Integration Notes

According to Gradio ChatInterface documentation:
- File paths in chat message content are automatically converted to download links
- Markdown links like `[Download: filename](file_path)` work
- Files must be accessible from the Gradio server
- Temp files are fine as long as they exist during the session

Current implementation in `event_to_chat_message()` already handles this correctly.

---

## Success Criteria

✅ Reports are saved to files when generated  
✅ File paths are included in AgentEvent data  
✅ File paths appear as download links in Gradio ChatInterface  
✅ File saving is configurable (can be disabled)  
✅ Backward compatible (existing code still works)  
✅ Error handling prevents crashes if file writing fails