Core · Service · Active

platform-ai-service

Provider-agnostic AI boundary for the workspace, exposing a stable internal contract for text generation with pluggable providers.

• TypeScript
• NestJS 11
• PostgreSQL
• OpenAI SDK
• Responses API
• @platform/contracts-ai
• @platform/observability

Spec sheet

Boundary

Core / AI

Runtime

NestJS 11 HTTP service

Default port

3300

Persistence

PostgreSQL via AI_DATABASE_URL

Security

Required PLATFORM_INTERNAL_TOKEN plus forwarded bearer validation via platform-auth-service

Providers

Postgres-managed registry with openai and template support

Responsibilities

• Expose a stable HTTP contract for synchronous text generations.
• Keep provider selection behind a provider registry.
• Support OpenAI via Responses API and a local template fallback.
• Persist provider configuration and default routing through admin endpoints.
• Allow consumers to inspect configured and enabled providers.

Interfaces and contract surface

• GET /health
• GET /internal/ai/providers
• GET /internal/ai/providers/admin
• GET /internal/ai/providers/:providerKey
• PUT /internal/ai/providers/:providerKey
• POST /internal/ai/generations

Consumers

• platform-mcp-service
• platform-agent-service
• funnel backend as migration target
• cs-chat api

Dependencies and external touchpoints

• platform-auth-service
• platform-local-stack
• @platform/contracts-ai
• @platform/observability
• OpenAI-compatible provider endpoints
• PostgreSQL state store

Notes

• Funnel IA still contains legacy AI integrations that should progressively move behind this service.
• Always inspect /internal/ai/providers first if you need to know whether openai is really configured in the current environment.
• Provider enablement and default model routing are runtime state in Postgres, not environment-only configuration.
• The template provider is deterministic and intended for local tests and fallback scenarios.

Source references

• platform-ai-service/README.md
• docs/core-services-integration.md
• platform-ai-service/package.json

Come integrarsi davvero

Questa surface e pensata per backend/BFF e worker. Il frontend non deve chiamare platform-ai-service direttamente.

Variabili utili

export AI_URL=http://127.0.0.1:3300
export INTERNAL_TOKEN=platform-local-stack-internal-token

1. Scopri provider disponibili e default effettivo

Prima di integrare la generazione, conviene leggere /internal/ai/providers: ti dice quali provider sono abilitati, quali sono configurati davvero e quale verra usato come default.

curl -sS "$AI_URL/internal/ai/providers" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"

Se openai risulta configured: false, la route di generazione deve usare un provider disponibile, in genere template per smoke test locali. La configurazione provider viene letta dallo state store PostgreSQL, non da sole variabili ambiente.

2. Ispeziona configurazione admin

Le viste operations e gli strumenti interni usano anche la surface admin per dettaglio e aggiornamento provider:

curl -sS "$AI_URL/internal/ai/providers/admin" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"

curl -sS "$AI_URL/internal/ai/providers/template" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN"

3. Generazione locale deterministica con provider template

Questo e il percorso piu rapido per verificare contratto HTTP, timeout, retry applicativi e mapping della risposta senza dipendere da credenziali esterne.

curl -sS -X POST "$AI_URL/internal/ai/generations" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "providerKey": "template",
    "instructions": "Rispondi in una sola frase tecnica.",
    "input": "Descrivi il ruolo di platform-ai-service."
  }'

4. Generazione con OpenAI

Il backend prodotto deve applicare le policy utente prima di chiamare il servizio core. Authorization: Bearer <session-token-auth> non sostituisce mai x-platform-internal-token.

curl -sS -X POST "$AI_URL/internal/ai/generations" \
  -H "Content-Type: application/json" \
  -H "x-platform-internal-token: $INTERNAL_TOKEN" \
  -d '{
    "providerKey": "openai",
    "model": "gpt-5-mini",
    "instructions": "Rispondi in italiano con tono tecnico.",
    "input": "Scrivi due frasi su come un backend di prodotto deve usare questo servizio.",
    "metadata": {
      "tenantId": "demo-tenant",
      "feature": "product-description"
    }
  }'

La risposta espone sempre un contratto stabile:

• generationId per correlazione applicativa
• providerKey e model effettivamente usati
• outputText gia normalizzato
• usage con token input/output/total
• providerRequestId e providerResponseId per tracing provider-specifico

Un consumer reale lato backend e funnel-ia-engine/backend/src/platform/platform-ai.client.ts.