6143abc83b
- Add contributing guidelines to README - Add detailed architecture documentation - Add text analysis task documentation - Include usage examples and best practices
156 lines
3.1 KiB
Markdown
156 lines
3.1 KiB
Markdown
# Architecture Overview
|
|
|
|
## Core Components
|
|
|
|
### TaskExecutor
|
|
|
|
The `TaskExecutor` is the base class for all task implementations. It provides:
|
|
|
|
1. **Task Step Management**
|
|
- Sequential step execution
|
|
- State tracking
|
|
- Checkpoint creation
|
|
- Error handling
|
|
|
|
2. **LLM Integration**
|
|
- Asynchronous API calls
|
|
- Retry mechanisms
|
|
- Response validation
|
|
|
|
### Configuration System
|
|
|
|
1. **Config Loader**
|
|
- YAML configuration files
|
|
- Environment variable support
|
|
- Configuration validation
|
|
|
|
2. **Secure Configuration**
|
|
- Encrypted storage for sensitive data
|
|
- Key management
|
|
- Secure API key handling
|
|
|
|
## Task Implementation
|
|
|
|
### Step Definition
|
|
|
|
Each task is defined as a series of steps:
|
|
|
|
```python
|
|
self.task_steps = [
|
|
{
|
|
"id": "step_id",
|
|
"name": "Step Name",
|
|
"required_info": ["required_data"],
|
|
"instruction": "Step instruction for LLM"
|
|
}
|
|
]
|
|
```
|
|
|
|
### Step Handlers
|
|
|
|
Step handlers are implemented as async methods:
|
|
|
|
```python
|
|
async def handle_step_id(self, step_input: dict) -> dict:
|
|
# 1. Process input
|
|
processed_data = self.preprocess(step_input)
|
|
|
|
# 2. Call LLM if needed
|
|
llm_response = await self.llm_call(
|
|
instruction=step_input["instruction"],
|
|
context=processed_data
|
|
)
|
|
|
|
# 3. Process response
|
|
result = self.postprocess(llm_response)
|
|
|
|
return {"result": result}
|
|
```
|
|
|
|
## Execution Flow
|
|
|
|
1. **Initialization**
|
|
```python
|
|
executor = TaskExecutor(llm_model="model_name")
|
|
```
|
|
|
|
2. **Task Setup**
|
|
```python
|
|
executor.task_steps = [...]
|
|
```
|
|
|
|
3. **Execution**
|
|
```python
|
|
result = await executor.execute(input_data)
|
|
```
|
|
|
|
4. **Step Processing**
|
|
- Validate input
|
|
- Execute step handler
|
|
- Create checkpoint
|
|
- Handle errors
|
|
- Move to next step
|
|
|
|
5. **Completion**
|
|
- Return final result
|
|
- Clean up resources
|
|
|
|
## Error Handling
|
|
|
|
1. **Retry Mechanism**
|
|
- API call retries with exponential backoff
|
|
- Configurable retry limits
|
|
|
|
2. **Error Types**
|
|
- `TaskExecutionError`: General execution errors
|
|
- `StepValidationError`: Input validation failures
|
|
- `LLMError`: LLM API related errors
|
|
|
|
3. **Recovery**
|
|
- Checkpoint-based recovery
|
|
- State restoration
|
|
- Partial results handling
|
|
|
|
## Best Practices
|
|
|
|
1. **Task Design**
|
|
- Keep steps atomic and focused
|
|
- Clear step instructions
|
|
- Proper input validation
|
|
- Comprehensive error handling
|
|
|
|
2. **LLM Usage**
|
|
- Clear and specific prompts
|
|
- Response validation
|
|
- Handle token limits
|
|
- Consider cost and latency
|
|
|
|
3. **Testing**
|
|
- Unit tests for each step
|
|
- Integration tests for full flow
|
|
- Mock LLM calls in tests
|
|
- Test error scenarios
|
|
|
|
4. **Security**
|
|
- Secure API key handling
|
|
- Input sanitization
|
|
- Output validation
|
|
- Access control
|
|
|
|
## Extension Points
|
|
|
|
1. **Custom Step Handlers**
|
|
- Implement custom logic
|
|
- Add new capabilities
|
|
- Integrate external services
|
|
|
|
2. **LLM Providers**
|
|
- Support multiple providers
|
|
- Custom response parsing
|
|
- Provider-specific optimizations
|
|
|
|
3. **Monitoring & Logging**
|
|
- Custom metrics
|
|
- Logging handlers
|
|
- Performance monitoring
|