Secure AI Synthesis Service

Version: 1.0 Date: October 12, 2025 Status: Draft

1.0 Overview

1.1. Purpose

This document provides the detailed functional specification for the integration between the Hybrid Forecasting Service (M26) and the AI Compliance & Trust Layer (M25). Its purpose is to define the precise architectural workflow, API contracts, and error handling required to ensure that all AI-driven synthesis and narrative generation is performed securely, in compliance with enterprise standards, and with full auditability.

This FSD serves as the master implementation guide for Task 26.2.4 and its dependency on Milestone 25.

1.2. Core Principle

The core principle of this architecture is that no service within ChainAlign shall make a direct call to an external Large Language Model (LLM). All interactions must be routed through the centralized AI Compliance Gateway, which enforces redaction, auditing, and security policies.

2.0 Architectural Flow

The interaction follows a strict sequence to ensure security and compliance at every step.

2.1. Sequence Diagram

2.2. Component Responsibilities

• Hybrid Forecasting Service (HFS):

  • Responsible for gathering all necessary data (statistical baseline, RAG context, supply constraints).
  • Constructs the initial, detailed, and potentially sensitive prompt required for AI synthesis.
  • Acts as a client to the AI Compliance Gateway. It is forbidden from calling the external LLM API directly.

• AI Compliance Gateway (ACG):

  • The single entry point for all outgoing LLM calls.
  • Orchestrates the entire secure workflow: sanitization, auditing, external API call, and response logging.
  • Enforces authentication and authorization for the calling service.

• Redaction Engine (RE):

  • A synchronous, internal service called by the ACG.
  • Applies universal (PII) and tenant-specific (proprietary) redaction rules to the prompt.
  • Returns the sanitized prompt and metadata about the redactions performed.

• Audit Logger (AL):

  • An internal service called by the ACG.
  • Writes a complete, immutable record of the interaction to the llm_interaction_audit table.

3.0 Detailed API Contract

This defines the contract for the internal API call from the HybridForecastingService to the AIComplianceGateway.

3.1. Endpoint

POST /api/chainalign/reasoning

3.2. Request Body

The HFS sends the raw prompt and contextual metadata.

{
  "prompt": "Based on a statistical forecast of 50,000 units for product SKU-123 and a 30% demand spike indicated by market news, what is the adjusted forecast, considering that supplier ACME-Parts has a 30% failure rate?",
  "user_context": {
    "service_name": "HybridForecastingService",
    "tenant_id": "uuid-for-tenant-abc",
    "user_id": "service-account-forecaster"
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "adjusted_forecast": { "type": "number" },
      "narrative": { "type": "string" },
      "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
      "key_assumptions": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["adjusted_forecast", "narrative"]
  }
}

3.3. Response Body (Success)

The ACG returns the final answer along with rich compliance and performance metadata.

{
  "answer": {
    "adjusted_forecast": 58500,
    "narrative": "The baseline forecast of [FORECAST_UNITS] for product [PRODUCT_SKU] has been adjusted upwards due to market events. However, significant risk is noted due to the poor reliability of supplier [REDACTED_SUPPLIER]."
  },
  "compliance_metadata": {
    "audit_log_id": "uuid-for-audit-entry-xyz",
    "sensitivity_score": "HIGH",
    "redactions_applied": 3,
    "redaction_types": ["number", "string", "string"],
    "contained_pii": false,
    "contained_proprietary": true
  },
  "performance_metadata": {
    "total_latency_ms": 2850,
    "llm_provider": "google",
    "llm_model": "gemini-1.5-pro",
    "prompt_tokens": 850,
    "response_tokens": 210,
    "estimated_cost_usd": 0.0087
  }
}

4.0 Error Handling & Fallback Strategy

The workflow must be resilient to failures at each step.

Step	Failure Condition	Fallback Action	Logged?
ACG	Invalid auth token from HFS	403 Forbidden response to HFS.	Yes
Redaction Engine	Fails to process prompt	500 Internal Server Error to HFS. Do NOT send the original prompt to the LLM.	Yes
Audit Logger	Fails to write initial log	500 Internal Server Error to HFS. Do NOT proceed with the LLM call.	No (Log to system console)
External LLM	API times out or returns an error	502 Bad Gateway to HFS. Log the failure in the audit record.	Yes
HFS	Receives an error from ACG	The HFS must not attempt to call the LLM directly. It should return an error to its own caller, stating that AI Synthesis is unavailable.	Yes (in its own service logs)

5.0 Placeholder & De-redaction Strategy

Handling the redacted placeholders in the final LLM output is critical for usability.

• V1 Strategy (Default): Present with Placeholders

  • The LLM response will contain the bracketed placeholders (e.g., [REDACTED_SUPPLIER]).
  • The HybridForecastingService will present this narrative as-is.
  • Rationale: This is the most secure approach, as it guarantees no sensitive data is ever accidentally exposed in the final output. It prioritizes compliance over perfect readability.
  • UI Requirement: The frontend, upon detecting placeholders in a narrative, should display a small info icon or tooltip explaining: "For security, sensitive identifiers have been redacted from this AI-generated text."

• V2 Strategy (Future Enhancement): Secure De-redaction

  • The AIComplianceGateway will store the mapping of placeholders to original values in a temporary, secure cache (e.g., Redis with a short TTL) associated with the audit_log_id.
  • The HybridForecastingService can then make a secure, server-to-server call back to the ACG with the audit_log_id to retrieve the original values and reconstruct the full narrative for internal display.
  • Risk: This adds complexity and a potential (though small) risk vector. It should only be implemented if the V1 placeholder approach proves to be a significant blocker for users.

This FSD provides the necessary detail to build a secure, compliant, and auditable AI synthesis layer, effectively "pinning together" your security architecture with your advanced AI forecasting features.