// DOCUMENTATION_CORE_v1.0

System Protocols

Cognito is a functional, tactical workstation for sovereign intelligence. This documentation outlines the exact technical standards for local deployment.

Architecture Overview

Designed for absolute locality, the stack is partitioned into three functional layers:

  • Command Shell (Electron/React): A tactical UI built for high-legibility and local resource binding.
  • Inference Core (FastAPI): The localized gateway service that maps neural instructions to the llama.cpp engine.
  • Context Module (RAG): An in-memory retrieval engine using TF-IDF vectorization and cosine similarity to inject private knowledge archives into active context.

Boot Sequence

Node deployment requires an isolated environment. We explicitly support source-level builds to ensure operational transparency.

Prerequisites

  • Node.js v22.12.0+ (Interface Runtime)
  • Python v3.10.0+ (Processing Kernel)
  • C++ Compiler (Hardware Layer Mapping: Metal/CUDA)
# CLONE_SOURCE
git clone https://github.com/ArjunDeshwal/cognitoai.git

# INITIALIZE_VENV
python -m venv venv
source venv/bin/activate
pip install -r backend/requirements.txt

# EXECUTE_INIT
cd app && npm ci && npm run electron:dev

Retrieval RAG

Local knowledge injection is handled via the Context Module. Uploaded PDF/TXT artifacts are parsed and split into overlapping 500-word chunks (50-word overlap).

Chunks are indexed with a TF-IDF vectorizer (scikit-learn) and ranked by cosine similarity against the query vector, surfacing the top-5 most relevant excerpts without any external indexing service or embedding API call.

SECURITY_NOTICE

All RAG indexes are held exclusively in volatile RAM. No persistent search database is created, ensuring a zero-trace operation for sensitive document analysis.

Agent Sensory

Network access is explicit. Each conversation starts in Local mode; choosing Web or Deep permits the model to emit a [SEARCH: query] directive that the core resolves through DuckDuckGo. Search results are treated as untrusted reference data and private-network destinations are blocked.

Enabling Deep Search expands a single directive into a multi-source research pass instead of one lookup, for questions that need cross-referencing.

Command API

The desktop shell connects to the local API through a random per-launch port and bearer token. Requests without that token are rejected; the interface below is internal until a stable public API is released.

Neural Mounting

POST/v1/load_model
Mounts a GGUF neural archive to the inference core.

Discovery Flow

POST/v1/chat/completions
Initiates a neural reasoning stream, with explicit web_search and optional deep_search flags.

Model Foundry

GET/v1/models/search
Queries Hugging Face for available GGUF archives.

POST/v1/models/download
Pulls a selected archive directly into local storage — no browser, no manual file placement.

GET/v1/models/local
Lists archives already mounted on this node.

Document Ingest

POST/v1/documents/upload
Submits a PDF/TXT artifact for chunking and indexing into the Context Module.