The harness, engine, and model

Fella separates model judgment from application control and data execution.

Definition

Fella has three cooperating parts:

Part	Responsibility
Model	Proposes tool calls and writes the response
Harness	Builds context, exposes tools, runs the loop, records evidence, and finishes the answer
Engine	Catalogs files and implements local SQL, document, Python, chart, and verification operations

The separation keeps providers replaceable and puts tool execution outside the model request.

Architecture

question + context
        |
        v
  +-----+------+       +----------------+
  |  Harness   |<----->| Model provider |
  +-----+------+       +----------------+
        |
   tool calls
        v
  +-----+------+     +----------------+
  |  Registry  |---->| Analytics      |
  +-----+------+     | engine         |
        |            +-------+--------+
        |                    |
        +--------> ToolOutput/results
                         |
                         v
                      Evidence
                         |
                         v
                      Verification

The model receives text context, tool schemas, and returned tool results. It does not receive a database handle or a general application API. The harness is the only path from model tool calls to the registered implementations. The registry turns a tool result into an evidence item; the analytics engine itself returns computation, not evidence.

Flow

The engine scans an open folder and prepares a catalog and queryable tables.
The harness combines that schema with the question, conversation context, fella.md, and folder memory.
The selected model either answers or proposes one or more tool calls.
The harness executes registered calls and records their results as evidence.
The loop repeats until the model answers or a stop condition is reached.
Deterministic verification runs before the completed answer is emitted. Some warnings can also trigger an optional, tool-free model second opinion.

Behavior

The engine does not call an LLM and is exposed to analytics code through a narrow AnalyticsSource trait. The Svelte frontend is a client of the Rust/Tauri backend: it sends commands, streams events, and renders answers, evidence, tabs, and controls. The standard registry contains seven fixed built-in tools. There is no runtime connector or plugin expansion path in the personal release.

The narrow engine seam

The verifier does not receive the whole application state. It receives only the catalog and read-only SQL capability it needs:

pub trait AnalyticsSource {
    fn catalog(&self) -> Catalog;
    fn run_sql(&self, sql: &str) -> EngineResult<QueryResult>;
}

EngineState implements this trait by delegation. That keeps verification independent of Tauri commands, credentials, conversation state, and the model provider. See the engine implementation and the state adapter.

Ownership map

Concern	Current owner	Boundary
Prompt, model turns, stopping, cancellation	`agent.rs`	Does not implement SQL, parsing, or statistics
Built-in and runtime tool dispatch	`tools.rs`	Converts tool output into the shape the harness records
Catalog and data access	`analytics/data/` and `catalog.rs`	Does not call an LLM
Evidence and streamed answer contract	`evidence.rs`	Serializes results for the Svelte client
Post-answer checks	`analytics/verify.rs`	Checks recorded work; does not prove intent

For the user-facing version of this flow, see read the evidence. For provider and Python network boundaries, see privacy and security.

Limits

The model can still choose the wrong query or misread an ambiguous question.
Deterministic verification checks evidence consistency and known query patterns; it does not prove the user’s intended meaning.
The SQL and document paths are bounded and read-only. run_python uses the same host-side data boundary from an embedded WASM guest; it has no filesystem, network, environment, or subprocess capability and is bounded by Wasmi resource limits.
A hosted model provider sees the prompt and tool results sent to it. The inert /mcp command makes no separate network request.

Next steps

Follow the loop

See how context, tool calls, stopping, and verification fit together.

Inspect the engine

See how files become local tables, documents, and evidence.

Inspect the tools

Review the seven fixed built-ins and their execution boundaries.

Choose a model

Review provider protocols, credentials, and network boundaries.

How Fella works

Trust and correctness

The harness, engine, and model

Definition

Architecture

Flow

Behavior

The narrow engine seam

Ownership map

Limits

Next steps

Follow the loop

Inspect the engine

Inspect the tools

Choose a model

​Definition

​Architecture

​Flow

​Behavior

​The narrow engine seam

​Ownership map

​Limits

​Next steps

Follow the loop

Inspect the engine

Inspect the tools

Choose a model

Definition

Architecture

Flow

Behavior

The narrow engine seam

Ownership map

Limits

Next steps