Core Architecture: The Knowledge Core

ANDARTIS is a domain-agnostic, local-first intelligence framework designed exclusively for macOS. It transforms static local data into a dynamic, interactive "Nervous System" using a hybrid architecture of PHP orchestration and Apple MLX acceleration, communicating via a zero-latency JSON-RPC STDIO pipeline.

---

Core Philosophical Mandates

1. Local-First: All raw data, processed metadata, and model weights remain strictly on the user's local machine. There is zero cloud dependency and no telemetry egress.
2. Micro-Specialization: Instead of relying on a single, resource-heavy LLM for everything, ANDARTIS orchestrates a fleet of hyper-specialized, light-weight "Brains" (Capabilities) managed by a persistent JSON-RPC process.
3. Agnostic Foundation: The framework has no hardcoded domain assumptions. It models all ingested documents as generic Nodes and Entities to remain useful for any profession.

---

System Components

graph TD
    User([User UI Interface]) <--> |Inertia/Vue| PHP[Laravel & NativePHP Core]
    PHP <--> |JSON-RPC over STDIO| Python[Persistent Python Daemon]
    Python <--> |MLX Engine| ANE[Apple Neural Engine / VRAM]
    PHP <--> |Local Query| DB[(Isolated SQLite DB)]
    Python <--> |Save/Load Weights| Disk[(Local NPZ / Safetensors)]

1. The Orchestrator (Laravel & NativePHP)

• Role: Coordinates the lifecycle of Intelligence Nodes, configures schemas, handles file ingestion queues, and communicates with the Python background daemon.
• Process Manager: Spawns and monitors the Python process. The daemon holds neural weights in VRAM to eliminate cold-start loading delays.
• Sequential Guardrails: PHP controls execution scheduling, ensuring heavy tasks (like model fine-tuning) run sequentially to prevent memory choking on the Apple Neural Engine.

2. The Librarian (Ingestion Pipeline)

• Role: High-fidelity document scanner. Walks user-defined directories, computes hashes for change detection, and normalizes various file types into the SQLite core.
• Extraction Forge: Uses a specialized global micro-model to extract metadata using "Semantic Resonance". By matching texts against forged structural prototypes, it extracts clean JSON variables without waking the larger SLM.

3. The Brains (Capability Plugin System)

• Role: Specialized Python classes containing isolated model logic. They load directly into the daemon memory.
• Key Capabilities:
  • Senior Analyst (Conversational SLM): Instruction-tuned model parsing context and queries.
  • Semantic Navigator: Neural vector ranker using Siamese Transformers.
  • Entity Analytic: Symbolic parser scanning database schemas.

---

Grounded Synthesis Data Lifecycle

sequenceDiagram
    autonumber
    User->>PHP Orchestrator: natural language query ("Total cost in March?")
    PHP Orchestrator->>Python Daemon: Parse Intent (SLM)
    Python Daemon-->>PHP Orchestrator: JSON Execution Plan (aggregate_query + SQL SELECT)
    PHP Orchestrator->>DB [(SQLite Node Core)]: Run SQL Filter query
    DB-->>PHP Orchestrator: returns RAW JSON Data (100 matched rows)
    PHP Orchestrator->>Python Daemon: Synthesis Pass (Sample JSON + Context)
    Python Daemon-->>PHP Orchestrator: Fluid Conversational Response
    PHP Orchestrator->>User: Displays Grounded Hallucination-Free Answer

1. Initialization: A user adds a local folder as an Intelligence Node and selects an extraction schema.
2. Ingestion: The Librarian crawls files, hashes them, performs metadata extraction using the Semantic Echo Head, and writes records to an isolated core.sqlite file.
3. Activation: The system registers and initializes Node-specific capabilities, loading target weights.
4. Agentic Execution: When a query is made, the Intent Blade determines the optimal retrieval path, fetches context, and passes it to the Senior Analyst for final writing.

---

Project Containers & Cross-Reasoning

To enable multi-node analytics and structured visualization, ANDARTIS introduces Project Containers and Cross-Reasoning.

Project Containers

A Project Container acts as a visual and logical namespace grouping related Intelligence Nodes. Instead of managing disconnected folders individually, developers can group them into high-level projects (stored in the main database's projects table) to configure shared goals, coordinate metadata schemas, and execute multi-source analysis.

Federated Cross-Reasoning

When dealing with multiple nodes, users can select a subset of nodes within a project container and initiate a Cross-Reasoning query. Instead of querying a single database, the system federates the query across multiple independent knowledge cores and synthesizes the results.

sequenceDiagram
    autonumber
    User->>PHP Orchestrator: Cross-Reason query ("Compare Patient A and Patient B")
    Note over PHP Orchestrator: Identifies selected Node IDs in Project Group
    PHP Orchestrator->>DB [(SQLite Node 1)]: Semantic query (retrieve top_k chunks)
    DB-->>PHP Orchestrator: return chunks & metadata (Node 1)
    PHP Orchestrator->>DB [(SQLite Node 2)]: Semantic query (retrieve top_k chunks)
    DB-->>PHP Orchestrator: return chunks & metadata (Node 2)
    Note over PHP Orchestrator: Compiles federated context from all nodes
    PHP Orchestrator->>Python Daemon: Synthesis Query (First Node Orchestrator)
    Python Daemon-->>PHP Orchestrator: Synthesized Cross-Reasoning response
    PHP Orchestrator->>User: Displays integrated comparative answer

1. Federated Ingestion: The Orchestrator receives the query and splits it across the selected target nodes.
2. Parallel Retrieval: Each node executes its local semantic search (via SQLite and its local vector embeddings index) to retrieve the top k chunks along with file metadata.
3. Context Compilation: The Orchestrator collects all responses, formats them into a single, clean markdown context block, and prefixes it with node origins.
4. Unified Synthesis: The query is dispatched to the background Senior Analyst daemon of the primary node with the complete federated context to synthesize a unified response.