Enterprise AI Platform¶

Honne · MVP Finance en Microsoft Azure

Plataforma empresarial de IA con capa común (APIM, Entra, Foundry, reglas, auditoría), reutilizada por Finanzas (en DEV) y RR.HH. (planificado).

IaC: no ejecutes terraform apply fuera del pipeline. En rama deployment, el apply de Terraform exige aprobación manual tras revisar el plan.

Documentación técnica · entorno DEV

Finance MVP

Cómo atender esta wiki (orden recomendado)

Orientarte en esta página (mapa del sistema)
Onboarding — clonar, local, deploy, smoke
Arquitectura Azure — entender el as-built
Guion de demo — validar el flujo HITL
Profundizar: Identidad/APIM → Foundry → Operaciones

Onboarding

Primer paso práctico: entorno local y smoke en Azure

Empezar
Arquitectura

Segundo: mapa as-built (APIM, Entra, ACA, Foundry)

Vista Azure
Demo

Tercero: guion HITL A1–A3 para presentar / validar

Abrir guion

Guía paso a paso (leer en este orden)¶

Paso	Documento	Qué aprenderás
1	Este inicio	Orientación: mapa del sistema en DEV
2	getting-started.md	Manos a la obra: local, deploy, smoke
3	arquitectura-tecnologica-azure.md	As-built Azure (borde, identidad, runtime)
4	demo-script.md	Validar / presentar el flujo HITL
5	entra-apim-finance.md	Login Entra, JWT, APIM, auth vs autorización
6	edge-front-door.md	Front Door, WAF, URLs públicas
7	finance-agent-foundry.md	Agente Foundry, tools, guardrails
8	deployment.md / terraform-pipeline.md	Pipelines y gates

Más referencia: architecture · data-model · azure-resources · azure-devops · decisions

Mapa del sistema (Finance as-built)¶

flowchart LR
  U[Usuario<br/>User / Reviewer] --> E[Entra ID]
  U --> W[finance-web<br/>Next.js · ACA]
  E -.->|OIDC| W
  W -->|JWT + proxy| G[APIM]
  G --> A[finance-api<br/>FastAPI · ACA]
  A --> R[Rule Engine]
  A --> S[(SQL / Blob / DI)]
  A --> F[Foundry Agent]
  F -->|tools| A

Entradas DEV (uso diario):

Servicio	URL
Portal Finance (AFD)	https://ep-finance-dev-gfayg5axbhd7h5hf.z02.azurefd.net/
Wiki docs (AFD)	https://ep-docs-dev-hhg4hpa5ecajdhfm.z02.azurefd.net/
APIM gateway	https://apim-eai-dev-fz1d.azure-api.net
APIM Developer Portal	https://apim-eai-dev-fz1d.developer.azure-api.net
Health	vía portal (proxy) o APIM + JWT · `/api/platform/health`

Preferir Front Door para portal y wiki. El FQDN ACA del API no es entrypoint (solo IP APIM).
Detalle del borde: edge-front-door.md.

Qué hace cada capa (lógica funcional)¶

flowchart TB
  A[1. PDF → Blob + Document Intelligence] --> B[2. Rule Engine FIN-001…005]
  B -->|PASS| C[Approved]
  B -->|FAIL| D[HITL en portal]
  D --> E[approve / reject / return + audit]
  F[Chat] --> G{Guardrail}
  G -->|off-topic| H[Rechazo fijo]
  G -->|in-scope| I[Foundry + tools]

Capacidad	Dueño	Nota
Extraer PDF	Document Intelligence	No el LLM
Reglas FIN-001…005	Código + SQL	Determinístico
Aprobar excepción	Humano (HITL)	Portal
Explicar / consultar OC	Foundry Agent + tools	Con guardrails
Identidad	Entra ID	Autenticación
Quién puede qué	App / grupos Entra	User\|Reviewer en portal/APIM/API; HITL = Reviewer

Detalle auth/authz: entra-apim-finance.md.

Estructura del repo¶

enterprise-ai-platform/
  apps/finance-web/          # Portal HITL + chat (Next.js, MSAL)
  services/finance-api/      # REST + rules + agent_runtime + guardrails
  services/rule-engine/      # FIN-001…005
  services/mcp-suppliers-server/
  agents/finance-agent/      # instructions.md + metadata Foundry
  infra/environments/dev/    # Terraform (ACA, SQL, APIM opt-in, …)
  scripts/                   # Entra apps, Foundry agent, smoke
  shared/contracts/openapi/  # finance.yaml
  docs/
  data/sample/finance/       # PDFs / seeds demo

Pipelines (Azure DevOps)¶

Org: honneprojects · Proyecto: Enterprise-AI-Platform

Pipeline	Cuándo	Efecto
eai-terraform-dev	push `deployment` + `infra/**`	plan → ManualValidation → apply
eai-finance-api-deploy	`services/finance-api/**`	imagen ACR + roll ACA API
eai-finance-web-deploy	`apps/finance-web/**`	imagen ACR + roll ACA Web
eai-mcp-suppliers-deploy	MCP suppliers	ACA MCP
eai-docs-wiki-deploy	`docs/**`, `README.md`	wiki estática
eai-mvp-ci	CI código	tests / no Azure

Rama operativa de deploy: deployment.

Arranque rápido¶

Local (API): ver local-dev.md y getting-started.md.

cd services/finance-api
pip install -r requirements.txt
uvicorn app.main:app --port 8001

Local (portal):

cd apps/finance-web
npm install
npm run dev
# http://localhost:3000 — sin Entra client id = modo demo

Azure smoke: abrir portal DEV → cola HITL → PDF → chat off-topic (rechazo) → pregunta de negocio (tools).

Estado actual (resumen)¶

I1 local + I2 Finance en Azure: cerrados
Portal HITL + PDF viewer + i18n ES/EN
Foundry agent v3 + instrucciones versionadas + guardrails en API
Apps Entra + grupos; APIM en Terraform (enable_apim)
Authz: portal/API exigen Finance.User o Finance.Reviewer; HITL solo Reviewer
Wiki técnica publicada (inicio = este README)

Principios¶

El LLM no accede directo a bases de datos (solo tools).
Reglas financieras determinísticas.
Aislamiento Finance Agent ↔ HR Agent.
Managed Identity primero; secretos en Key Vault.
Correlation ID + auditoría funcional end-to-end.