Upload README.md

README.md

@@ -1,323 +1,387 @@
 ---
+library_name: transformers
+pipeline_tag: text-generation
 license: other
+base_model:
+  - Qwen/Qwen3.6-27B
 language:
-- en
-pipeline_tag: text-generation
+  - en
 tags:
-- code
-- coding-agent
-- software-engineering
-- harness-engineering
-- weight-agnostic
-- veriloop
-pretty_name: VeriLoop Coder E1
-library_name: transformers
+  - safetensors
+  - qwen3_6
+  - qwen
+  - code
+  - coding-agent
+  - software-engineering
+  - harness-engineering
+  - agentic-coding
+  - repository-understanding
+  - tool-use
+  - evidence-binding
+  - rollback
+  - uncertainty-calibration
+  - veriloop
+  - weight-agnostic
 ---
 
-# VeriLoop Coder E1
+# VeriLoop Coder-E1
 
-**VeriLoop Coder E1** is a coding model program designed for real-world software engineering tasks, repository-scale problem solving, and benchmark-oriented code generation workflows.
+**VeriLoop Coder-E1** is an open-weight coding model release built on a Qwen3.6-27B backbone and aligned for harness-driven software engineering workflows.
 
-Rather than being tied to a single fixed checkpoint, VeriLoop Coder E1 is built as a **weight-agnostic coding system**: it is designed to continuously improve as stronger open-weight foundations become available. Its core goal is straightforward:
+This release is designed for developers and researchers who want a coding model that is not only fluent at code generation, but also more prepared for tool-mediated, evidence-aware, rollback-safe, and uncertainty-calibrated coding pipelines.
 
-- deliver stronger coding performance than the underlying base model,
-- scale from local development to evaluation-heavy engineering workflows,
-- remain adaptable across different open-weight backbones,
-- and provide a stable path toward increasingly capable front-end programming applications.
+VeriLoop Coder-E1 is released as a two-layer public package:
 
-VeriLoop Coder E1 is intended for developers, researchers, and product teams who need a coding system that can do more than produce snippets. It is designed to support complete engineering loops such as repository understanding, scoped editing, patch generation, validation-aware iteration, and task-oriented development.
+1. **Backbone weights** in the repository root, stored in standard `safetensors` sharded format.
+2. **Four public PEFT adapters** for coding-agent behavior shaping:
+   - `toolspec_adapter/adapter`
+   - `uncertainty_adapter/adapter`
+   - `rollback_adapter/adapter`
+   - `evidence_adapter/adapter`
 
-> **Positioning**  
-> VeriLoop Coder E1 is built to compete with frontier-style coding assistants and to push beyond strong open coding baselines through continual harness upgrades, better workflow alignment, and more robust engineering execution.
+The public release follows the standard Hugging Face / PEFT adapter format. Internal production runtime components, private runtime heads, training data, logs, and orchestration code are not included in this public model card.
 
 ---
 
 ## Highlights
 
-- **Repository-aware coding**
-  - Designed for multi-file projects, codebases with existing structure, and engineering tasks that require context beyond a single prompt.
+VeriLoop Coder-E1 is optimized for coding-agent workloads where a model must interact with tools, interpret validation signals, manage uncertain states, and produce safer revisions under runtime constraints.
 
-- **Task-oriented software work**
-  - Supports bug fixing, feature implementation, refactoring, code completion, test-oriented revision, and structured patch generation.
+Key capability directions include:
 
-- **Weight-agnostic evolution**
-  - The system is not bound to one permanent weight release. As stronger open models emerge, VeriLoop Coder E1 is intended to inherit stronger foundations while preserving the same product direction.
+- **Harness-ready coding behavior** — trained to operate cleanly inside external coding runtimes, validators, tool routers, and repair loops.
+- **Tool-spec awareness** — improves obedience to tool-call schemas, preconditions, postconditions, and execution-facing instruction formats.
+- **Evidence-bound reasoning style** — encourages stronger alignment between claims, code changes, validation signals, and supporting context.
+- **Rollback and revision discipline** — improves behavior around failed edits, validator feedback, worktree-sensitive repairs, and bounded correction loops.
+- **Uncertainty calibration** — improves routing signals for answer uncertainty, evidence gaps, execution necessity, specification mismatch, and risk pressure.
+- **Repository-scale workflow orientation** — intended for code understanding, patch drafting, iterative debugging, and agentic software engineering tasks.
+- **Open standard artifacts** — released with `safetensors` backbone weights and PEFT-compatible adapter checkpoints for reproducible public loading.
 
-- **Harness-first performance strategy**
-  - Emphasizes system-level coding performance, workflow consistency, and practical execution quality rather than relying only on model size.
+VeriLoop Coder-E1 should be viewed as a **coding model foundation for harness-centric systems**, not as a complete hosted agent product by itself.
 
-- **Built for iterative engineering**
-  - Intended to work well in repeated development loops: inspect, modify, validate, revise, and complete.
+---
 
-- **Practical deployment flexibility**
-  - Suitable for local development, private infrastructure, evaluation pipelines, and future productized programming applications.
+## Release Scope
 
----
+### Included in this public release
 
-## What VeriLoop Coder E1 Can Do
+- Qwen3.6-27B-compatible model files in the repository root.
+- Standard `safetensors` model shards.
+- Tokenizer and generation configuration files.
+- Four public PEFT adapters:
+  - ToolSpec adapter
+  - Uncertainty adapter
+  - Rollback adapter
+  - Evidence Binding adapter
+- Public adapter manifests and metric summaries.
 
-### 1. Repository Understanding
-VeriLoop Coder E1 is designed to work at the repository level rather than only at the single-file level. It can be used to:
+### Not included in this public release
 
-- inspect project structure,
-- identify relevant files for a task,
-- follow dependencies across modules,
-- trace implementation paths,
-- and narrow work to the most relevant regions of a codebase.
+- Private runtime heads.
+- Internal harness orchestration code.
+- Training JSONL files and evaluation JSONL files.
+- Internal logs, checkpoints, optimizer states, and scheduler states.
+- Private routing, sandbox, memory, evidence-gate, or production-serving logic.
 
-This makes it suitable for engineering tasks where the answer depends on how a repository is actually organized, not just on generic programming knowledge.
+This separation is intentional: the public repository provides standard model assets, while production-grade agent behavior may require a full runtime system around the model.
 
-### 2. Code Generation and Editing
-VeriLoop Coder E1 is designed for:
+---
 
-- generating new code from natural language requirements,
-- editing existing code with scoped changes,
-- implementing new functions or modules,
-- updating interfaces and internal logic,
-- and producing patches that fit an existing repository style.
+## Model Overview
 
-Its intended behavior is not merely to “write code,” but to support code changes that are better aligned with the target project.
+| Property | Value |
+|---|---|
+| Model family | VeriLoop Coder-E1 |
+| Backbone | Qwen3.6-27B-compatible backbone |
+| Public release type | Open-weight backbone + PEFT adapters |
+| Primary domain | Coding, software engineering, coding-agent workflows |
+| Weight format | `safetensors` |
+| Adapter format | PEFT / LoRA-style adapter checkpoints |
+| Runtime target | Harness-driven coding systems, tool-mediated agents, repository workflows |
 
-### 3. Bug Fixing and Debug Support
-The system is suitable for issue-driven development workflows, including:
+The backbone inherits the long-context and coding-oriented capabilities of Qwen3.6-27B. The VeriLoop release adds four focused public adapters for agentic coding alignment, while keeping the public artifact format compatible with standard Hugging Face tooling.
 
-- locating likely sources of failure,
-- proposing corrective edits,
-- narrowing down error-prone code paths,
-- revising earlier patches,
-- and helping complete fix-and-verify cycles.
+---
 
-It is especially useful where users want assistance with actionable debugging work rather than only explanations.
+## Adapter Overview
 
-### 4. Refactoring and Codebase Maintenance
-VeriLoop Coder E1 is intended to support:
+| Adapter | Folder | Public files | Role |
+|---|---|---|---|
+| ToolSpec | `toolspec_adapter/adapter` | `adapter_config.json`, `adapter_model.safetensors` | Tool-call discipline, schema obedience, pre/postcondition sensitivity |
+| Uncertainty | `uncertainty_adapter/adapter` | `adapter_config.json`, `adapter_model.safetensors` | Runtime uncertainty calibration across answer, evidence, execution, spec, and risk signals |
+| Rollback | `rollback_adapter/adapter` | `adapter_config.json`, `adapter_model.safetensors` | Validator-aware repair behavior, rollback discipline, bounded revision control |
+| Evidence Binding | `evidence_adapter/adapter` | `adapter_config.json`, `adapter_model.safetensors` | Stronger alignment between claims, evidence, provenance, and validation context |
 
-- function and class cleanup,
-- repeated-pattern reduction,
-- naming and structure improvement,
-- interface consistency updates,
-- and maintenance work across related files.
+Each adapter is published independently. Users can load one adapter at a time for focused experimentation, or build their own runtime policy for adapter selection and orchestration.
 
-This makes it useful for engineering teams that want help with code quality work, not only greenfield generation.
+---
 
-### 5. Test-Oriented Development Workflows
-The system is designed to contribute to development flows where testing matters. It can support:
+## Quickstart
 
-- generating test candidates,
-- revising code after failed checks,
-- improving implementation to meet expected behavior,
-- and iterating toward completion under validation pressure.
+### Install
 
-This makes it more suitable for engineering environments than models optimized purely for chat-style coding help.
+```bash
+pip install -U transformers peft accelerate safetensors
+```
 
-### 6. Patch-Centric Delivery
-VeriLoop Coder E1 is intended to support patch-style outputs for practical software work. It can be used in settings where users need:
+For large-model inference, use an environment with adequate GPU memory and recent versions of `transformers`, `peft`, and `accelerate`.
 
-- focused edits instead of long essays,
-- repository-consistent changes,
-- smaller and more deliberate revisions,
-- and outputs that are easier to inspect, review, and apply.
+### Load the backbone
 
-### 7. Long-Horizon Task Support
-The model program is designed for multi-step software tasks that may require:
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+import torch
 
-- staged planning,
-- repeated tool use,
-- revision after intermediate outcomes,
-- and continuity across a longer engineering loop.
+repo_id = "veriloop-lab/veriloop-coder-e1"
 
-This makes it more suitable for practical coding sessions than one-turn code generation setups.
+tokenizer = AutoTokenizer.from_pretrained(
+    repo_id,
+    trust_remote_code=True,
+)
 
----
+model = AutoModelForCausalLM.from_pretrained(
+    repo_id,
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+    trust_remote_code=True,
+)
 
-## Core Product Capabilities
+model.eval()
+```
 
-### A. Coding Assistant for Real Development
-VeriLoop Coder E1 is intended to function as a professional coding assistant for:
+### Load a public VeriLoop adapter
 
-- application development,
-- backend services,
-- frontend iteration,
-- repository maintenance,
-- scripting and automation,
-- and software engineering support inside real projects.
+```python
+from peft import PeftModel
 
-### B. Evaluation-Oriented Coding System
-The system is built with benchmark-facing goals in mind. It is intended to perform well in settings that reward:
+repo_id = "veriloop-lab/veriloop-coder-e1"
 
-- correctness,
-- repository reasoning,
-- patch quality,
-- revision discipline,
-- and stable completion behavior.
+model = PeftModel.from_pretrained(
+    model,
+    repo_id,
+    subfolder="evidence_adapter/adapter",
+)
 
-### C. Foundation for a Front-End Programming Product
-VeriLoop Coder E1 is also intended to serve as the model backbone for a future programming application focused on interactive development workflows. The product direction is to deliver a coding experience that can stand alongside leading AI programming tools while remaining compatible with open-weight progress.
+model.eval()
+```
 
-### D. Reusable Coding Layer Across Backbone Upgrades
-A key feature of VeriLoop Coder E1 is continuity across weight upgrades. The product direction is not tied to a single model generation. Instead, the coding layer is designed to remain reusable as new open-weight systems improve.
+Available adapter subfolders:
 
----
+```text
+toolspec_adapter/adapter
+uncertainty_adapter/adapter
+rollback_adapter/adapter
+evidence_adapter/adapter
+```
 
-## Why This Model Exists
+### Generate
 
-Many coding systems are either:
+```python
+prompt = "Write a robust Python function that validates and normalizes a repository file path. Include a minimal self-test."
 
-- strong at raw generation but weak at repository-grounded engineering work,
-- tied too tightly to a single weight release,
-- or difficult to carry forward as the open-weight landscape changes.
+messages = [
+    {"role": "user", "content": prompt}
+]
 
-VeriLoop Coder E1 exists to provide a more durable path:
+inputs = tokenizer.apply_chat_template(
+    messages,
+    add_generation_prompt=True,
+    return_tensors="pt",
+).to(model.device)
 
-- a stable coding product direction,
-- a reusable engineering workflow layer,
-- and a model program that can keep improving as the open ecosystem advances.
+outputs = model.generate(
+    inputs,
+    max_new_tokens=2048,
+    do_sample=False,
+)
 
-The goal is not simply to release one checkpoint. The goal is to build a coding system that becomes stronger over time without losing its identity.
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
 
 ---
 
-## Harness Engineering Focus
-
-VeriLoop Coder E1 places strong emphasis on **Harness Engineering** as a product capability.
+## vLLM / Serving Notes
 
-In practical terms, this means the system is intended to work well inside disciplined coding workflows, including:
+The backbone can be served as a standard Hugging Face model in inference engines that support the underlying architecture.
 
-- structured repository inspection,
-- controlled code modification,
-- validation-aware iteration,
-- multi-step completion,
-- and consistent developer-facing behavior across different base weights.
+For LoRA adapter serving, use a serving runtime that supports PEFT/LoRA adapters and point it to one of the adapter folders after downloading the repository snapshot locally. Exact command-line flags may vary by vLLM version.
 
-For users and teams, the effect is that VeriLoop Coder E1 is designed to remain useful even as the underlying open-weight model changes. The coding experience is meant to become stronger through system improvement, not only through swapping in a larger checkpoint.
+A typical deployment pattern is:
 
-This is one of the defining characteristics of the VeriLoop Coder line:  
-**the model family is designed to improve with the open-weight frontier rather than freeze around a single permanent base model.**
+1. Serve the backbone model from the repository root.
+2. Mount one VeriLoop PEFT adapter as a LoRA module.
+3. Route requests to the adapter that matches the task profile.
+4. For production coding agents, add external validation, sandboxing, and tool orchestration outside the model.
 
 ---
 
-## Intended Use
+## Recommended Use Cases
 
-VeriLoop Coder E1 is intended for:
+VeriLoop Coder-E1 is intended for:
 
-- software engineering assistance,
-- repository-scale coding tasks,
-- code generation and modification,
-- benchmark-oriented coding evaluation,
-- developer workflow augmentation,
-- research on open-weight coding systems,
-- and future product deployment in programming tools.
+- Repository understanding and codebase navigation.
+- Patch drafting and bounded code revision.
+- Tool-mediated coding workflows.
+- Validator-aware debugging loops.
+- Evidence-aware code explanation.
+- Coding-agent research and runtime integration.
+- Experiments with uncertainty-aware code generation.
 
-Typical scenarios include:
-
-- fixing issues in an existing repository,
-- implementing requested functionality,
-- proposing code changes under project constraints,
-- generating or refining tests,
-- reviewing and improving patch candidates,
-- and supporting repeated engineering loops over time.
+It is especially suitable for users building coding systems where the model is paired with an external runtime, tool layer, validator, or repository-aware workflow.
 
 ---
 
-## Out-of-Scope Use
+## Limitations
 
-VeriLoop Coder E1 is **not** intended as:
+This public release is not a full hosted coding agent. It does not include VeriLoop's private production runtime, private custom heads, sandbox execution system, memory service, evidence gateway, or internal orchestration policies.
 
-- a guarantee of correct code without review,
-- a replacement for secure software practices,
-- a substitute for human approval in high-stakes production environments,
-- or a universal reasoning system for non-coding tasks.
+Important limitations:
 
-It should be treated as a coding system that assists software work, not as an autonomous authority.
+- The public adapters provide model-level alignment signals, not a complete execution environment.
+- Users should validate generated code before using it in production.
+- Repository-scale behavior depends heavily on retrieval, context construction, and tool execution outside the model.
+- Adapter composition should be tested carefully; do not assume that naively merging or stacking all adapters is optimal for every task.
+- Public benchmark results for this release will be updated after standardized external evaluation.
 
 ---
 
-## Current Strength Profile
+## Evaluation Status
+
+Public benchmark results are not yet included in this release.
 
-VeriLoop Coder E1 is particularly oriented toward the following strengths:
+The current repository is a public model-asset release focused on:
 
-- repository-aware engineering workflows,
-- task-focused code modification,
-- revision after intermediate feedback,
-- stable coding assistance across changing weights,
-- and practical software delivery behavior over one-shot demo behavior.
+- Standard weight availability.
+- Adapter availability.
+- Reproducible loading.
+- Harness-oriented coding model alignment.
 
-The project is especially relevant for users who care about **engineering usefulness**, **benchmark performance**, and **long-term upgradeability**.
+External leaderboard and benchmark results will be added after controlled evaluation on standardized coding and agentic software-engineering benchmarks.
 
 ---
 
-## Limitations
+## Safety and Responsible Use
 
-As with other open-weight coding systems, performance may vary depending on:
+VeriLoop Coder-E1 is a coding-oriented model and may generate incorrect, insecure, incomplete, or harmful code if used without validation.
 
-- the chosen backbone weights,
-- repository complexity,
-- tool availability,
-- evaluation settings,
-- runtime configuration,
-- and task type.
+Recommended safeguards:
 
-Users should expect stronger performance in structured software tasks than in unconstrained claims about arbitrary domains. All outputs should still be reviewed before production use.
+- Run generated code in a sandbox before execution on real systems.
+- Review file-system, network, credential, and destructive-operation behavior.
+- Use static analysis and unit tests for generated patches.
+- Do not grant unrestricted shell, repository, or deployment permissions without external policy checks.
+- Treat the model as an assistant for software engineering, not as an autonomous authority.
 
-VeriLoop Coder E1 is also an evolving model line. Specific performance characteristics may change as stronger open-weight foundations and improved engineering workflows are incorporated.
+For high-risk environments, deploy VeriLoop Coder-E1 behind explicit permission controls, audit logging, validation gates, and rollback procedures.
 
 ---
 
-## Model Evolution
+## Public vs. Production Capability
 
-VeriLoop Coder E1 is part of a broader long-term model direction.
+This Hugging Face repository provides the **public standard model layer**:
 
-The product philosophy is simple:
+```text
+27B backbone weights
++ four public PEFT adapters
++ public adapter manifests
+```
 
-- keep the coding identity stable,
-- keep the engineering workflow strong,
-- and keep upgrading the model family as better open weights become available.
+A full production coding-agent stack may additionally include:
 
-This means future releases may differ in backbone choice, scaling strategy, and deployment profile while preserving the same core mission:
+```text
+runtime orchestration
+sandbox validation
+evidence management
+memory/context systems
+self-check and repair loops
+policy gates
+observability
+external expert routing
+```
 
-**to become a stronger, more practical, and more competitive open coding system over time.**
+The public model is useful on its own for research and development. The strongest production behavior is expected when the model is integrated into a robust coding-agent runtime.
 
 ---
 
-## Release Philosophy
-
-VeriLoop Coder E1 should be understood as an evolving coding platform rather than a one-off model drop.
-
-The release philosophy emphasizes:
-
-- forward compatibility with stronger open-weight backbones,
-- continuity of developer experience,
-- practical software engineering capability,
-- and continuous improvement toward frontier-level coding performance.
+## File Layout
+
+```text
+README.md
+config.json
+configuration.json
+generation_config.json
+model.safetensors.index.json
+tokenizer.json
+tokenizer_config.json
+special_tokens_map.json
+merges.txt
+preprocessor_config.json
+video_preprocessor_config.json
+veriloop-coder-e1-model-00001-of-00010.safetensors
+...
+veriloop-coder-e1-model-00010-of-00010.safetensors
+
+toolspec_adapter/
+  README.md
+  metrics_summary.json
+  veriloop_adapter_manifest.json
+  adapter/
+    README.md
+    adapter_config.json
+    adapter_model.safetensors
+
+uncertainty_adapter/
+  README.md
+  metrics_summary.json
+  veriloop_adapter_manifest.json
+  adapter/
+    README.md
+    adapter_config.json
+    adapter_model.safetensors
+
+rollback_adapter/
+  README.md
+  metrics_summary.json
+  veriloop_adapter_manifest.json
+  adapter/
+    README.md
+    adapter_config.json
+    adapter_model.safetensors
+
+evidence_adapter/
+  README.md
+  metrics_summary.json
+  veriloop_adapter_manifest.json
+  adapter/
+    README.md
+    adapter_config.json
+    adapter_model.safetensors
+```
 
 ---
 
-## Recommended Presentation on the Hub
-
-For best clarity, present this repository as:
-
-- a **coding model system**,
-- a **weight-agnostic open coding program**,
-- and the **first generation of the VeriLoop Coder line**.
+## Citation
 
-A concise positioning line for public-facing surfaces can be:
+If you use VeriLoop Coder-E1 in your work, please cite this repository:
 
-> **VeriLoop Coder E1 is a weight-agnostic coding model system built for repository-scale software engineering, benchmark-oriented performance, and continual improvement across open-weight generations.**
+```bibtex
+@misc{veriloop_coder_e1_2026,
+  title        = {VeriLoop Coder-E1: Harness-Aligned Open-Weight Coding Model},
+  author       = {VeriLoop Lab},
+  year         = {2026},
+  howpublished = {Hugging Face model repository},
+  url          = {https://huggingface.co/veriloop-lab/veriloop-coder-e1}
+}
+```
 
 ---
 
-## Notes
+## Acknowledgements
 
-- Weight choice is not permanently fixed.
-- Product capability is expected to strengthen as stronger open-weight backbones appear.
-- Public-facing documentation focuses on capabilities and use cases, not internal implementation details.
-- Users should evaluate the specific released checkpoint and runtime configuration for their deployment needs.
+VeriLoop Coder-E1 is built on top of the Qwen3.6-27B open-weight model family. We thank the open-source model ecosystem, the Hugging Face community, and the broader coding-agent research community for making reproducible model development possible.
 
-## Base Weight Notice
-
-This release currently uses **Qwen/Qwen3.6-27B** as its underlying open-weight backbone. The upstream Qwen/Qwen3.6-27B release is published under the **Apache 2.0** license.
-
-VeriLoop Coder E1 should not be understood as a claim over the underlying base weights themselves. Its distinguishing product direction lies in the surrounding **Harness Engineering** layer, including the way the coding system is organized, steered, and delivered for practical software engineering use.
+---
 
-As stronger open-weight coding backbones become available, VeriLoop Coder E1 is intended to update its underlying weights accordingly while preserving the same product identity and system direction. The intended outcome is that backbone upgrades, when combined with the VeriLoop harness, can deliver a stronger practical coding system than the raw base model alone.
+## License
 
+This repository includes model assets derived from an upstream open-weight backbone and VeriLoop adapter artifacts. Users are responsible for complying with the upstream base-model license and any applicable VeriLoop release terms described in this repository.