CyberShield-Gemma-4B-v2

A fine-tuned Gemma 3 4B adapter for natural-language-to-software-architecture generation in CyberShield-Arch. This is the v2 successor to earnest-s/CyberShield-Gemma-4B, retrained on a canonicalized target representation that makes structural fidelity measurable and learnable.

This is an experimental research/project-demonstration model. It is not production-certified.

Model Description

• Base model: unsloth/gemma-3-4b-it-bnb-4bit (Gemma 3 4B, 4-bit NF4 quantized, frozen) — taken from this adapter's adapter_config.json
• Adapter type: LoRA (PEFT), causal language modeling, r = 24 / alpha = 48 / dropout 0.05 (from adapter_config.json)
• Input: natural-language software architecture requirements
• Output: structured architecture representation — a JSON object with nodes, edges, and architecture metadata:

{
  "nodes": [{ "id": "service-1", "type": "service" }],
  "edges": [{ "source": "ui-1", "target": "service-1", "label": "HTTP" }]
}

Training representation (what changed vs v1)

The v2 training targets use a canonicalized representation:

• Type-anchored canonical node identifiers: {type}-{k} (e.g. ui-1, service-2, database-1), assigned deterministically from the graph itself. Node-id vocabulary collapses from ~28,703 arbitrary names to 45 canonical ids.
• Deterministic ordering: nodes emitted in (type, id) order; edges sorted by (source, target, label) — 100% of targets deterministically ordered (vs 0–3% in v1).
• Single consistent contract: prompt, targets, and runtime validator all enforce ≤10 nodes / ≤15 edges (v1 prompts said max 8/10 while 97% of targets had 10 nodes).
• Every record preserves provenance: a reversible id_map (canonical id → original id) plus the original architecture are retained in the dataset metadata.

Intended Use

• Research/project demonstrations of representation-driven fidelity improvement in natural-language → architecture-graph generation.
• Producing structurally valid, well-sized architecture drafts for human review in an interactive editor.
• Not intended for production planning, security-critical decisions, or any use requiring exact reproduction of a specified architecture.

Training

• Data: CyberShield_Gemma_SFT_v2_canonical — 51,498 records derived from real architectures (ajibawa-2023/Technical-Architectures-Large via the CyberShield-Arch pipeline); split 46,348 train / 2,575 validation / 2,575 test (held out).
• 1 epoch, 5,793 optimizer steps, 12,109,238 tokens, seed 42.
• Train loss 0.0993 avg (final step 0.0903); validation loss 0.0866.
• Peak VRAM 3.52 GiB on a single RTX 4050 Laptop GPU; base loaded 4-bit NF4; 8-bit AdamW lr 2e-4, cosine schedule, prompt-masked chunked cross-entropy, max_length 1024 with zero truncation (longest sequence 594 tokens).

Evaluation

Measured on the untouched 2,575-record test split using a corrected non-truncating evaluation methodology (targets compared verbatim, never passed through size-capping parsers):

Metric	V1 baseline	V2
Node F1	0.237	~0.80
Edge F1	0.069	0.656
Structure-exact	0%	0.08% (2/2575)
Repetition failure	0	0
Generated node count	~10.01 avg	exactly 10 for 2575/2575

Metric precision: structure-exact means the generated graph matches the target's component-type inventory and edge structure exactly. It is NOT name-level exact match — name-level exact match (exact node-id strings) remains 0% in both models. Node F1 here is computed against canonical ids, which measures type-inventory fidelity rather than reproduction of arbitrary original component names.

Runtime contract: ≤10 nodes / ≤15 edges; the integrated runtime returns v2 graphs untruncated (runtime truncation rate 0 after contract alignment).

Limitations

• Name-level exact match remains 0% — the model does not reproduce arbitrary original component names (by design of the canonical representation).
• Structure-exact remains very low at 0.08% (2/2575) — exact whole-graph structural reproduction is not achieved; treat it as informational only.
• Domain is software architecture graphs only; narrow, purpose-built dataset.
• This is a project/research demonstration model, not production-certified; outputs require human review and must not drive security-critical or planning decisions.
• The adapter requires the compatible Gemma base model (unsloth/gemma-3-4b-it-bnb-4bit) and a CUDA-capable GPU; it is weights-only (no tokenizer/config of its own beyond PEFT config).
• The runtime expects the validated ≤10-node / ≤15-edge contract; graphs outside these limits fail explicit validation rather than degrade silently.
• Canonical node ids (service-1, ui-2, …) are display labels; mapping back to semantic component names requires the per-record id map kept in the project dataset.

Licensing

No license has been established for this adapter (license: unknown). The base model unsloth/gemma-3-4b-it-bnb-4bit is subject to its own upstream terms (Google Gemma license as distributed by the unsloth repository). The training data derives from ajibawa-2023/Technical-Architectures-Large; see that dataset's terms. Use of this adapter is additionally subject to the Gemma Terms of Use inherited from the base model.

Inference Example

import torch
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

base_id = "unsloth/gemma-3-4b-it-bnb-4bit"
adapter_id = "earnest-s/CyberShield-Gemma-4B-v2"

tokenizer = AutoTokenizer.from_pretrained(base_id)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

bnb = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_quant_type="nf4",
                         bnb_4bit_compute_dtype=torch.float16)
model = AutoModelForCausalLM.from_pretrained(base_id, device_map="auto",
                                             quantization_config=bnb)
model = PeftModel.from_pretrained(model, adapter_id)
model.eval()

prompt = """You are a senior software architect.

Convert the following system description into a CLEAN architecture graph.

FORMAT:
{
    "nodes": [
        {"id": "ui-1", "type": "ui"},
        {"id": "service-1", "type": "service"}
    ],
    "edges": [
        {"source": "ui-1", "target": "service-1", "label": "HTTP"}
    ]
}

CONSTRAINTS:
- Max nodes: 10
- Max edges: 15

Description:
A web frontend calls an API gateway that routes to order and payment services backed by PostgreSQL.

ONLY return JSON. No explanation.
"""

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
out = model.generate(**inputs, do_sample=False, repetition_penalty=1.1,
                     max_new_tokens=512)
print(tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))

Project

Part of ArchitectAI / CyberShield-Arch — a local-first architecture generation and editing workspace (FastAPI + React/React Flow) with a staged dataset pipeline and a production security engine. Companion repositories/models: earnest-s/CyberShield-Gemma-4B (v1).