YiemAgent/docs/requirements.md

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