Provider API - Quick Reference

Purpose: standardize how ACS fetches candidates from L2/L4/L1.

Request

{ "request_id": "...", "query": "...", "entities": ["..."], "top_k": 20, "deadline_ms": 300, "expansion": false, "privacy_mode": "allow" }

Response

{
  "request_id": "...",
  "candidates": [
    { "id": "doc:...", "text": "...", "entities": ["..."], "cost_tokens": 110, "source": "L2" }
  ],
  "latency_ms": 120,
  "warnings": [ { "code": "PROJECT_EMPTY", "message": "No project data; consider expansion to L1" } ]
}

Rules

• Deadline per provider; partial responses accepted.
• Sources must label items with stable IDs and minimal text (snippet) only.
• No raw sensitive payloads; providers must honor privacy_mode.
• L1 expansion requires expansion:true and must emit a user‑visible warning upstream.
• Per‑provider time slice; ACS may retry with reduced top_k before considering expansion.
• Token budget is strict (0% overshoot). Latency is a comfort target; do not fail hard solely on soft latency exceedance.

Examples

L2 Provider: PROJECT_EMPTY Warning Scenario

Request to L2 (Project Library)

{ 
  "request_id": "req-100", 
  "query": "explain ACS planner implementation", 
  "entities": ["acs", "planner"], 
  "top_k": 10, 
  "deadline_ms": 300, 
  "expansion": false, 
  "privacy_mode": "allow" 
}

Response (PROJECT_EMPTY warning)

{
  "request_id": "req-100",
  "candidates": [],
  "latency_ms": 45,
  "warnings": [ 
    { 
      "code": "PROJECT_EMPTY", 
      "message": "No project data found for ACS implementation. Consider expansion to L1 global knowledge." 
    } 
  ]
}

ACS re-issues with explicit L1 expansion

{ 
  "request_id": "req-101", 
  "query": "explain ACS planner implementation", 
  "entities": ["acs", "planner"], 
  "top_k": 8, 
  "deadline_ms": 400, 
  "expansion": true, 
  "privacy_mode": "allow" 
}

L1 Response with global knowledge

{
  "request_id": "req-101",
  "candidates": [
    { 
      "id": "global:acs-concept#planning-algorithms", 
      "text": "Adaptive Context Scaling uses budget-aware planning to optimize information retrieval across hierarchical knowledge layers...", 
      "entities": ["acs", "planner", "budget_optimization"], 
  "cost_tokens": 145,
  "source": "L1"
    },
    { 
      "id": "global:cognitive-load-theory#working-memory", 
      "text": "Working memory constraints require adaptive context selection based on cognitive load assessment...", 
      "entities": ["cognitive_load", "working_memory", "context_selection"], 
  "cost_tokens": 118,
  "source": "L1"
    }
  ],
  "latency_ms": 285,
  "warnings": [
    {
      "code": "EXPANSION_ACTIVATED",
      "message": "Expanded to global knowledge due to insufficient project data"
    }
  ]
}

L4 Provider: Experience Pattern Matching

Request to L4 (Experience Layer)

{ 
  "request_id": "req-200", 
  "query": "debug React authentication loop mobile", 
  "entities": ["react", "authentication", "mobile", "debug"], 
  "top_k": 5, 
  "deadline_ms": 250, 
  "expansion": false, 
  "privacy_mode": "redact" 
}

Response with historical patterns

{
  "request_id": "req-200",
  "candidates": [
    { 
      "id": "exp:react-auth-debug#2025-08-20", 
      "text": "Similar auth loop debugging session: issue resolved by clearing [REDACTED: session_storage] and resetting state...", 
      "entities": ["react", "authentication", "mobile", "session_management"], 
  "cost_tokens": 132,
  "source": "L4"
    },
    { 
      "id": "exp:mobile-safari-cookies#2025-07-15", 
      "text": "Mobile Safari cookie handling differences caused similar authentication loops. Solution: explicit cookie domain settings...", 
      "entities": ["mobile", "safari", "cookies", "authentication"], 
  "cost_tokens": 108,
  "source": "L4"
    }
  ],
  "latency_ms": 180,
  "warnings": []
}

Provider Timeout Scenario

Request with tight deadline

{ 
  "request_id": "req-300", 
  "query": "hyperbolic embedding optimization GPU", 
  "entities": ["hyperbolic", "embedding", "gpu"], 
  "top_k": 15, 
  "deadline_ms": 150, 
  "expansion": false, 
  "privacy_mode": "allow" 
}

Privacy Mode: Block (no raw text)

Request with privacy_mode=block

{ 
  "request_id": "req-400", 
  "query": "customer email reset token", 
  "entities": ["email", "reset", "token"], 
  "top_k": 3, 
  "deadline_ms": 200, 
  "expansion": false, 
  "privacy_mode": "block" 
}

Response with minimal, non-sensitive content

{
  "request_id": "req-400",
  "candidates": [
    { 
      "id": "proj:auth#reset-token-overview", 
      "text": "[BLOCKED]", 
      "entities": ["auth", "reset", "token"], 
      "cost_tokens": 42,
      "source": "L2"
    }
  ],
  "latency_ms": 72,
  "warnings": []
}

Partial response due to timeout

{
  "request_id": "req-300",
  "candidates": [
    { 
      "id": "proj:gpu-optimization#batch-processing", 
      "text": "GPU batch processing for hyperbolic embeddings shows 8x speedup with optimal batch size of 512...", 
      "entities": ["gpu", "optimization", "batch_processing"], 
  "cost_tokens": 95,
  "source": "L2"
    }
  ],
  "latency_ms": 150,
  "warnings": [
    {
      "code": "PARTIAL_DATA",
      "message": "Provider returned partial response due to 150ms deadline. Additional results available with increased timeout."
    }
  ]
}

Warnings (common)

• PROJECT_EMPTY — no project data found
• PARTIAL_DATA — provider returned partial response due to deadline
• LOW_COVERAGE — entities coverage below threshold