Nexus

The consolidated, integrated flagship product of the ai-core-infra suite. It consists of a responsive Single Page Application (SPA) web application designed with a premium Dark Mode aesthetic (violet neon gradients, Glassmorphism panels, and Montserrat typography) that unifies under a single control interface all the modular capabilities developed throughout the infrastructure.

The application allows real-time interaction with HNSW vector search indexes, visualization of interactive knowledge graphs manipulated by physics force simulators, dialogue with autonomous agents equipped with decay memory, and monitoring of internal performance through a live telemetry panel (Flame Graph).

Consolidation and Interlinking Architecture

The module acts as the Application Plane that coordinates the repository's sub-projects.

flowchart TD
    User[SPA User Interface HTML/JS] -->|1. Create Note| API_Notes[POST /api/notes]
    User -->|2. Agent Chat| API_Chat[POST /api/chat]
    
    subgraph Note Ingestion Pipeline
        API_Notes --> ChunkEngine[semantic-chunking-engine]
        ChunkEngine --> VectorIndex[nano-vector-db - HNSW Graph]
        VectorIndex --> GraphExtractor[knowledge-graph-extractor]
        GraphExtractor --> D3Update[Update D3.js Graph]
    end
    
    subgraph Dialogue and Security Loop
        API_Chat --> GuardrailsInput[llm-guardrails-shield - Input Filter]
        GuardrailsInput --> AgentLoop[orchestra-agents - ReAct loop]
        AgentLoop --> AgentMemory[agentic-memory-layer - Ebbinghaus Memory]
        AgentMemory --> StreamSSE[FastAPI StreamingResponse - SSE tokens]
        StreamSSE --> GuardrailsOutput[llm-guardrails-shield - Output Filter]
    end
    
    Pipeline_Tracer[llm-observability-tracer] -.->|Span Instrumentation| Pipeline_Logs[SpanModel / Telemetry Endpoint]
    API_Notes & API_Chat & ChunkEngine & VectorIndex & GraphExtractor & AgentLoop & AgentMemory & GuardrailsInput & GuardrailsOutput -.-> Pipeline_Tracer
    
    Pipeline_Logs --> TelemetryPanel[Telemetry Dashboard: Live Flame Graph]

1. The Ingestion and Processing Pipeline

When saving a new semantic note to the system:

1. Semantic Segmentation: The text is split into cohesive fragments using the semantic-chunking-engine, avoiding artificial sentence breaks.
2. Vector Registration: Fragment embeddings are computed locally and indexed in nano-vector-db's multi-layer HNSW graph.
3. Entity Mapping: The knowledge-graph-extractor module analyzes the text extracting logical relationships (example: [Note] -> contains -> [Concept] -> belongs to -> [Category]) to populate the relational graph database.
4. Telemetry: Each of these phases is recorded in a nested fashion in an llm-observability-tracer telemetry Span.

2. The Autonomous and Secure Chat Loop

When starting a dialogue with the integrated agent:

1. Input Filter: The prompt passes through the llm-guardrails-shield shield to detect code injections and anonymize personal data (PII) such as emails and phone numbers.
2. ReAct Reasoning: The orchestra-agents engine starts a loop of thoughts and tool invocations to answer the user's query.
3. Episodic Memory: The agent queries agentic-memory-layer, retrieving facts from the digital brain applying temporal decay (Ebbinghaus forgetting curve) to avoid loading the context with irrelevant data.
4. Streaming Emission: The FastAPI server returns a connection via Server-Sent Events (SSE), delivering tokens word by word in real time to the SPA chat.
5. Output Filter: Before rendering the response, the firewall validates that there are no blatant RAG hallucinations or accidental API key leaks.

3. Premium Interface Components

• D3.js Graph Map: Interactive visualizer that maps the digital brain's nodes applying a physics force simulator (link force with distance 80, charge repulsion force -100, collision force radius 25). It colors the root node purple, notes red, and theoretical concepts blue, supporting node dragging, zoom, and panning.
• Flame Graph Dashboard: A side panel that consumes the observability tracer's /api/telemetry endpoint and draws horizontal bar charts proportional to each module's actual latency in milliseconds, coloring failed steps red and allowing clicking on each bar to expand inputs/outputs.

Installation Requirements

The module requires Python 3.9 or higher and the following dependencies:

• FastAPI
• Uvicorn
• SSE-Starlette
• Pydantic
• HTTPX (Test Client)

To install local dependencies, activate your virtual environment and run:

pip install -r requirements.txt

Project Structure

• main.py: FastAPI server that exposes the notes, graph, chat SSE, and telemetry endpoints, integrating imports from the workspace's sibling modules.
• templates/index.html: Source code of the Single Page Application, designed with vanilla CSS styles (Glassmorphism, Neon Glow) and native JavaScript controllers for D3.js and SSE streaming.
• test_nexus.py: Asynchronous unit test suite that validates the REST endpoints, error handling, graph retrieval, and consistency of chat responses.
• example.py: Product bootstrap script that pre-populates the digital brain with notes on RAG, QLoRA, and DVC to initialize the knowledge graph, and starts the web server.

Installation and Execution

1. Activate the Local Environment and Install Dependencies

Make sure you are in the project directory before activating the environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Run Integration Tests

Validate the consistency of the endpoints and the server flow:

.venv/bin/python -m unittest test_nexus.py

3. Start the Consolidated Application

Start the notes bootstrap and the local FastAPI server:

.venv/bin/python example.py

The script will print the initial data load and enable serving at:

• Access URL: http://127.0.0.1:8000

Open the URL in your preferred browser to interact with the digital brain's admin console, visualize the D3.js forces, and monitor the observability Flame Graph in real time.