Nora SuperIntelligence LabNora source

One assistant. Clear service boundaries.

Architecture shows the reusable system: who owns each responsibility, how a request moves, and why document preparation stays outside the conversation. The walkthrough applies those same boundaries to concrete scenarios.

  • Single assistant
  • Prepared knowledge
  • Durable state
  • Provider-flexible
Follow the request path Nora source on GitHub
On this page

Request workflow

How one request reaches an answer.

This reusable request path is the system contract: the question enters through the Browser UI or embedded tool, Coordination retrieves prepared passages, and the answer is produced while the checkpoint is retained. The walkthrough applies it to the fictional Atlas question.

One NIS requestExample: retrieve the Atlas plan, infer an answer and persist the new conversation. Direct FastMCP uses the same operation · tool cycles remain bounded · ingestion is separateask_nisin processsearchencodequery vectorhybrid searchpassagesoptional readcontextanswer / tool callcheckpointsanswer + UUIDCLIENTClientQuestion + optional UUIDENTRANCEMCP entranceGateway → FastMCPSERVICENIS / LangGraphShared operation + selectorSERVICERetrieval MCPSearch / bounded readsCLIENTAnswer + thread_idPlain response to clientSTORAGEPostgreSQLLifecycle checkpointsPROVIDERInference providerQuestion + bounded contextSERVICEBGE serverQuery → vectorSTORAGEPrepared textFull document readSERVICEGrounding evidencePassages + document textSTORAGEQdrant searchVector → passages + IDs

Select a node to explore its connections.

View all component details
  • Client: The client sends a question and an optional UUID conversation identifier to the shared entrance. It renders the answer returned by the operation and passes the UUID along for follow-up requests.
  • MCP entrance: The MCP entrance receives client requests and forwards them through the LiteLLM gateway into the embedded FastMCP adapter, with a documented direct option available. It returns shared-operation results to the client. The entrance does not select models or execute the LangGraph application flow.
  • NIS / LangGraph: The NIS orchestration node receives forwarded requests inside the Coordination service. It runs the shared operational flow, the incumbent model selector, and the LangGraph runtime to produce responses. The node returns grounded answers while delegating knowledge retrieval to the separate Retrieval MCP service.
  • Retrieval MCP: The Retrieval MCP receives bounded search and read calls during the coordination flow. It queries BGE for vector encoding, executes hybrid search against Qdrant, and reads full text from the prepared document store. The service returns passages and document text but excludes all ingestion activities.
  • Answer + thread_id: The answer node receives the completed operation result from the Coordination service. The client renders this plain response for the user; the node itself carries the answer data and thread_id back to the requester.
  • PostgreSQL: PostgreSQL receives checkpoint writes from the LangGraph runtime during operations. It persists conversation state and lifecycle data across MCP transport sessions, enabling thread continuity. The database maintains these checkpoints independently from the prepared document knowledge used for retrieval.
  • Inference provider: The inference provider receives the question and bounded grounding context assembled by the coordination flow. It generates responses using Ollama Cloud or Fireworks models according to the incumbent selector. The provider returns generated output for the answer path but does not perform retrieval.
  • BGE server: The BGE server receives retrieval queries in query mode during search operations. It encodes these queries into vector embeddings used by the retrieval service. The service returns query embeddings to the retrieval flow; it does not read full documents or generate final answers.
  • Prepared text: The prepared text store receives document identifiers selected by the search process. It serves the full prepared document text for those specific identifiers. The store returns document content for grounding context while remaining separate from conversion and import workflows. Reads occur when content is needed.
  • Grounding evidence: The grounding evidence node receives Qdrant passages and prepared document text gathered during retrieval. It packages this bounded context for the inference provider. The node returns grounding material attached to the question; no manual ingestion is triggered during this question flow.
  • Qdrant search: Qdrant receives vector embeddings produced by the BGE server. It performs dense and lexical hybrid search over the active prepared release to identify relevant content. The index returns matching passages and chunk identifiers; it operates separately from conversation checkpoints.

The request path shows how Coordination handles inference and retrieval directly.

Technical architecture

Components, state, and system boundaries.

The map makes ownership explicit. Browser UI connects directly to Coordination, while MCP clients separately use the gateway to embedded FastMCP; Retrieval and conversation state remain separate services.

NIS system architectureExample: ask NIS to compare two documents, then continue the same new conversation. One assistant · shared NIS operations · separate retrieval and manual ingestion. Manual jobs also publish documents and the index; see the ingestion view.MCPMCPin processsearch / readmodel callscheckpointsHTTP / AG-UIdirect MCPfull textindexencode querybatch encodingCLIENTCodex / OpenClawNew topic conversationsENTRANCELiteLLM gatewayMCP entrance · own processENTRANCEEmbedded FastMCPInside existing FastAPI processSERVICENIS assistantDeep Agents / LangGraphCLIENTBrowser UICopilotKit / AG-UISTORAGEPostgreSQLConversation checkpointsPROVIDERInference providersOllama Cloud / Fireworks.aiSERVICERetrieval MCPSeparate knowledge serviceMANUAL JOBManual ingestionFour jobs · operator commandSERVICEShared BGEQuery + document encodingSTORAGEQdrantDense + lexical search indexSTORAGEPrepared documentsLocal baseline / GCS target

Select a node to explore its connections.

View all component details
  • Codex / OpenClaw: Clients use one NIS assistant. Each new topic gets a new UUID conversation; a follow-up reuses that UUID. Old-chat migration is excluded.
  • LiteLLM gateway: The selected default entrance forwards MCP tool calls. It does not replace the NIS model selector or execute LangGraph. Its real-runtime overhead is unmeasured.
  • Embedded FastMCP: Planned adapter calls shared NIS operations in process. Preserve and combine FastAPI and MCP lifespans. No separate adapter host or loopback HTTP hop.
  • NIS assistant: One assistant owns the incumbent model selector, bounded tool execution and conversation checkpoints. Application inference remains inside NIS.
  • Browser UI: The existing web entrance keeps its HTTP/AG-UI path into shared application operations.
  • PostgreSQL: Conversation history belongs to LangGraph, independent of MCP transport sessions. New conversations persist; old history is not deleted.
  • Inference providers: The incumbent NIS selector chooses application models. Local Ollama remains an optional route. LiteLLM built-in model routing is not selected.
  • Retrieval MCP: Search/read stays separate from the client-facing embedded FastMCP entrance. Retrieval calls BGE for query encoding, Qdrant for search and the pinned prepared-document store for full text.
  • Manual ingestion: Conversion, preparation, batch embedding and import/verify run independently of conversations. No question starts ingestion.
  • Shared BGE: Retrieval uses query mode; the batch job uses document mode. Pin model/configuration and bound batch load to preserve interactive capacity.
  • Qdrant: The index is derived from prepared artifacts. It is separate from conversation state and must match the active document release.
  • Prepared documents: Dated private deployment uses the local prepared release. GCS publication and activation remain a separate verified cutover, not a completed deployment.

Browser UI connects directly to Coordination, while MCP clients separately use the gateway to embedded FastMCP.

Manual ingestion

Preparation stays outside the conversation.

Conversion, preparation, embedding, and import are operator-triggered jobs, not request-time work. This separate path prepares documents and the retrieval index; the walkthrough shows it as its own operator scenario.

Updating knowledgeBuild a complete release, verify its documents and index, then select it for Retrieval. Additions: merge with retained corpus before import. Current deployment: explicit local pin. GCS cutover: pending.INPUTSelected sourcesImmutable original versionsJOB 1ConversionExtract text and source metadataJOB 2PreparationFull documents + stable chunksJOB 3EmbeddingBGE vectors + model metadataJOB 4Import + verifyComplete bundle → fresh indexDEPLOYMENTActivate RetrievalSelect matching documents + index

Select a node to explore its connections.

View all component details
  • Selected sources: Select original versions and preserve their bytes, dates and provenance. For a rebuild, include the complete desired source set. For additions, prepare a delta and assemble it with the retained complete corpus before import.
  • Conversion: Docling converts supported binary documents; supported text and JSON inputs use direct readers. Originals are mounted read only.
  • Preparation: Normalize deterministically, preserve headings and substantive meaning, and record coverage, stable chunk IDs, hashes and offsets. No LLM summaries or rewriting.
  • Embedding: Encode document chunks with shared BGE. Preserve configuration and vectors. Bound batch load so interactive queries retain capacity. For additions, assemble the embedded delta with the retained bundle before import.
  • Import + verify: Import the complete bundle into a fresh Qdrant collection, independently verify identities and counts, after taking database backups. Import alone does not activate the running service.
  • Activate Retrieval: The current private deployment requires an explicit local release-pin overlay and recreation of only Retrieval. Pointer-following installations use current or a GCS pointer. GCS cutover is pending. Database backups and matching prepared documents are recorded before the update.

Manual ingestion runs outside the conversation flow to prepare text for retrieval.

Decisions & tradeoffs

Architecture decisions and tradeoffs.

Architecture defines the reusable boundaries. Decisions records why they were chosen, Validation records what was checked, and Walkthroughs applies the boundaries to concrete examples.

Review decisions and tradeoffs