# 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