title	InfoAssistant
emoji	🤖
colorFrom	blue
colorTo	indigo
sdk	docker
app_port	7860
pinned	false
license	mit

Agentic Information Assistant (AIA)

Repository: agentic-state/PubSec-Agentic-InfoAsst (the GitHub identity for this project).

A refactor of Microsoft's Information Assistant agent template implementing the concepts of The Agentic State (Ilves, Kilian, Parazzoli, Peixoto, Velsberg — Tallinn Digital Summit, 2025).

AIA keeps the Information Assistant template's core idea — "chat with your own data" via the RAG pattern over Azure AI Search and Azure OpenAI — and rebuilds it as a governed, multi-step agentic assistant. It adds a ReAct-style planner, a governed tool registry, Responsible-AI gates with human-in-the-loop enforcement on decision-informing outputs, multi-language operation (EN/FR supported), FinOps cost attribution, and a provenance chain that makes every answer auditable from retrieval path through model version to policy rules applied.

This repository is a working rewrite meant to be reviewable as a proposed PR into the upstream template. See Agentic-State-Vision.md for the mapping of AIA to the paper's 12-layer model, and AIA-Design-Principles-Beyond-Agentic-State.md for the architectural gaps AIA addresses that the paper leaves open.

Open work tracked in BACKLOG.md. Changes logged in CHANGELOG.md. Contributor guidelines in CONTRIBUTING.md.

The running app

Screenshots pending regeneration against the generic fixture set. Regenerate with npx playwright test tests/e2e/screenshots.spec.ts (see tests/e2e/screenshots.spec.ts) after starting the local stack with seed data.

Surfaces covered: Landing, Chat, Workspace catalog, My Workspace, Admin (workspaces + model registry), Ops (FinOps cost, AIOps, drift monitor, LiveOps, DevOps, compliance audit, red-team evaluation).

Table of Contents

• Response generation approaches
• Features
• Azure account requirements
• Azure deployment
• Secure mode deployment
• Multi-language and accessibility baseline
• Security and compliance posture
• Responsible AI
• Shared responsibility
• Resources

Response generation approaches

Building on the IA template's four response modes, with additional governance extensions:

Work (Grounded). Retrieval-Augmented Generation against the tenant's own dataset, with pinpoint citations to the exact chunks used. Hybrid keyword + vector + semantic reranking over Azure AI Search (HNSW, cosine). Response always carries source anchors, freshness timestamps, and a confidence score.

Ungrounded. Direct LLM generation without retrieval — ideation, brainstorming, hypothetical exploration. Marked explicitly in the UI and excluded from audit chains that require grounded output.

Work and Web. Parallel RAG + web-search responses with optional comparative synthesis. Web citations required on web-sourced content.

Agentic (governance-gated). Canonical ReAct loop (plan -> execute_tool -> observe -> reflect -> continue|finalize) with six hard-terminated paths (step, wall-clock, token, LLM-timeout, circuit-breaker, finalize). RBAC is enforced at invocation time inside the loop -- not at registry load -- defending against planner jailbreak. Tool output is sanitized before re-entering the planner context. Every step is streamed as an NDJSON event for real-time UI rendering. Agentic responses at decision-informing assurance levels enforce a human-in-the-loop checkpoint before the answer surfaces.

Features

• Custom RAG pipeline — document ingestion -> Form Recognizer/layout parsing -> chunking (token-based, section/title aware) -> embeddings -> Azure AI Search hybrid index
• Governed tool registry — every tool registers with classification ceiling, residency, language support, HITL flag
• Responsible-AI gates — advisory vs decision-informing, with HITL enforcement on the latter
• Multi-language (EN/FR supported) — language-parameterized prompts, translation as a first-class tool, auto-routing for non-multilingual tools
• Explainable responses — every answer carries retrieval path, reasoning trace, negative evidence, source freshness, and behavioural fingerprint (model + prompt + corpus + policy versions)
• FinOps cost attribution — every AI call routes through APIM with x-app-id, x-user-group, x-classification headers
• Three-portal management surface — self-service (workspace booking), business management (client onboarding), ops & support (FinOps, AIOps, LiveOps, DevOps)
• Accessible step indicators — agentic planner steps are screen-reader announced

See Agentic-State-Vision.md and AIA-Design-Principles-Beyond-Agentic-State.md for the architectural principles behind these features.

Azure account requirements

• Azure subscription with Azure OpenAI service access. Models required:

  Model	Notes
  gpt-4o	default generation
  gpt-4o-mini	classification, routing, cheap calls
  text-embedding-3-small or -large	index embeddings

• Azure AI Search — Standard tier or above (HNSW vector index, semantic reranker)

• Azure Document Intelligence — PDF layout parsing

• Azure AI Foundry — hub for tool registry, evaluations, safety evals, tracing. Hub in the target Azure region, private endpoint, VNet.

• Azure API Management — the single public edge for all AI calls (FinOps header enforcement)

• Entra ID tenant — SSO + group-based RBAC

• Target Azure region with private networking — no public IPs, VNet traffic only (see Security and compliance posture)

Azure deployment

# One-command local setup
make install

# Full local stack (Azurite blob, Jaeger tracing, API on :8000, portal on :5173)
make dev

# Or Docker Compose
make docker-up

Manual start

# Terminal 1 — backend
docker compose up -d azurite jaeger
.venv/bin/uvicorn services.api-gateway.app.main:app --reload --port 8000

# Terminal 2 — frontend
npm run dev --workspace=@aia/portal-unified

Local service URLs:

Service	URL
API Gateway	http://localhost:8000
Portal (Lovable UI)	http://localhost:5173
Jaeger UI	http://localhost:16686
Azurite Blob	http://localhost:10000

Bicep IaC for Azure deployment lives in infra/ (target Azure region, private endpoints, VNet, APIM, AI Foundry hub).

Secure mode deployment

All deployments targeting sensitive data must:

• use private endpoints for every Azure resource (no public network access)
• route traffic through the tenant's VNet
• pin AI Search and Azure OpenAI to the target Azure region
• use Entra ID + managed identity (no API keys in production)
• enable Azure AI Content Safety with prompt-injection defense + content filtering
• enable Log Analytics + Foundry tracing with dual-auth gated access (anonymized logs only)

A country-specific authorization roadmap document is tracked as a future deliverable; reference docs/security/threat-model.md + docs/compliance/ for the currently-shipped security + compliance posture.

Multi-language and accessibility baseline

Target standard: WCAG 2.2 Level AA (declared 2026-05-21). Current claim is partial conformance -- the automated jest-axe suite passes with only color-contrast disabled (a jsdom rendering limitation, covered separately by the @axe-core/playwright real-browser nightly) after Phases B1+B2+B3+B4 landed 2026-05-21. Full status, evidence per criterion, and remediation queue are in docs/accessibility/CONFORMANCE.md. The externally-shareable conformance statement is at docs/accessibility/CONFORMANCE-STATEMENT.md (currently DRAFT).

• Accessible design system with first-class header, footer, nav, language toggle, breadcrumbs, and error summary components
• React 19 + Vite 6 + TypeScript 5.7 application layer with shadcn/ui on Radix Primitives + Tailwind v4 -- the primitive layer is WCAG-aligned by default (roles, keyboard handlers, focus management, aria-* attributes)
• react-i18next + {en,fr}/translation.json -- all frontend visible strings externalized; server-emitted strings are currently English-only and tracked for bilingual completion in Phase C. EN/FR supported; additional languages pluggable through the same framework once Phase C lands. See docs/i18n/STRATEGY.md.
• HTML lang attribute updates dynamically on language change for correct screen-reader pronunciation
• aria-live regions (polite + assertive, both aria-atomic="true") carry chat streaming output to assistive tech
• axe-core automated checks in CI via the test-ts job; manual screen-reader testing (NVDA + VoiceOver) is procedural and runs per major release once the documented procedure lands in Phase D

Security and compliance posture

This rewrite targets deployment against sensitive enterprise or public-sector data. Controls in scope:

• AC — Entra ID + group RBAC (Reader/Contributor/Admin), enforced at APIM and AI Foundry Hub
• AU — Log Analytics + Foundry tracing, weekly log review, dual-auth gated access, no PII in logs
• CM — baseline config + versioning for tools, prompts, models, policies (the "behavioural fingerprint")
• IA — Entra SSO, dual-auth on log/database access
• SC — TLS 1.3, encryption at rest, private endpoints, VNet, target Azure region only
• SI — Azure Content Safety, prompt-injection defense, grounding enforcement, citation requirement
• SA — Foundry safety evals, OWASP Top 10 for LLM, MITRE ATLAS, Google SAIF, NIST AI RMF, ISO/IEC 42001:2023

Responsible AI

• No retraining on user data
• Anonymized logs — no PII in Azure Log Analytics
• RAG-first — retrieve from trusted sources, generate with pinpoint citations; no fine-tuning for domain knowledge
• Responsible-AI gates — advisory vs decision-informing; mandatory HITL on decision-informing outputs
• Explainable reasoning — citations, retrieval path, negative evidence on every answer, regardless of assurance level
• Transparency — behavioural fingerprint (model + prompt + corpus + policy versions) recorded on every response

Shared responsibility

This template provides the agentic chassis, governance gates, and reference configuration. The deploying organization is responsible for:

• tenant-specific Entra ID group design and RBAC assignments
• content classification and corpus curation
• assurance level decisions per workspace and per use case
• legal review of the tool registry (classification ceilings, residency)
• ongoing log review, incident response, and authorization maintenance

Resources

Monorepo structure

apps/
  portal-unified/        # Single React 19 + Vite 6 portal app (root npm workspace)
services/
  api-gateway/           # FastAPI orchestrator (auth, guardrails, RAG, chat, agents)
  doc-pipeline/          # Azure Functions (PDF extract, enrich, embed, chunk)
  enrichment/            # Embeddings microservice scaffold
infra/                   # Bicep IaC + dev|staging|prod.bicepparam (see docs/infra/MODULES.md)
policies/                # Drift policy rule-packs (e.g. drift-p53.yaml)
scripts/                 # Operational scripts (see docs/operations/scripts.md)
tests/
  e2e/                   # Playwright end-to-end + visual regression
  eval/                  # PS-29 honesty-gate + per-provider baselines
  security/              # Adversarial test suites (prompt-injection, RBAC, SSRF, etc.)
  integration/ smoke/ unit/   # Integration + smoke + top-level unit suites
docs/                    # Public-facing reference (accessibility, i18n, compliance, etc.)

Note: shared types/utilities/components are inlined under apps/portal-unified/src/ rather than extracted into separate packages/* workspaces. The root package.json declares workspaces: ["apps/*"] only.

Key commands

Command	What it does
make install	Install all Node + Python dependencies
make dev	Start full local dev stack
make build	Build all workspaces
make test	Run npm + pytest suites
make lint	Ruff (Python) + ESLint (portal-unified)
make docker-up	Start Docker Compose stack
make docker-down	Stop Docker Compose stack

Configuration

cp services/api-gateway/.env.example services/api-gateway/.env

Key settings (all env vars use the EVA_ prefix per Pydantic settings binding at services/api-gateway/app/config.py:329; see docs/operations/hf-secrets-runbook.md for the full env-key map):

Variable	Purpose
EVA_AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint URL
EVA_AZURE_OPENAI_API_KEY	API key (dev only; prod uses managed identity)
EVA_AUTH_MODE	demo (no auth) or production (Entra ID)
EVA_DEPLOY_TARGET	hf-demo (SQLite + LanceDB) or azure-prod (default)
EVA_DEBUG	Enable debug mode

Documentation

• Agentic-State-Vision.md — design principles (Ilves & Kilian, 2025)
• AIA-Design-Principles-Beyond-Agentic-State.md — complementary principles
• BACKLOG.md — open work and phased remediations
• docs/accessibility/ — WCAG 2.2 AA conformance target + externally-shareable statement
• docs/i18n/ — bilingual (EN/FR) strategy
• docs/api/ROUTERS.md — backend router-by-router inventory
• docs/portal/PAGES.md — frontend page-by-page inventory across the three personas
• docs/retrieval/STACK.md — the 8 retrieval modules the gateway runs on top of Azure AI Search
• docs/infra/MODULES.md — Bicep module + environment param-file inventory
• docs/operations/ci-workflows.md — CI workflow inventory with NIST 800-53 control mapping
• docs/operations/scripts.md — operational scripts inventory
• docs/compliance/ — compliance evidence
• docs/security/ — threat models + pre-launch review
• docs/governance/ — audit cadence + cross-session review
• docs/audits/ — Phase G1 + meta-audit ledgers (audit history of record)

Reporting security issues

See SECURITY.md for the vulnerability reporting process, response SLA, and coordinated-disclosure policy.