---
auto_generated: true
created: 2026-05-19
manual_updated_at: 2026-05-19
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- domain/ai
- status/active
- tech/docker
- tech/openai
- tech/python
- tech/rag
- type/sop
type: sop
---

# RAG Test App Developer Manual

## Architecture Overview
The application follows a modular architecture:
- **CLI Layer**: Handles argument parsing and user interaction
- **Core Logic**: RAGTester class manages testing workflows
- **Testing**: Pytest suite for component validation
- **Output**: Rich console formatting and JSON/CSV results

## Tech Stack
- Python 3.8+
- OpenAI Python SDK
- Pandas & NumPy for data analysis
- Rich for console formatting
- Matplotlib for visualizations
- Pytest for testing

## Local Setup

### Prerequisites
- Python 3.8+
- OpenAI API key
- pip package manager

### Installation
```bash
# Clone repository
git clone https://github.com/yourusername/rag-test-app.git
cd rag-test-app

# Install dependencies
pip install -e .
```

## Environment Variables
Required:
- `OPENAI_API_KEY`: Your OpenAI API key (can also be passed via CLI)

Optional:
- `CONFIG_PATH`: Default configuration file path
- `OUTPUT_DIR`: Default output directory

## Key Services & Entry Points

### Main Entry Point
```python
# cli.py
if __name__ == "__main__":
    main()
```

### Core Classes
```python
# main.py
from openai import OpenAI

class RAGTester:
    def __init__(self, api_key, assistant_id, ...):
        self.client = OpenAI(api_key=api_key)
        self.document_content = self._load_documents()
        
    def run_test(self):
        """Execute RAG testing workflow"""
        questions = self._generate_questions()
        results = self._evaluate_responses(questions)
        return self._generate_report(results)
```

### Configuration Structure
```json
{
  "api_key": "sk-xxxxx",
  "assistant_id": "asst_xxxxx",
  "document": "path/to/doc.pdf",
  "num_questions": 20,
  "iterations": 3,
  "model": "gpt-4o",
  "prompt_type": "task-based"
}
```

## API Reference

### CLI Arguments
| Argument | Description | Default |
|----------|-------------|---------|
| --config | Config file path | None |
| --api-key | OpenAI API key | env var |
| --assistant-id | Assistant ID | Required |
| --document | Document path | Required |
| --output-dir | Results directory | results |
| --num-questions | Number of questions | 20 |
| --model | OpenAI model | gpt-4o |
| --prompt-type | Question generation type | task-based |
| --parallel | Parallel workers | 5 |
| --verbose | Enable verbose output | False |

### Core Methods
- `RAGTester.__init__()`: Initialize tester
- `RAGTester._load_documents()`: Load document content
- `RAGTester._generate_questions()`: Create test questions
- `RAGTester._evaluate_responses()`: Test assistant responses
- `RAGTester._generate_report()`: Create results report

## Deployment

### Docker Support
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
ENTRYPOINT ["rag-test"]
```

### Production Config
```json
{
  "parallel": 10,
  "batch_size": 5,
  "output_dir": "/data/results",
  "verbose": false
}
```

## Known Gotchas
1. **Document Loading**
   - DOCX files require `docx2txt` package
   - Large PDFs may consume significant memory
   - Text encoding issues may occur with special characters

2. **API Limits**
   - Rate limiting may occur with high parallel workers
   - Token limits in document processing
   - Assistant context window constraints

3. **Performance**
   - Parallel processing can cause resource contention
   - Large document sets impact processing time
   - Model selection affects speed/accuracy tradeoff

4. **Testing**
   - Mock OpenAI client in tests
   - Use temporary directories for test artifacts
   - Clear result directories between runs

## Testing
```bash
# Run tests
pytest

# Run with coverage
pytest --cov=rag_test_app

# Specific test file
pytest tests/test_main.py
```

## Related

- [[01 Projects/barclays-rag-report/USER_MANUAL]]
- [[01 Projects/barclays-rag-report/DEVELOPER_MANUAL.md]]
- [[01 Projects/barclays-rag-report/USER_MANUAL.md]]