ACTG-AI Service

ACTG-AI is Nexa’s asynchronous LLM job engine. It runs the heavy, model-driven work behind the platform — generating raw-to-curated mappings, resolving data conflicts, and producing DDL, ETL, and projection code — as background jobs so the calling API never blocks. You rarely call it directly; the Databricks and Snowflake services delegate to it. This page explains what it does and the shape of its API.

What it does

ACTG-AI turns metadata and mapping requests into generated data assets. Its work spans the Raw → Curated → Consumption layers:

• Mapping — generate a raw-to-target (curated/TDM) column mapping from source and target schemas.
• Conflict resolution — apply precedence rules to resolve conflicting source records.
• Code generation — regenerate DDL and ETL, plus projection, SQL edit, and the G3 and G4 deploy stages.
• Nomenclature & enrichment — TDM (target data model) nomenclature loading, refresh, and enrichment.
• Dummy data — generate realistic test data for curated tables when live data isn’t available.

It reads its inputs from a PostgreSQL metadata store (schema/context tables) and writes results back for the rest of the platform to consume.

API shape

ACTG-AI is a FastAPI service titled ACTG-AI (info.version 1.0.0) built around asynchronous jobs: you submit a request, get a job identifier, and poll for the result rather than waiting on the HTTP call.

Authentication

Protected endpoints require a bearer token — the service advertises a BearerAuth HTTP scheme with JWT format. Send it the same way as the other services:

Authorization: Bearer <token>

A small set of paths are public: / (home), /health, /openapi.json, the docs UIs (/docs, /redoc), and the auth endpoints (/auth/token, /auth/status). Everything else needs a token. See Authentication for how tokens are issued.

Endpoints

Operational routes are served under the /api/v1/… prefix and grouped by function. Representative groups:

Area	What it does
Mapping	Generate raw-to-TDM mappings
Conflict resolution / detection	Resolve or detect conflicts by precedence rules
Projection	Generate projection code
SQL Editor (/sql-edit)	Programmatic SQL edits
Deploy (G3 / G4)	Run the G3 and G4 deployment stages
TDM nomenclature / enrichment / refresh	Manage and enrich the target data model
Jobs	Submit, track, and stream status of async jobs
Logs	Stream job/LLM log updates (server-sent events)
Dummy data	Generate test data for curated tables

The job lifecycle

1. Submit a request to an operation endpoint. The service enqueues a job and returns its ID.

2. Track progress via the jobs status endpoint, or subscribe to the log/event stream for live updates.

3. Read the result once the job reaches a terminal state.

Note

A reaper inside the API process marks jobs failed if their worker stops sending heartbeats (default: no heartbeat for ~10 minutes). A crashed worker therefore still produces a terminal status, so poll to completion and handle a terminal failed state as a normal outcome — the same async pattern described in Core Concepts.

Deployment

ACTG-AI runs as a FastAPI app plus one or more worker processes: the API enqueues jobs and the worker executes them. Both are part of your customer-managed deployment. It connects to a PostgreSQL metadata database and to your data platform to run generated code.

Full reference

ACTG-AI’s complete endpoint reference is generated on request rather than published as a standing page here — its surface tracks in-flight codegen work and changes frequently. To get the current reference:

• Fetch the live openapi.json from a running instance, or open its /docs (Swagger UI) or /redoc pages in a non-production environment.
• Ask your DataReadyAI contact for a generated snapshot pinned to your deployed version.

For the services that call ACTG-AI, see the API Overview.