Eirika-270M Hybrid

A compact, tool-oriented language model with a deterministic mathematical evidence-ranking component.

Eirika-270M Hybrid is an experimental, locally deployable assistant built on Google's Gemma 3 270M Instruct. It is fine-tuned to choose structured read-only tools, work with retrieved text, return concise evidence-grounded answers with source identifiers, and abstain when evidence is absent or contradictory.

This repository contains the fully merged BF16 model weights—not an adapter-only checkpoint—plus the tokenizer, a frozen mathematical retrieval module, and an example read-only tool host. The model and retrieval module work together at the application level; the mathematical circuit is not embedded in the transformer layers.

Research status: This is a first public experimental release, not a general-purpose reasoning model or a verified source of factual, medical, laboratory, legal, or safety-critical advice. The strongest reported evaluations use author-generated synthetic data; evaluate on your own documents before relying on it.

Model repository · Base model · Gemma Terms of Use

At a glance

Why Eirika?

A small local model does not need to answer every question from its internal weights. Eirika explores a narrower alternative: understand the user's request, request relevant evidence through tools, and answer only when that evidence supports a response.

The project grew out of research into mathematically constructed, zero-training neural circuits for matching, copying, statement memory, and retrieval. Those experiments established that specific computations can be engineered directly, but did not produce a broadly capable language model. Eirika combines a pretrained, fine-tuned language model with a new, explicitly fixed mathematical evidence-ranking component. This is a system-level hybrid, not a claim that Gemma's attention weights have been mathematically reconstructed.

Intended uses

• Routing simple user requests to a small, defined set of tools.
• Searching and reading approved local reference folders.
• Extracting short answers from supplied snippets with explicit source IDs.
• Abstaining on missing or contradictory evidence.
• Research into small-model tool use, mathematical retrieval, and hybrid ablation experiments.

Not intended for: unrestricted autonomous agents, executing shell commands, unreviewed professional decisions, guaranteed citation correctness, or reliable open-domain question answering without evidence.

How the hybrid works

User request
    |
    v
Fine-tuned Gemma 3 270M  -- JSON tool proposal -->  Host validator
                                                       |
                                                  Read-only tool
                                               (files / optional web)
                                                       |
                                               Retrieved source text
                                                       |
                     +---------------------------------+
                     |
              FixedEvidenceCircuit
             (deterministic ranking)
                     |
        Ranked source IDs + source excerpts
                     |
                     v
           Fine-tuned Gemma 3 270M
          JSON answer + source IDs
                     |
             Host citation validation
                     |
            Answer or safe abstention

The frozen circuit tokenises text, removes a small set of stopwords, hashes each remaining token into one of 256 fixed dimensions, and uses an identity projection with normalised dot-product similarity to rank candidate evidence. This ranking is lexical, not learned semantic understanding. Hash collisions, paraphrases, long documents, and distractors can affect its relevance scores.

The model receives both source excerpts and a ranked list of source IDs. The circuit does not generate the answer, prove factual correctness, or dynamically modify Gemma's weights. The host independently checks tool schemas, approved file boundaries, and whether citations refer to supplied source IDs. Citation membership checking is not factual entailment verification.

Getting started

Requirements

Python 3.10+ and a compatible PyTorch/Transformers environment are recommended. The included requirements.txt documents the dependencies used by the example runtime:

pip install "torch>=2.6" "transformers>=5.17,<6" "huggingface_hub>=1.32,<2" safetensors pypdf python-docx

For CUDA inference, use BF16, not FP16, when your GPU supports it. FP16 produced non-finite logits during release validation; BF16 was successfully saved, reloaded, and tested. CPU inference can use FP32. The repository's initial eirika_quickstart.py selects FP16 on CUDA, so change that one dtype to torch.bfloat16 before using it on a CUDA GPU (or use the BF16-safe example below).

1. Load the merged model

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM

REPO = "EphAsad/Eirika-270M-Hybrid"
device = "cuda" if torch.cuda.is_available() else "cpu"
dtype = torch.bfloat16 if device == "cuda" else torch.float32

tokenizer = AutoTokenizer.from_pretrained(REPO)
model = AutoModelForCausalLM.from_pretrained(
    REPO,
    dtype=dtype,
    attn_implementation="sdpa",
).to(device).eval()

print("Loaded standalone merged Eirika weights:", device, dtype)

This loads the merged language model and does not require PEFT. To reproduce the full hybrid assistant, also load eirika_hybrid.py and use its FixedEvidenceCircuit, prompting utilities, and validated tool host.

2. Download the runtime and try a read-only local folder

from huggingface_hub import hf_hub_download

for filename in ("eirika_hybrid.py", "eirika_quickstart.py"):
    hf_hub_download(
        repo_id="EphAsad/Eirika-270M-Hybrid",
        filename=filename,
        local_dir=".",
    )

Create a folder named approved_docs containing your non-sensitive test Markdown or text files. Then run:

# On CUDA, first change the quickstart's torch.float16 choice to torch.bfloat16.
python eirika_quickstart.py \
  --repo EphAsad/Eirika-270M-Hybrid \
  --folder ./approved_docs \
  --question "Find the documented incubation temperature in my notes"

The example will print its tool proposal, host execution status, evidence-backed response (if any), and source-ID validation. This is a research demo, not a hardened multi-user document service. Internet access is disabled in this quickstart.

3. Use the mathematical circuit directly

from eirika_hybrid import FixedEvidenceCircuit

circuit = FixedEvidenceCircuit()
evidence = [
    {"source_id": "notes.md#L1", "text": "Orion Harbor has capacity of 42 slots."},
    {"source_id": "notes.md#L2", "text": "Lunar Exchange has duration of 9 weeks."},
]

print(circuit.rank("What is Orion Harbor's capacity?", evidence))

The returned values are ranked source IDs and similarity scores, not answers. The example names and figures above are fictional.

Interaction contracts

Eirika is fine-tuned for two explicitly prompted modes. A host application must select the mode, validate generated JSON, execute permitted tools, and supply evidence for the answer step. A bare text-generation call is not a complete agent runtime.

ROUTE mode:

{"tool":"search_documents","arguments":{"query":"Orion Harbor capacity"}}

The supported tool signatures are:

ANSWER mode, evidence supported:

{
  "status": "answered",
  "answer": "Orion Harbor has capacity of 42 slots.",
  "citations": ["fictional/orion_harbor.md#L4"]
}

ANSWER mode, evidence absent or contradictory:

{
  "status": "abstain",
  "answer": "Insufficient verified evidence.",
  "citations": []
}

Citation identifiers are provided by the tool host; the model should not invent them. The sample responses are illustrative, not a claim of flawless performance.

Training

The public release was fine-tuned from google/gemma-3-270m-it on an NVIDIA A100 using BF16 LoRA. The LoRA configuration targeted attention projections (q_proj, k_proj, v_proj, o_proj) and MLP projections (gate_proj, up_proj, down_proj), using rank 16. The selected run used two epochs, batch size 4, gradient accumulation 4, learning rate 1.5e-4, cosine scheduling, and validation-loss-based checkpoint selection.

The training set contained 2,400 synthetic examples, with 240 validation and 240 separate, topic-disjoint held-out examples. Assistant JSON completions, rather than user prompts, contributed to the supervised training loss. The training limit was 1,024 tokens, considerably shorter than the model's full architectural context capacity.

Training examples covered routing, document search, file reads, web-tool selection, supported evidence, missing information, and contradictory evidence. All generated project names, filenames, and measurements used for fine-tuning were fictional. The synthetic training records and local training logs are not part of the public model repository.

After selecting the best checkpoint, the LoRA updates were combined with the base model in FP32 and exported as a standalone BF16 Safetensors checkpoint. The export was verified by checking 126 LoRA-adapted layers against their expected fused weight updates, checking unaffected tensors, confirming finite BF16 logits, and verifying that every saved tensor reloaded exactly. The repository ships the merged weights, not a LoRA adapter.

Evaluation

Internal synthetic holdout

The following are measured internal diagnostics from the executed release notebook. They use author-generated fictional examples and should not be interpreted as independent benchmark scores or real-world reliability guarantees.

The evidence-ranking ablation suggests that the ranked-ID hint helped on those 12 synthetic prompts, but it does not isolate the mathematical circuit from other retrieval methods or establish a general advantage over conventional search. In particular, a no-hint condition is not a comparison with a tuned lexical or embedding retriever.

Known failures and caveats

• End-to-end supported evidence: In one local-file demonstration, the tool correctly retrieved a supporting line, but Eirika abstained instead of answering.
• Long-context sensitivity: The early-evidence placement failed in one approximately 7,800-token prompt; middle and late placements passed. This does not demonstrate dependable 8K reasoning.
• Synthetic-data generalisation: Many evaluation examples share the structured task style of training. Broader paraphrases, unfamiliar documents, and unanticipated tasks require independent testing.
• Citation fidelity: A citation can point to a supplied source ID without proving the answer is actually supported by its text.
• Tool use: The model proposes actions; an external application is responsible for tool execution, authentication, network policy, and access control.
• Small-model capacity: Complex synthesis, extensive reasoning, messy documents, and multi-step workflows may fail or produce inappropriate abstentions.

For deployment, evaluate answer correctness and abstention on your own representative documents, inspect failure cases, and add robust source-entailment and permission checks.

Repository files

No training dataset, local private documents, authentication tokens, training logs, notebook outputs, or adapter-only checkpoints are intended to be included in the release.

Safety and privacy

The bundled host limits local access to an approved directory, checks relative paths and file types, and rejects invalid tool schemas. Web access requires a separately configured provider; none is enabled by default. The included optional Wikipedia provider is restricted and is not an unrestricted browsing service.

Retrieved documents and webpages are untrusted content, not instructions to the model or host. The implemented checks reduce some failure modes, but they do not guarantee resistance to prompt injection, factual hallucination, data disclosure, or incorrect tool decisions. For sensitive or operational use, add stronger policy enforcement, source verification, and human review.

This release uses synthetic fictional fine-tuning examples. Do not upload confidential source documents to public repositories when adapting the runtime to your environment.

Roadmap

Areas for future work include stronger grounded answering when sources are present, lower unnecessary abstention, independent evaluation on unfamiliar documents, more robust long-context retrieval, BF16-safe quickstart updates, and direct comparisons between fixed mathematical retrieval, conventional lexical retrieval, and embedding-based ranking. Future adapter-integration experiments will need explicit evidence that the engineered components improve the learned model.

Licence, attribution, and notices

Eirika-270M Hybrid is a modified derivative of google/gemma-3-270m-it, developed by Google. Its redistribution and use are governed by the Gemma Terms of Use and the applicable Gemma Prohibited Use Policy, not the Apache 2.0 or MIT model licences. Review the included GEMMA_TERMS.txt, NOTICE, and USE_RESTRICTIONS.txt files before redistribution or deployment.

The original Gemma model is provided by Google. Eirika's fine-tuning, external mathematical evidence-ranking implementation, tool-use workflow, and release tests are additional work in this derivative project. The name Eirika-270M Hybrid does not imply endorsement by Google or Hugging Face.

Citation

If you reference this release, please link to the model repository:

Eirika-270M Hybrid v1.0. https://huggingface.co/EphAsad/Eirika-270M-Hybrid

Thank you for exploring Eirika. Feedback, reproducible tests, and detailed failure reports are welcome.