Data Flow & Request Patterns

Overview

This page documents the data flow patterns and request/response sequences in Pricing Intelligence, showing how different components interact to process user queries.

Core Data Flow Patterns

1. Simple Query Flow

The most basic interaction: user asks a question about a known pricing URL.

User Query

User submits natural language question via frontend

Planning Phase

Harvey uses LLM to generate structured execution plan

Data Extraction

MCP calls A-MINT to extract pricing YAML from URL

Constraint Solving

Analysis API converts YAML to CSP and finds optimal configuration

Answer Synthesis

Harvey generates natural language answer from tool results

Detailed Flow Scenarios

Scenario A: First-Time URL Analysis

User asks about a pricing URL that hasn’t been cached.

{
  "message": "What plans does HubSpot offer?",
  "pricing_urls": ["https://hubspot.com/pricing"]
}

Flow Diagram

Key Points:

Cache Miss: First request triggers full extraction pipeline
A-MINT Processing: ~5-10 seconds for LLM extraction
Caching: YAML cached for 1 hour to avoid re-extraction
Summary Calculation: Fast in-memory statistics (~100ms)

Scenario B: Cached URL with Filters

User asks about a previously analyzed URL with specific requirements.

{
  "message": "Show me HubSpot plans under $100 with API access",
  "pricing_urls": ["https://hubspot.com/pricing"]
}

Flow Diagram

Performance:

Cache Hit: YAML retrieval ~1ms
DZN Conversion: ~200ms
MiniZinc Solving: ~500ms for small models
Total Time: ~700ms (vs 5-10s without cache)

Scenario C: Optimization Query

Finding the cheapest or most expensive plan.

{
  "message": "What's the cheapest Buffer plan with 10 channels and analytics?",
  "pricing_urls": ["https://buffer.com/pricing"]
}

Flow Diagram

Optimization Details:

Constraint Variables: Plan selection, add-on selections
Objective Function: minimize(plan_cost + sum(addon_costs))
Constraints: Feature requirements, usage limit thresholds
Solver: MiniZinc with Chuffed backend (default)

Scenario D: Multi-Pricing Comparison

Comparing pricing models across different SaaS providers.

{
  "message": "Compare the cheapest plans with SSO between HubSpot and Salesforce",
  "pricing_urls": [
    "https://hubspot.com/pricing",
    "https://salesforce.com/pricing"
  ]
}

Flow Diagram

Harvey performs per-context grounding - it identifies that HubSpot uses “SSO” while Salesforce uses “Single Sign-On” by analyzing each YAML schema independently.

Request/Response Patterns

Pattern 1: Synchronous Summary

Use Case: Quick statistics about a pricing model

curl -X POST http://localhost:8002/api/v1/pricing/summary \
  -F "[email protected]"

Characteristics:

Latency: ~100-200ms
Operation: In-memory YAML parsing and statistics
No solver required

Pattern 2: Asynchronous Job Processing

Use Case: Complex CSP operations (optimal, subscriptions, validate)

Submit Job

curl -X POST http://localhost:8002/api/v1/pricing/analysis \
  -F "[email protected]" \
  -F "operation=subscriptions" \
  -F "solver=minizinc"

Response:

{"jobId": "job_abc123", "status": "PENDING"}

Poll for Results

curl http://localhost:8002/api/v1/pricing/analysis/job_abc123

Response (in progress):

{"jobId": "job_abc123", "status": "RUNNING"}

Retrieve Results

curl http://localhost:8002/api/v1/pricing/analysis/job_abc123

Response (completed):

{
  "jobId": "job_abc123",
  "status": "COMPLETED",
  "results": {
    "subscriptions": [...],
    "cardinality": 42
  }
}

Characteristics:

Latency: 500ms to 60s depending on complexity
Polling Interval: Recommended 1-2 seconds
Job TTL: Results cached for 1 hour

Pattern 3: Streaming Chat Response

Harvey streams responses to the frontend using Server-Sent Events.

// Frontend code
const eventSource = new EventSource(
  'http://localhost:8086/chat/stream?message=' + encodeURIComponent(message)
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'plan') {
    console.log('Execution plan:', data.plan);
  } else if (data.type === 'tool_result') {
    console.log('Tool completed:', data.tool, data.result);
  } else if (data.type === 'answer') {
    displayAnswer(data.answer);
  }
};

Event Sequence:

event: plan
data: {"type":"plan","plan":{"actions":["iPricing","optimal"]}}

event: tool_result
data: {"type":"tool_result","tool":"iPricing","result":{...}}

event: tool_result
data: {"type":"tool_result","tool":"optimal","result":{...}}

event: answer
data: {"type":"answer","answer":"The Pro plan at $29/mo..."}

event: done
data: {"type":"done"}

Caching Strategy

Cache Layers

MCP Server Cache

Key: pricing:{url}Value: Pricing2Yaml contentTTL: 3600 seconds (1 hour)Backend: In-memory or Redis

Analysis API Job Cache

Key: job:{jobId}Value: Job status and resultsTTL: 3600 secondsBackend: In-memory Map

Cache Hit/Miss Flow

Cache Invalidation

Manual: Set refresh: true in tool call
TTL Expiration: Automatic after 1 hour
No Proactive Invalidation: System doesn’t monitor URLs for changes

Error Handling Patterns

Error Propagation

Common Error Scenarios

Invalid URL

Trigger: User provides malformed or inaccessible URLError: AMintError: Failed to fetch URLHandling: Harvey asks user to verify URL

LLM Extraction Failure

Trigger: A-MINT can’t extract pricing structureError: AMintError: No pricing data foundHandling: Harvey suggests manual YAML upload

Invalid Filter

Trigger: Filter references non-existent featureError: AnalysisError: Feature 'XYZ' not found in YAMLHandling: Harvey re-plans with corrected feature names

Unsatisfiable Constraints

Trigger: No plan satisfies the filter criteriaError: AnalysisError: No solution foundHandling: Harvey explains why no plan matches

Solver Timeout

Trigger: CSP problem too complexError: AnalysisError: Solver timeout after 60sHandling: Harvey suggests simplifying filters or using Choco solver

Performance Metrics

Latency Breakdown

Operation	Cold (Cache Miss)	Warm (Cache Hit)
iPricing	5,000-10,000ms	1-5ms
Summary	100-200ms	100-200ms
Subscriptions (small)	500-1,000ms	500-1,000ms
Subscriptions (large)	5,000-60,000ms	5,000-60,000ms
Optimal	500-2,000ms	500-2,000ms
Validate	300-800ms	300-800ms

Throughput

Harvey API: ~10 concurrent chat sessions
MCP Server: ~50 concurrent tool calls
Analysis API: ~20 concurrent jobs
A-MINT API: ~5 concurrent extractions (LLM rate limit)

Next Steps

Architecture Overview

Return to architecture overview

Service Details

Explore individual services

Get Started

Architecture

Core Concepts

Guides

Overview

Core Data Flow Patterns

1. Simple Query Flow

Detailed Flow Scenarios

Scenario A: First-Time URL Analysis

Flow Diagram

Scenario B: Cached URL with Filters

Flow Diagram

Scenario C: Optimization Query

Flow Diagram

Scenario D: Multi-Pricing Comparison

Flow Diagram

Request/Response Patterns

Pattern 1: Synchronous Summary

Pattern 2: Asynchronous Job Processing

Pattern 3: Streaming Chat Response

Caching Strategy

Cache Layers

MCP Server Cache

Analysis API Job Cache

Cache Hit/Miss Flow

Cache Invalidation

Error Handling Patterns

Error Propagation

Common Error Scenarios

Performance Metrics

Latency Breakdown

Throughput

Next Steps

Architecture Overview

Service Details

Build docs developers (and LLMs) love

Get Started

Architecture

Core Concepts

Guides

​Overview

​Core Data Flow Patterns

​1. Simple Query Flow

​Detailed Flow Scenarios

​Scenario A: First-Time URL Analysis

​Flow Diagram

​Scenario B: Cached URL with Filters

​Flow Diagram

​Scenario C: Optimization Query

​Flow Diagram

​Scenario D: Multi-Pricing Comparison

​Flow Diagram

​Request/Response Patterns

​Pattern 1: Synchronous Summary

​Pattern 2: Asynchronous Job Processing

​Pattern 3: Streaming Chat Response

​Caching Strategy

​Cache Layers

MCP Server Cache

Analysis API Job Cache

​Cache Hit/Miss Flow

​Cache Invalidation

​Error Handling Patterns

​Error Propagation

​Common Error Scenarios

​Performance Metrics

​Latency Breakdown

​Throughput

​Next Steps

Architecture Overview

Service Details

Build docs developers (and LLMs) love

Overview

Core Data Flow Patterns

1. Simple Query Flow

Detailed Flow Scenarios

Scenario A: First-Time URL Analysis

Flow Diagram

Scenario B: Cached URL with Filters

Flow Diagram

Scenario C: Optimization Query

Flow Diagram

Scenario D: Multi-Pricing Comparison

Flow Diagram

Request/Response Patterns

Pattern 1: Synchronous Summary

Pattern 2: Asynchronous Job Processing

Pattern 3: Streaming Chat Response

Caching Strategy

Cache Layers

Cache Hit/Miss Flow

Cache Invalidation

Error Handling Patterns

Error Propagation

Common Error Scenarios

Performance Metrics

Latency Breakdown

Throughput

Next Steps