# Open Fusion Nestjs API

> Build and maintain the Open Fusion NestJS backend API. Use when Codex implements or changes OpenAI-compatible HTTP endpoints, NestJS modules/controllers/services, request validation, streaming SSE responses, OpenAI-style error envelopes, model listing, authentication guards, or API tests for the Open Fusion LLM gateway.

- Skill: `vinilana/open-fusion-nestjs-api` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vinilana/open-fusion-nestjs-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vinilana/open-fusion-nestjs-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: vinilana (https://skillmd.com/u/vinilana)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vinilana/open-fusion-nestjs-api

---


# Open Fusion NestJS API

## Required Context

Before editing API code, read:

- `docs/PRD.md`
- `docs/specs/001-openai-compatible-api.md`
- `docs/specs/005-streaming-tools-response-normalization.md`
- `docs/adrs/0001-use-nestjs-backend.md`
- `docs/adrs/0002-openai-compatible-public-api.md`

Also read `docs/specs/007-observability-resilience-security.md` when touching auth, errors, logs, limits, health checks, or request ids.

## API Contract

Preserve these MVP endpoints:

- `POST /v1/chat/completions`
- `GET /v1/models`

Treat OpenAI compatibility as the public contract. A client should be able to change `baseURL` and token without learning Open Fusion internals.

## NestJS Structure

Prefer modules with clear ownership:

- API/controller layer: HTTP shape, status codes, headers, SSE response framing.
- Application services: route resolution, orchestration request lifecycle, response normalization.
- Config services: validated configuration access only.
- Provider services: call adapters, never import provider SDKs in controllers.
- Guards/interceptors/filters: auth, request id, logging, error normalization.

Do not let controllers import OpenRouter, Vercel provider packages, or raw configuration files directly.

## Chat Completions Rules

- Validate `model` and `messages` before orchestration.
- Reject non-finite numeric request fields (`NaN`, `Infinity`, `-Infinity`) with an OpenAI-style validation error.
- Enforce configured payload, message-count, and message-content limits before orchestration.
- Preserve compatible request fields when supported.
- Reject or ignore unsupported fields consistently with the configured compatibility policy.
- Return OpenAI-style error envelopes.
- For `stream: true`, use `text/event-stream` and terminate with `data: [DONE]`.
- Do not stream internal delegation traces unless a future spec explicitly allows it.

## Controller Logging Rules

- Put context creation, validation, route lookup, model access checks, and tools policy checks inside the failure logging path.
- If a request fails before route/orchestrator resolution, log a minimal `chat_completion.failed` event with `requestId`, client id when known, stream flag when known, latency, and normalized error.
- Never open SSE before all pre-stream validation and routing failures that should return JSON have been handled.

## Testing

Add focused tests for:

- request validation;
- `NaN`/`Infinity` numeric rejection;
- message count, message content, and payload limits;
- auth failures;
- unknown public model;
- failure logs for validation/model/tool-policy errors before SSE starts;
- non-streaming response envelope;
- streaming chunk shape and `[DONE]`;
- provider/orchestration errors mapped to OpenAI-style errors.

When API behavior changes, update the owning spec before or with the implementation.