Enterprise AI Knowledge & Action Hub

Architecture & engineering decisions

A conversational interface joins enterprise knowledge retrieval, structured employee queries and a human-reviewed action workflow. Python owns authorization and execution; model calls help select tools and synthesize answers.

Enterprise AI logical architectureStreamlit calls FastAPI. The orchestrator coordinates model calls, grounding, and authorized tool execution. Tools reach RAG, employee repositories, and action proposals. These services use PostgreSQL. External providers supply models and embeddings.FASTAPI BACKEND · LOGICAL COMPONENTSStreamlit frontendBrowser UI · HTTP clientFastAPI entry pointAuthentication · request validationAgent OrchestratorContext · bounded tool loopGroundingServiceEvidence · citations · abstentionProvider gatewayExternal model APIsToolExecutorAuthorize before dispatchRagServiceRole-filtered hybrid retrievalEmployee repositoriesStructured data queriesActionApprovalServicePersist pending proposalExternal providersModels · embeddingsPostgreSQL + pgvectorKnowledge · employees · workflow stateConversation persistence also uses PostgreSQL. RAG requests embeddings from external providers.
Logical architecture: arrows summarize responsibilities rather than every direct function call. Not every question uses every component or needs a final model call. The vector diagram stays sharp when enlarged; scroll horizontally on small screens.

From question to evidence-backed answer

  1. Resolve identity. Streamlit sends the request to FastAPI. Hosted calls use the frontend service's Google identity for Cloud Run invocation plus application authentication. Local and hosted demo login use database-backed user sessions. Cloud IAM service identity and application user identity are separate authorization layers.
  2. Choose a bounded plan. The orchestrator loads conversation context and requests tool selection when needed. Round limits and duplicate-call suppression bound the tool loop.
  3. Authorize before execution. ToolExecutor checks the resolved identity's permissions and validates arguments before dispatching a protected operation.
  4. Retrieve permitted evidence. RAG coordinates embedding and hybrid search. KnowledgeRepository applies role filters in SQL; employee repositories provide structured database results.
  5. Ground the response. Grounding and answer-strategy logic determine whether evidence supports an answer, a deterministic result, or abstention. The UI renders sources and optional proposals.

See grounding and abstention evidence →

Engineering choices and their evidence

Authorization is application logic

A model-selected tool never grants privileges. Identity checks, tool authorization and knowledge role filters enforce access at their respective boundaries.

Reader denied; HR reader authorized

Evidence before a fluent answer

Retrieval supplies authorized evidence. Insufficient evidence can produce abstention, while supported knowledge claims include citations.

Policy answer and unsupported question

Proposal and decision are separate

The agent's salary tool persists a pending proposal. Separate approval/rejection endpoints handle the human decision. The portfolio demonstrates rejection without executing a salary change.

Pending proposal → rejection

Knowledge administration is explicit

Employee write access does not imply upload access. Ingestion requires knowledge-management permission and handles parsing, chunking, embeddings, persistence and duplicate detection.

Upload permission and retrieval evidence

Services and repositories have different jobs

Services coordinate application behavior; repositories implement database access. Composition injects providers and collaborators into extracted services.

Execution is observable

The optional sanitized inspector exposes measured stages, model/tool call counts, outcomes and latency. One trace explains one captured run; it is not a general performance benchmark.

Two-tool comparison and inspector

Local and hosted boundaries

AreaLocal demonstrationHosted deployment
UI and APIStreamlit and FastAPI containersPublic Streamlit Cloud Run service; IAM-protected FastAPI Cloud Run service
DatabasePostgreSQL/pgvector containerNeon PostgreSQL with SSL required
IdentityThree signed-in demo accounts for role testsDatabase-backed demo sessions; frontend Google service identity invokes backend; reader API-key configuration retained
ProvidersExternal model and embedding APIs; the database remains the source for structured records and stored knowledge
ConfigurationLocal environment configurationCloud Run environment and Secret Manager references

Repeatable release, explicitly initiated

A manual submission starts an automated Cloud Build pipeline. The release packages tracked source from a commit; it does not copy the local PostgreSQL volume or untracked working files.

  1. Build backend and frontend images with commit/build identifiers.
  2. Run focused tests, disposable-PostgreSQL checks, a real FastAPI startup check and release-orchestration tests.
  3. Publish the tested images to Artifact Registry.
  4. When deployment is explicitly enabled, inspect existing configuration and backend IAM policy, then run the migration job.
  5. Deploy backend and frontend sequentially. Confirm Cloud Run readiness, a ready revision and 100% latest-revision traffic.
  6. Perform separate browser checks for grounded answers, authorization denial and abstention.

Cloud releases completed successfully on October 18 and 19, 2026. Hosted reader sign-in/logout, policy retrieval, employee-data denial, HR-reader queries and writer proposal/rejection were verified. Image releases now preserve the configured login setting.

Control-plane readiness is distinct from functional or security verification. The pipeline does not automate the browser checks, provide automatic rollback, or make the two service deployments atomic.

Scope of the demonstration

The portfolio shows working behaviors, not a claim of enterprise SSO, production-scale reliability or complete security coverage. Privileged role screenshots were captured locally. The salary evidence covers the proposal/rejection path. Demo sessions cannot use the legacy direct salary-update endpoint; legacy API-key integrations retain that route. Writer self-approval is intentional for this demo; separate approver duties are not enforced. Evaluation results and trace timings should be read within their specific test scope.