add docs
This commit is contained in:
@@ -0,0 +1,190 @@
|
||||
# Requirements
|
||||
|
||||
## 1. Business Context & Success Metrics
|
||||
|
||||
### Business Goal
|
||||
|
||||
The **YiemAgent** project is a Julia reimplementation of the Pi Agent Core framework, designed to provide a stateful agent system for LLM interactions in a wine retail store context. This system enables AI agents to interact with customers, search wine databases, and provide personalized wine recommendations based on customer preferences and store inventory.
|
||||
|
||||
### User Stories
|
||||
|
||||
- **US-001**: As a wine store customer, I want to interact with an AI sommelier so that I can get personalized wine recommendations
|
||||
- **US-002**: As a wine store operator, I want the AI to search our wine database so that I can provide accurate inventory-based recommendations
|
||||
- **US-003**: As a developer, I want a reusable agent framework so that I can quickly build custom AI agents for different use cases
|
||||
- **US-004**: As a system administrator, I want session persistence so that I can maintain conversation history across agent restarts
|
||||
|
||||
### KPIs & Targets
|
||||
|
||||
- **KPI-001**: 95% of customer queries receive responses within 3 seconds (measured from query receipt to response delivery)
|
||||
- **KPI-002**: 99% of wine searches return results from inventory database within 2 seconds
|
||||
- **KPI-003**: Agent session recovery time < 5 seconds after restart
|
||||
- **KPI-004**: Conversation context retention accuracy > 95% across session restarts
|
||||
|
||||
## 2. Technical Boundaries
|
||||
|
||||
### In Scope
|
||||
|
||||
- Low-level agent loop with LLM interaction and tool execution
|
||||
- High-level Agent struct with state management and event streaming
|
||||
- Session persistence with JSONL-based storage
|
||||
- Built-in tools: bash execution, file read/write/edit operations
|
||||
- Conversation history compaction for context window management
|
||||
- Branch-based conversation navigation
|
||||
- Event-driven architecture for monitoring and control
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- LLM model hosting or inference (relies on external services)
|
||||
- Frontend UI components (web interface)
|
||||
- Database schema design or management
|
||||
- User authentication and authorization
|
||||
- Multi-tenant isolation
|
||||
|
||||
### Dependencies
|
||||
|
||||
- Julia 1.9+ runtime
|
||||
- JSON3 for JSON parsing
|
||||
- UUIDs for session identification
|
||||
- Dates for timestamp management
|
||||
- LibPQ for PostgreSQL database connections
|
||||
- MQTT client for external communication
|
||||
|
||||
### Deployment Constraints
|
||||
|
||||
- **NFR-501**: System shall be deployed to containerized environment (Docker/Podman)
|
||||
- **NFR-502**: Agent instances shall support horizontal scaling
|
||||
- **NFR-503**: Session data shall be persisted in shared storage for failover scenarios
|
||||
|
||||
## 3. Functional Requirements (FR)
|
||||
|
||||
### FR-001: Agent State Management
|
||||
|
||||
The system shall maintain conversation state including message history, active tools, and system prompt.
|
||||
|
||||
- Store and retrieve conversation history
|
||||
- Support multiple concurrent agent sessions
|
||||
- Maintain tool state across conversation turns
|
||||
- Persist agent state to storage backend
|
||||
|
||||
**Traceability**: US-001, US-004
|
||||
|
||||
### FR-002: Tool Execution
|
||||
|
||||
The system shall execute tools requested by the LLM in response to user queries.
|
||||
|
||||
- Support parallel and sequential tool execution modes
|
||||
- Handle tool call errors gracefully
|
||||
- Return tool results to LLM for processing
|
||||
- Support tool result streaming for long-running operations
|
||||
|
||||
**Traceability**: US-001
|
||||
|
||||
### FR-003: Session Persistence
|
||||
|
||||
The system shall persist agent sessions to enable recovery after restart.
|
||||
|
||||
- Store session metadata and conversation history in JSONL format
|
||||
- Support session creation, opening, and deletion
|
||||
- Enable session branching for experiment tracking
|
||||
- Support session compaction to reduce storage and context size
|
||||
|
||||
**Traceability**: US-004
|
||||
|
||||
### FR-004: Event Streaming
|
||||
|
||||
The system shall provide real-time event streaming for monitoring agent activity.
|
||||
|
||||
- Emit lifecycle events (agent start/end, turn start/end, message start/end)
|
||||
- Emit tool execution events (start, update, end)
|
||||
- Support event subscription and unsubscription
|
||||
- Enable event-driven workflows
|
||||
|
||||
**Traceability**: US-001
|
||||
|
||||
### FR-005: Conversation Management
|
||||
|
||||
The system shall manage conversation flow with support for steering and follow-up messages.
|
||||
|
||||
- Support sequential conversation turns
|
||||
- Enable message injection after assistant turns (steering)
|
||||
- Support follow-up messages that run after natural termination
|
||||
- Clear message queues on agent reset
|
||||
|
||||
**Traceability**: US-001, US-002
|
||||
|
||||
### FR-006: Wine Database Search
|
||||
|
||||
The system shall provide tools to search wine inventory databases.
|
||||
|
||||
- Execute SQL queries against wine database
|
||||
- Support vector similarity search for recommendations
|
||||
- Cache similar queries in vector database
|
||||
- Handle database connection failures gracefully
|
||||
|
||||
**Traceability**: US-002
|
||||
|
||||
## 4. Non-Functional Requirements (NFRs)
|
||||
|
||||
### 4.1 Performance & Scalability
|
||||
|
||||
- **NFR-101**: System shall process messages with <500ms latency for 95th percentile
|
||||
- **NFR-102**: System shall support at least 100 concurrent agent sessions
|
||||
- **NFR-103**: Tool execution shall complete within 10 seconds for 99% of operations
|
||||
- **NFR-104**: Session compaction shall reduce token count by at least 50% with minimal context loss
|
||||
|
||||
### 4.2 Availability & Reliability
|
||||
|
||||
- **NFR-201**: Agent sessions shall recover from failures within 5 seconds
|
||||
- **NFR-202**: System shall maintain conversation continuity across restarts
|
||||
- **NFR-203**: Message queues shall not lose messages during normal operation
|
||||
- **NFR-204**: Event streaming shall survive temporary subscriber disconnections
|
||||
|
||||
### 4.3 Privacy & Security
|
||||
|
||||
- **Data Classification**: Commercial wine data, customer preferences
|
||||
- **Encryption**: TLS 1.3+ for database connections, encrypted session storage
|
||||
- **Authentication**: Database credential management via environment variables
|
||||
- **Compliance**: GDPR Article 32 (security of processing)
|
||||
|
||||
### 4.4 Observability & Telemetry
|
||||
|
||||
- **Required Logs**: `session_id`, `message_id`, `event_type`, `timestamp`, `latency_ms`, `tool_name`
|
||||
- **Critical Metrics**:
|
||||
- `agent_sessions_active`
|
||||
- `message_processing_latency_seconds`
|
||||
- `tool_execution_errors_total`
|
||||
- `session_recovery_time_seconds`
|
||||
- **Tracing**: B3 propagation for distributed tracing
|
||||
- **Alerting**: `tool_execution_error_rate > 5%` triggers PagerDuty
|
||||
- **Retention**: Logs: 30 days, Metrics: 90 days
|
||||
|
||||
## 5. Acceptance Conditions
|
||||
|
||||
- [ ] **FR-001**: Agent maintains conversation state across multiple turns with correct message ordering
|
||||
- [ ] **FR-002**: Tools execute correctly with proper error handling and result formatting
|
||||
- [ ] **FR-003**: Sessions can be persisted and recovered with complete conversation history
|
||||
- [ ] **FR-004**: All agent lifecycle events are emitted and可 captured by subscribers
|
||||
- [ ] **FR-005**: Steering messages are injected at correct points in conversation flow
|
||||
- [ ] **FR-006**: Wine database search returns results within 2 seconds for 95% of queries
|
||||
- [ ] **NFR-101**: 95% of messages processed within 500ms latency
|
||||
- [ ] **NFR-201**: Agent sessions recover within 5 seconds after simulated failure
|
||||
|
||||
## 6. Requirements Traceability Matrix
|
||||
|
||||
| Requirement ID | Description | Implementation File | Test File |
|
||||
|----------------|-------------|---------------------|-----------|
|
||||
| FR-001 | Agent State Management | `src/agent.jl`, `src/types.jl` | `test/test1.jl` |
|
||||
| FR-002 | Tool Execution | `src/agent_loop.jl`, `src/tools/` | `test/prompttest_*.jl` |
|
||||
| FR-003 | Session Persistence | `src/session/` | `test/chatting_with_agent.jl` |
|
||||
| FR-004 | Event Streaming | `src/agent.jl`, `src/types.jl` | `test/prompttest_*.jl` |
|
||||
| FR-005 | Conversation Management | `src/agent.jl`, `src/agent_loop.jl` | `test/chatting_with_agent.jl` |
|
||||
| FR-006 | Wine Database Search | `example/main.jl`, `example/agent_chat_virtualCustomer.jl` | N/A |
|
||||
| NFR-101 | Performance & Scalability | System-wide | `test/runtests.jl` |
|
||||
| NFR-201 | Availability & Reliability | `src/session/`, `src/agent.jl` | `test/chatting_with_agent.jl` |
|
||||
|
||||
**Notes**:
|
||||
- Functional Requirements (FR) define what the system shall do
|
||||
- Non-Functional Requirements (NFR) define system qualities (performance, availability, security, etc.)
|
||||
- KPIs are measurable targets that validate whether requirements were met post-deployment
|
||||
- Each requirement must include a clear requirement ID for traceability
|
||||
- All acceptance conditions must be verifiable through testing or manual inspection
|
||||
Reference in New Issue
Block a user