Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
100
docs/specs/vtm/conversation-state.md
Normal file
100
docs/specs/vtm/conversation-state.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Conversation State Management Specification
|
||||
|
||||
## Overview
|
||||
|
||||
Conversation state management for multi-turn VTM conversations.
|
||||
|
||||
## State Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"context": {
|
||||
"current_workflow": "bridge_action",
|
||||
"workflow_state": {...},
|
||||
"entities": {
|
||||
"amount": "100",
|
||||
"source_chain": "138",
|
||||
"destination_chain": "1"
|
||||
}
|
||||
},
|
||||
"conversation_history": [
|
||||
{
|
||||
"turn": 1,
|
||||
"user": "I want to bridge tokens",
|
||||
"assistant": "Which chains would you like to bridge between?",
|
||||
"timestamp": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
],
|
||||
"intents": ["bridge_initiation"],
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"updated_at": "2024-01-01T00:05:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Context Preservation
|
||||
|
||||
### Context Types
|
||||
|
||||
**Workflow Context**: Current workflow state
|
||||
**Entity Context**: Extracted entities (amounts, addresses, etc.)
|
||||
**User Context**: User preferences, history
|
||||
**Session Context**: Session metadata
|
||||
|
||||
### Context Updates
|
||||
|
||||
**Triggers**:
|
||||
- User input
|
||||
- Workflow progression
|
||||
- Entity extraction
|
||||
- External events
|
||||
|
||||
## Multi-Turn Conversation Handling
|
||||
|
||||
### Turn Management
|
||||
|
||||
**Track**:
|
||||
- Turn number
|
||||
- User input
|
||||
- Assistant response
|
||||
- Extracted entities
|
||||
- Intent changes
|
||||
|
||||
### Entity Extraction
|
||||
|
||||
**Entities**:
|
||||
- Amounts
|
||||
- Addresses
|
||||
- Chain names/IDs
|
||||
- Token symbols
|
||||
- Dates/times
|
||||
|
||||
### Disambiguation
|
||||
|
||||
**Handling Ambiguity**:
|
||||
- Ask clarifying questions
|
||||
- Suggest options
|
||||
- Use context to infer
|
||||
|
||||
## Session Timeout and Recovery
|
||||
|
||||
### Timeout
|
||||
|
||||
**Duration**: 30 minutes of inactivity
|
||||
**Action**: Save state, end session
|
||||
**Recovery**: Resume from saved state if user returns
|
||||
|
||||
### Recovery
|
||||
|
||||
**Process**:
|
||||
1. User returns within timeout window
|
||||
2. Restore conversation state
|
||||
3. Continue from last turn
|
||||
4. Prompt user to continue
|
||||
|
||||
## References
|
||||
|
||||
- Teller Orchestrator: See `teller-orchestrator.md`
|
||||
- Workflows: See `teller-workflows.md`
|
||||
|
||||
87
docs/specs/vtm/soul-machines-integration.md
Normal file
87
docs/specs/vtm/soul-machines-integration.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# Soul Machines Integration Specification
|
||||
|
||||
## Overview
|
||||
|
||||
Integration with Soul Machines digital humans for Virtual Teller Machine (VTM) experience.
|
||||
|
||||
## Digital Human UI Embedding
|
||||
|
||||
### Web Integration
|
||||
|
||||
**Method**: Embed Soul Machines SDK/widget
|
||||
**Container**: React component or iframe
|
||||
**Positioning**: Modal overlay or side panel
|
||||
|
||||
### Mobile Integration
|
||||
|
||||
**Method**: Native SDK integration
|
||||
**UI**: Full-screen or overlay
|
||||
|
||||
### XR Integration
|
||||
|
||||
**Method**: 3D digital human in XR environment
|
||||
**Platform**: WebXR or native XR app
|
||||
|
||||
## API Integration Points
|
||||
|
||||
### Session Management
|
||||
|
||||
**Endpoints**:
|
||||
- Create session
|
||||
- End session
|
||||
- Get session status
|
||||
|
||||
### Conversation Management
|
||||
|
||||
**Events**:
|
||||
- User message
|
||||
- Digital human response
|
||||
- Intent detection
|
||||
- Workflow triggers
|
||||
|
||||
## Session Management
|
||||
|
||||
### Session Lifecycle
|
||||
|
||||
1. User initiates VTM session
|
||||
2. Create Soul Machines session
|
||||
3. Authenticate user (if required)
|
||||
4. Load user context
|
||||
5. Start conversation
|
||||
6. End session (user or timeout)
|
||||
|
||||
### Session Data
|
||||
|
||||
**Stored**:
|
||||
- Session ID
|
||||
- User ID
|
||||
- Conversation history
|
||||
- Workflow state
|
||||
- Timestamps
|
||||
|
||||
## Conversation State Persistence
|
||||
|
||||
### State Storage
|
||||
|
||||
**Storage**: Database or session store
|
||||
**Retention**: Per session, archive after completion
|
||||
|
||||
### State Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"conversation_history": [...],
|
||||
"workflow_state": {...},
|
||||
"intents": [...],
|
||||
"created_at": "timestamp",
|
||||
"updated_at": "timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- Teller Orchestrator: See `teller-orchestrator.md`
|
||||
- Workflows: See `teller-workflows.md`
|
||||
|
||||
113
docs/specs/vtm/teller-orchestrator.md
Normal file
113
docs/specs/vtm/teller-orchestrator.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Teller Orchestrator Specification
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrator that connects Soul Machines digital humans with backend services and workflows.
|
||||
|
||||
## Workflow Engine Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
DH[Digital Human UI]
|
||||
NLU[Intent/Policy Layer]
|
||||
WF[Workflow Engine]
|
||||
BANK[Banking API]
|
||||
ACT[Action Orchestrator]
|
||||
EXP[Explorer Services]
|
||||
HUM[Human Agent Console]
|
||||
|
||||
DH --> NLU
|
||||
NLU --> WF
|
||||
WF --> BANK
|
||||
WF --> ACT
|
||||
WF --> EXP
|
||||
WF --> HUM
|
||||
```
|
||||
|
||||
## Intent Recognition and Routing
|
||||
|
||||
### Intent Types
|
||||
|
||||
**Banking Intents**:
|
||||
- Account opening
|
||||
- Balance inquiry
|
||||
- Transaction explanation
|
||||
- Limit increase request
|
||||
|
||||
**Explorer Intents**:
|
||||
- Transaction lookup
|
||||
- Address information
|
||||
- Token information
|
||||
|
||||
**Action Intents**:
|
||||
- Bridge initiation
|
||||
- Swap assistance
|
||||
- Wallet setup
|
||||
|
||||
### Intent Recognition
|
||||
|
||||
**Method**: NLU from Soul Machines + custom intent classification
|
||||
**Routing**: Route to appropriate workflow handler
|
||||
|
||||
## Policy Enforcement Layer
|
||||
|
||||
### Policies
|
||||
|
||||
**Role-Based Access**:
|
||||
- Customer permissions
|
||||
- Feature access
|
||||
- Limit enforcement
|
||||
|
||||
**Compliance Policies**:
|
||||
- KYC requirements
|
||||
- Transaction limits
|
||||
- Regulatory restrictions
|
||||
|
||||
### Enforcement
|
||||
|
||||
**Checks**:
|
||||
- Verify user permissions
|
||||
- Check compliance status
|
||||
- Validate limits
|
||||
- Enforce policies
|
||||
|
||||
## Action Authorization
|
||||
|
||||
### Authorization Flow
|
||||
|
||||
1. User requests action via VTM
|
||||
2. Teller orchestrator validates request
|
||||
3. Check user permissions
|
||||
4. Check compliance status
|
||||
5. Request explicit confirmation
|
||||
6. Execute action if authorized
|
||||
|
||||
### Authorization Levels
|
||||
|
||||
**Level 1**: Information queries (no authorization needed)
|
||||
**Level 2**: Read-only actions (view account)
|
||||
**Level 3**: Financial actions (require explicit confirmation)
|
||||
|
||||
## Human Escalation Workflow
|
||||
|
||||
### Escalation Triggers
|
||||
|
||||
**Conditions**:
|
||||
- Complex issues beyond VTM capability
|
||||
- User request for human agent
|
||||
- Compliance concerns
|
||||
- Technical errors
|
||||
|
||||
### Escalation Process
|
||||
|
||||
1. Identify escalation need
|
||||
2. Create support ticket
|
||||
3. Notify human agent
|
||||
4. Transfer conversation context
|
||||
5. Human agent takes over
|
||||
|
||||
## References
|
||||
|
||||
- Soul Machines Integration: See `soul-machines-integration.md`
|
||||
- Workflows: See `teller-workflows.md`
|
||||
|
||||
98
docs/specs/vtm/teller-workflows.md
Normal file
98
docs/specs/vtm/teller-workflows.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Teller Workflows Specification
|
||||
|
||||
## Overview
|
||||
|
||||
Workflow definitions for common VTM teller interactions.
|
||||
|
||||
## Workflow: Account Opening
|
||||
|
||||
**State Machine**:
|
||||
```
|
||||
[Start] → [Identity Verification] → [KYC Check] → [Account Creation] → [Wallet Setup] → [Complete]
|
||||
↓ ↓
|
||||
[Failed] [Manual Review]
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
1. Collect user information
|
||||
2. Initiate identity verification
|
||||
3. Run KYC checks
|
||||
4. Create account if approved
|
||||
5. Set up wallet
|
||||
6. Complete onboarding
|
||||
|
||||
## Workflow: Bridge Action
|
||||
|
||||
**State Machine**:
|
||||
```
|
||||
[Start] → [Select Chains] → [Enter Amount] → [Risk Check] → [Confirmation] → [Execute] → [Monitor] → [Complete]
|
||||
↓
|
||||
[Failed]
|
||||
```
|
||||
|
||||
**Steps**:
|
||||
1. User requests bridge
|
||||
2. Select source and destination chains
|
||||
3. Enter amount
|
||||
4. Get quote and show details
|
||||
5. Risk assessment
|
||||
6. User confirmation
|
||||
7. Execute bridge
|
||||
8. Monitor status
|
||||
9. Confirm completion
|
||||
|
||||
## Workflow: Transaction Explanation
|
||||
|
||||
**Steps**:
|
||||
1. User provides transaction hash
|
||||
2. Fetch transaction details
|
||||
3. Explain transaction components
|
||||
4. Answer user questions
|
||||
5. Provide additional context if needed
|
||||
|
||||
## User Consent Checkpoints
|
||||
|
||||
### Checkpoint Types
|
||||
|
||||
**Implicit Consent**: Information queries
|
||||
**Explicit Consent**: Financial actions
|
||||
**Strong Consent**: High-value or high-risk actions
|
||||
|
||||
### Consent Recording
|
||||
|
||||
**Record**:
|
||||
- Action requested
|
||||
- User acknowledgment
|
||||
- Timestamp
|
||||
- Method (voice, text, button)
|
||||
|
||||
## Audit Logging Requirements
|
||||
|
||||
### Logged Events
|
||||
|
||||
**All Events**:
|
||||
- Workflow start/completion
|
||||
- User inputs
|
||||
- System actions
|
||||
- Authorizations
|
||||
- Escalations
|
||||
- Errors
|
||||
|
||||
### Log Format
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"workflow": "bridge_action",
|
||||
"event": "user_confirmation",
|
||||
"data": {...},
|
||||
"timestamp": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- Teller Orchestrator: See `teller-orchestrator.md`
|
||||
- Conversation State: See `conversation-state.md`
|
||||
|
||||
Reference in New Issue
Block a user