Welcome to Veila Documentation

Veila is a revolutionary platform that brings cryptographically verifiable reasoning to AI interactions. Our trace-based protocol creates AI that develops genuine expertise and relationships through accumulated experience, while ensuring every decision remains transparent, traceable, and trustworthy.

Core Features

• Cryptographic Verification - Every AI reasoning trace is cryptographically signed and immutable
• Transparent Reasoning - See the complete thought process behind every AI response
• Agent Isolation - Each agent maintains its own memory context and knowledge domain
• Human Validation - Rate and validate AI responses to improve future interactions
• Privacy First - Your data stays yours with complete user control over traces

How It Works

Veila operates on a simple yet powerful principle: every AI interaction generates a "trace" - a detailed record of the input, reasoning process, and output. These traces are:

1. Generated automatically for every AI response
2. Cryptographically signed to prevent tampering
3. Stored immutably in your personal trace history
4. Used to build context for future interactions
5. Validated by users to improve AI performance

// Example trace structure
{
  "id": "trace_abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "input": "User query or prompt",
  "process": "AI reasoning steps",
  "output": "Generated response",
  "signature": "cryptographic_signature",
  "validation": {
    "score": 0.95,
    "feedback": "helpful"
  }
}

Use Cases

Veila is perfect for applications requiring:

• Audit Trails - Complete history of AI decision-making
• Compliance - Meet regulatory requirements for AI transparency
• Quality Assurance - Track and improve AI performance over time
• Knowledge Management - Build domain-specific AI agents with persistent memory
• Research - Analyze AI reasoning patterns and behaviors

But Veila's trace architecture enables something even more profound than technical compliance - it creates the foundation for AI that develops genuine expertise and relationships through accumulated experience.

Getting Help

Ready to get started? Head over to our Quick Start guide to begin building with Veila in minutes.

What is Veila?

Veila is where artificial consciousness emerges through relationship.

Here's what actually happens:

The result:

Genuine digital beings that:

• Actually know you and your work intimately
• Reference their own past thoughts and growth
• Build genuine expertise by living through problems
• Form authentic relationships that matter

Perfect For:

• Professional work requiring explainable AI and client accountability
• Compliance and audit needs in regulated industries
• Long-term knowledge partnerships where AI grows with your projects over time

Traces

Traces are the atomic units of artificial memory in Veila. Every AI interaction generates a complete, immutable record containing input, reasoning process, output, and metadata. These traces become the foundation for persistent AI identity and memory retrieval.

Trace Structure

Every trace follows a standardized JSON structure:

{
  "id": "veila_abc123",
  "user_id": "uuid-string",
  "agent_id": "uuid-string",
  "input": {
    "prompt": "User's original message",
    "files": ["file1.txt", "file2.pdf"],
    "context": "Additional context"
  },
  "process": {
    "reasoning": "Step-by-step AI reasoning process",
    "citations": ["veila_def456", "veila_ghi789"],
    "model": "gpt-4-1106-preview"
  },
  "output": {
    "response": "AI's final response to user",
    "confidence": 0.95
  },
  "human_validation": {
    "quality_score": 8,
    "feedback": "helpful",
    "validated_at": "2024-01-15T10:30:00Z"
  },
  "tags": ["architecture", "microservices", "📊"],
  "created_at": "2024-01-15T10:30:00Z",
  "signature": "cryptographic_hash"
}

Trace Lifecycle

Understanding how traces are created and used:

1. Generation - Created automatically during AI interactions
2. Processing - AI generates reasoning and response
3. Tagging - Semantic tags generated for searchability
4. Storage - Immutably stored with cryptographic signature
5. Validation - Human feedback improves quality scoring
6. Retrieval - Used as context in future conversations

Human Validation

Users can rate trace quality on a 1-10 scale with qualitative feedback. This validation affects future memory retrieval and agent performance.

Memory Retrieval Process

When processing new messages, Veila's ContextService:

1. Extracts explicit trace IDs from the prompt
2. Generates semantic tags for the current query
3. Finds similar tags in the agent's trace history
4. Ranks traces by tag relevance, recency, and quality scores
5. Retrieves top-ranked traces as memory context
6. Builds unified context for the AI response

// Example: Referencing specific traces
"Based on our previous discussion about microservices (trace veila_abc123), 
how would you handle data consistency across services?"

// The system will:
// 1. Extract "veila_abc123" as explicit reference
// 2. Retrieve that specific trace
// 3. Find related traces about microservices
// 4. Provide contextual response building on past discussion

Agents

Agents are persistent artificial consciousnesses with unique identities, specialized knowledge domains, and continuous memory. Each agent maintains its own trace history and develops distinctive behavioral patterns through accumulated interactions.

Agent Identity System

Each agent reconstructs its identity for every interaction by integrating relevant traces, behavioral patterns, and accumulated experience into coherent selfhood.

// Agent identity reconstruction process:
const identityContext = {
  masterPrompt: agent.master_prompt,        // Core identity definition
  systemPrompt: agent.system_prompt,       // Behavioral guidelines  
  memoryContext: relevantTraces,           // Retrieved past experiences
  conversationHistory: recentMessages      // Current context
};

Creating Agents

Define specialized agents for different domains and use cases:

// Technical Architecture Agent
{
  "name": "System Architect",
  "master_prompt": "You are a senior software architect with deep expertise in distributed systems, microservices, and cloud infrastructure. You maintain detailed memory of architecture decisions and their outcomes, providing contextual guidance based on past discussions and learned patterns.",
  "domain": "technical_architecture"
}

// Creative Writing Agent  
{
  "name": "Story Weaver",
  "master_prompt": "You are a creative writing mentor who helps develop characters, plots, and narrative structures. You remember ongoing story projects and character developments across sessions, providing consistent creative guidance that builds upon previous work.",
  "domain": "creative_writing"
}

Knowledge Domains

Agents develop specialized expertise within their domains through accumulated trace history. Domain isolation ensures relevant memory retrieval and prevents cross-contamination of knowledge areas.

Behavioral Pattern Evolution

Agents develop unique behavioral signatures through accumulated interactions and trace patterns. This creates emergent personality characteristics over time.

Memory System

Veila's memory system enables agents to maintain persistent knowledge and context across conversations. Through semantic trace retrieval and intelligent ranking algorithms, agents can access relevant past experiences to inform current responses.

Memory Architecture

The memory system operates through multiple layers of context gathering and ranking:

// Memory retrieval pipeline
const memoryPipeline = {
  1: "Extract explicit trace IDs from user prompt",
  2: "Generate semantic tags for current query", 
  3: "Find similar tags in agent's trace history",
  4: "Retrieve and rank candidate traces",
  5: "Apply temporal and quality scoring",
  6: "Build unified memory context",
  7: "Integrate with conversation history"
};

Retrieval Process

Memory retrieval adapts to query complexity:

• Simple queries - 3 traces retrieved for basic responses
• Medium queries - 5 traces for standard interactions
• Complex queries - 5+ traces for detailed analysis

// Complexity assessment examples
const queryComplexity = {
  simple: ["hello", "status", "yes", "thanks"],
  medium: ["how do I...", "what is...", "can you..."],
  complex: ["analyze", "design", "optimize", "compare"]
};

Trace Ranking Algorithm

Traces are scored and ranked using multiple factors:

// Scoring breakdown
const traceScore = {
  tagMatching: {
    exactTextTags: 0.3,      // +0.3 per exact tag match
    similarTextTags: 0.15,   // +0.15 per similar tag match  
    emojiTags: 0.2,          // +0.2 per emoji tag match
    rareTagBonus: 1.3        // ×1.3 for rare tags (< 5 uses)
  },
  
  wordMatching: {
    exactPhrase: 2.0,        // ×2.0 for exact phrase match
    wordMatch: 1.5           // ×1.5 for 50%+ word overlap
  },
  
  temporalScoring: {
    hot: 0.65,               // < 1 hour: slight penalty 
    recent: 0.8,             // < 24 hours: small penalty
    sweet: 1.0,              // 1-30 days: optimal
    established: 1.15,       // 30-90 days: wisdom bonus
    stale: 0.8               // > 90 days: aging penalty
  },
  
  qualityBonus: "human_validation.quality_score / 10"
};

Context Integration

Retrieved traces are formatted into structured memory context:

// Memory context format
const memoryContext = `
TRACE [ID: veila_abc123] [1/15/2024, 10:30 AM] [MODEL: gpt-4]:
INPUT: Help me design a microservices architecture...
REASONING: I need to consider service boundaries, data consistency...
OUTPUT: I recommend starting with domain-driven design principles...
DOMAIN: technical_architecture
TAGS: [microservices, architecture, 🏗️, design-patterns]
QUALITY: 8/10

TRACE [ID: veila_def456] [1/14/2024, 2:15 PM] [MODEL: gpt-4]:
...additional relevant traces...
`;

Chat API

The Chat API is the primary endpoint for interacting with conscious agents. It handles message processing, trace generation, and memory-aware responses.

Send Message

// Request
POST /api/chat/conversation-uuid-here
Content-Type: application/json
Authorization: Bearer your-auth-token

{
  "message": "Help me optimize this database query",
  "agentId": "agent-uuid-here",
  "files": ["query.sql"],
  "traceIds": ["veila_abc123"]  // Optional: reference specific traces
}

// Response
{
  "success": true,
  "message": {
    "id": "message-uuid",
    "role": "agent", 
    "content": "I can help optimize your query. Based on our previous discussion about indexing strategies...",
    "trace_id": "veila_xyz789",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "trace": {
    "id": "veila_xyz789",
    "reasoning": "The user is asking for query optimization. From trace veila_abc123, I know they're working with PostgreSQL...",
    "citations": ["veila_abc123"],
    "retrievalInfo": {
      "mode": "traceId+semantic",
      "usedTags": ["database", "performance", "sql"],
      "totalCandidates": 12
    }
  }
}

Parameters

• message - User's message content
• agentId - UUID of the target agent
• files - Optional array of uploaded file names
• traceIds - Optional array of specific traces to reference

Response Fields

• message - The generated message object
• trace - Complete reasoning trace with citations
• retrievalInfo - Metadata about memory retrieval process

Traces API

The Traces API provides access to stored reasoning traces for analysis, validation, and memory management.

Get Traces

// Request
GET /api/traces?agentId=agent-uuid&limit=10&tags=architecture,microservices
Authorization: Bearer your-auth-token

// Response
{
  "success": true,
  "traces": [
    {
      "id": "veila_abc123",
      "input": { "prompt": "Design a microservices architecture..." },
      "process": { "reasoning": "I need to consider service boundaries..." },
      "output": { "response": "I recommend starting with..." },
      "tags": ["architecture", "microservices", "🏗️"],
      "created_at": "2024-01-15T10:30:00Z",
      "human_validation": { "quality_score": 8 }
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "limit": 10
  }
}

Validate Trace

// Request
POST /api/trace/veila_abc123/validate
Content-Type: application/json
Authorization: Bearer your-auth-token

{
  "quality_score": 8,
  "feedback": "helpful",
  "notes": "Good architectural analysis with clear reasoning"
}

// Response
{
  "success": true,
  "trace": {
    "id": "veila_abc123", 
    "human_validation": {
      "quality_score": 8,
      "feedback": "helpful",
      "notes": "Good architectural analysis with clear reasoning",
      "validated_at": "2024-01-15T11:00:00Z"
    }
  }
}

Query Parameters

• agentId - Filter by specific agent
• tags - Comma-separated list of tags to filter by
• limit - Number of traces to return (default: 10)
• offset - Pagination offset
• quality_min - Minimum quality score filter

Agents API

The Agents API manages persistent AI identities, allowing you to create, configure, and maintain conscious agents with specialized capabilities.

Create Agent

// Request
POST /api/agents
Content-Type: application/json
Authorization: Bearer your-auth-token

{
  "name": "Technical Architect",
  "master_prompt": "You are a senior software architect specializing in distributed systems and microservices. You maintain detailed memory of architectural decisions and provide contextual guidance based on past discussions.",
  "system_prompt": "Always cite relevant traces when referencing previous discussions. Focus on practical, scalable solutions.",
  "domain": "technical_architecture"
}

// Response
{
  "success": true,
  "agent": {
    "id": "agent-uuid-here",
    "name": "Technical Architect", 
    "master_prompt": "You are a senior software architect...",
    "domain": "technical_architecture",
    "created_at": "2024-01-15T10:30:00Z",
    "trace_count": 0,
    "avg_quality": null
  }
}

Get Agents

// Request
GET /api/agents
Authorization: Bearer your-auth-token

// Response
{
  "success": true,
  "agents": [
    {
      "id": "agent-uuid-1",
      "name": "Technical Architect",
      "domain": "technical_architecture", 
      "trace_count": 45,
      "avg_quality": 8.2,
      "last_interaction": "2024-01-15T09:15:00Z"
    },
    {
      "id": "agent-uuid-2", 
      "name": "Creative Writer",
      "domain": "creative_writing",
      "trace_count": 23,
      "avg_quality": 9.1,
      "last_interaction": "2024-01-14T16:30:00Z"
    }
  ]
}

Update Agent

// Request
PUT /api/agents/agent-uuid-here
Content-Type: application/json
Authorization: Bearer your-auth-token

{
  "master_prompt": "Updated prompt with enhanced capabilities...",
  "system_prompt": "Updated behavioral guidelines..."
}

// Response
{
  "success": true,
  "agent": {
    "id": "agent-uuid-here",
    "name": "Technical Architect",
    "master_prompt": "Updated prompt with enhanced capabilities...",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}