Specialized Brains: Pluggable Capabilities

ANDARTIS rejects the "one-size-fits-all" model approach. Instead, it utilizes a modular system of pluggable Capabilities (referred to as Brains) running locally via a resident daemon.

---

Why Specialized Brains?

• Deterministic Execution (Symbolic): Standard LLMs struggle with math and exact counts. We use symbolic query engines for database operations to ensure 100% accuracy.
• Resource Efficiency: Our micro-architectures require very little RAM and execute in milliseconds on the Apple Neural Engine (ANE).
• Persistent State: Models are kept in memory within the background process, avoiding the latency overhead of reloading weights on every prompt.

---

Core Capability Matrix

Brain	Core Architecture	Best Suited For
Senior Analyst	Local SLM (Mistral/Llama)	Conversational reasoning, intent parsing, and grounded context synthesis.
Pattern Synthesizer	Micro-Transformer (Style Forge)	Re-writing and drafting content in a user's specific voice/style.
Semantic Navigator	Siamese Transformer (MLX)	Fast text embedding generation and vector similarity search.
Entity Analytic	Symbolic Database Aggregator	Schema extraction, counts, sums, and table listings.

---

The Model Weaver Paradigm

Rather than exposing raw models directly to users, ANDARTIS uses them as steps in a structured pipeline:

[User Query] ──> [Intent Blade]
                      │ (Determines Strategy)
                      ▼
             [Semantic Navigator] (Ranks 10,000+ files to top 5)
                      │
                      ▼
             [Senior Analyst] (Synthesizes top 5 into response)

1. Filtering: The Semantic Navigator performs metadata filters to isolate relevant files in milliseconds.
2. Ranking: The Navigator ranks candidates using MLX embeddings.
3. Synthesis: The Senior Analyst synthesizes the ranked context.

---

Deep Dive: Entity Analytic (Symbolic Core)

While neural brains (like the Senior Analyst and Semantic Navigator) excel at natural language understanding and search, they struggle with precise mathematical calculations, counts, and statistical listings. The Entity Analytic acts as a deterministic, symbolic query engine built directly on the node's SQLite database.

Document-Level Grounding vs. Chunk Counting

A common issue in RAG architectures is that queries asking "what is the most common..." or "how many patients have..." return the number of matching text chunks instead of the number of actual documents. Since documents are divided into multiple overlapping chunks during ingestion, counting chunks exaggerates the true document frequency.

To prevent this, Entity Analytic implements strict Document-Level Grounding:

• Training & Indexing: During node ingestion/training, it reads metadata schemas from the documents table (using self.get_documents()) rather than the document_chunks table.
• Symbolic Entity Reconciliation: It parses all metadata variables (e.g. Patient Information -> Full Name, Diagnosis, ASCVD Risk), reconciles lists or dictionaries, and compiles a comprehensive, de-duplicated frequency_map.

Guiding the Senior Analyst

When a user asks a quantitative question, the Intent Blade routes the query to Entity Analytic. The capability executes matching query scenarios:

1. Aggregations: Sorts and caps frequencies, compiling a top_frequencies block.
2. Exact Key-Value Filtering: Counts documents matching precise metadata criteria.
3. List Queries: Returns structured outputs containing all matching items.

The structured JSON containing total_documents, top_frequencies, and exact counts is returned to the Senior Analyst (SLM) to guide conversational synthesis, ensuring the final text response is 100% mathematically accurate.

---

Creating a Custom Capability

Developers can build and register custom brains by following three steps:

1. Define the Python Logic

Create a capability script that inherits from BaseCapability. All brains share the Mistral tokenizer for token alignment.

from .base import BaseCapability

class CustomAnalyticsBrain(BaseCapability):
    def __init__(self, node_id, node_path=None, project_root=None, node_name=None, node_config=None, slug=None):
        super().__init__(node_id, node_path, project_root, node_name, node_config, slug=slug)

    def train(self, data, params):
        # Runs during ingestion (e.g., training custom adapters or building indices)
        pass

    def interact(self, query, context):
        # Called when the orchestrator forwards a query
        return {"result": "Analyzed content."}

2. Register the Backend Service

Register your capability slug and script path in the Laravel registry (App\Services\CapabilityRegistry):

[
    'name' => 'Custom Analytics',
    'slug' => 'custom-analytics',
    'type' => 'neural',
    'manifest' => [
        'worker' => 'capabilities/custom_analytics.py',
        'ui' => 'CustomAnalyticsWidget'
    ]
]

3. Implement the UI Widget

Create a matching Vue component (e.g., CustomAnalyticsWidget.vue) in resources/js/Components/Widgets/ to render the brain's custom visual outputs.