Upload README.md

README.md

@@ -1,89 +1,64 @@
 ---
 library_name: transformers
 pipeline_tag: text-generation
-license: other
+license: apache-2.0
+license_link: https://huggingface.co/Qwen/Qwen3.6-27B/blob/main/LICENSE
 base_model:
   - Qwen/Qwen3.6-27B
+base_model_relation: finetune
 language:
   - en
+  - zh
 tags:
-  - safetensors
   - qwen3_6
+  - qwen3
   - qwen
+  - veriloop
+  - veriloop-coder
   - code
   - coding-agent
-  - software-engineering
-  - harness-engineering
   - agentic-coding
+  - software-engineering
   - repository-understanding
   - tool-use
+  - peft
+  - lora
+  - safetensors
+  - transformers
+  - harness-engineering
   - evidence-binding
   - rollback
   - uncertainty-calibration
-  - veriloop
-  - weight-agnostic
+  - long-context
+  - open-weights
+  - reasoning
+  - conversational
 ---
 
 # VeriLoop Coder-E1
 
-**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.
-
-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.
+**VeriLoop Coder-E1** is an open-weight coding model release built on a Qwen3.6-27B backbone and specialized for harness-driven software engineering workflows.
 
-VeriLoop Coder-E1 is released as a two-layer public package:
+The public release provides a standard, Hugging Face-compatible model package: sharded `safetensors` backbone weights in the repository root, plus four focused PEFT adapters for coding-agent behavior shaping. It is designed for developers and researchers who want a coding model that is not only fluent at code generation, but also better prepared for tool-mediated execution, evidence-aware reasoning, rollback-safe revision, and uncertainty-calibrated coding workflows.
 
-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`
-
-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.
+> **Release note**  
+> This is the first public VeriLoop Coder-E1 27B release package. Public benchmark results will be added after the formal evaluation run. The current repository focuses on releasing clean, standard model artifacts without exposing internal production Harness code, private runtime heads, training data, or server-side orchestration logic.
 
 ---
 
 ## Highlights
 
-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.
-
-Key capability directions include:
-
-- **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.
+VeriLoop Coder-E1 is built for coding-agent environments where a model must cooperate with external tools, validators, repository context, and iterative repair loops.
 
-VeriLoop Coder-E1 should be viewed as a **coding model foundation for harness-centric systems**, not as a complete hosted agent product by itself.
-
----
-
-## Release Scope
-
-### Included in this public release
-
-- 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.
-
-### Not included in this public release
-
-- 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.
+- **Harness-ready coding behavior** — shaped for coding runtimes that use tool calls, validation feedback, staged execution, and bounded repair loops.
+- **Tool-spec alignment** — improves obedience to tool schemas, argument discipline, preconditions, postconditions, and execution-facing instruction formats.
+- **Evidence-bound coding style** — encourages stronger alignment between claims, code edits, validation signals, and supporting repository context.
+- **Rollback-aware revision behavior** — improves response patterns around failed edits, validator negation, worktree-sensitive repair, and safe correction boundaries.
+- **Uncertainty-calibrated routing signals** — supports more reliable decisions around answer uncertainty, evidence gaps, execution necessity, specification mismatch, and risk pressure.
+- **Repository-scale workflow orientation** — intended for code understanding, patch drafting, debugging, refactoring assistance, and agentic software engineering tasks.
+- **Open standard artifacts** — released with `safetensors` model shards and PEFT-compatible adapter checkpoints for public loading and reproducible experimentation.
 
-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.
+VeriLoop Coder-E1 should be viewed as a **coding model foundation for harness-centric systems**. The full VeriLoop product experience may involve additional runtime components such as tool orchestration, sandbox validation, evidence handling, memory, observability, and API-side routing.
 
 ---
 
@@ -93,13 +68,41 @@ This separation is intentional: the public repository provides standard model as
 |---|---|
 | Model family | VeriLoop Coder-E1 |
 | Backbone | Qwen3.6-27B-compatible backbone |
-| Public release type | Open-weight backbone + PEFT adapters |
+| Public release type | Open-weight backbone + four PEFT adapters |
 | Primary domain | Coding, software engineering, coding-agent workflows |
+| Languages | English, Chinese |
 | Weight format | `safetensors` |
 | Adapter format | PEFT / LoRA-style adapter checkpoints |
 | Runtime target | Harness-driven coding systems, tool-mediated agents, repository workflows |
+| Public benchmark status | Formal benchmark results pending |
 
-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.
+The public release separates standard model assets from private production runtime infrastructure. Users can load the base model directly, or mount one of the four public PEFT adapters for targeted experimentation.
+
+---
+
+## Public Release Contents
+
+### Included
+
+- Qwen3.6-27B-compatible backbone files in the repository root.
+- Standard sharded `safetensors` model weights.
+- Tokenizer, generation, and configuration files.
+- Four public PEFT adapters:
+  - `toolspec_adapter/adapter`
+  - `uncertainty_adapter/adapter`
+  - `rollback_adapter/adapter`
+  - `evidence_adapter/adapter`
+- Public adapter README files, metric summaries, and adapter manifests.
+
+### Not Included
+
+- 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 separation is intentional. The public repository provides standard open model assets, while production-grade coding-agent behavior may require a full runtime system around the model.
 
 ---
 
@@ -107,12 +110,12 @@ The backbone inherits the long-context and coding-oriented capabilities of Qwen3
 
 | 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 |
+| ToolSpec | `toolspec_adapter/adapter` | `adapter_config.json`, `adapter_model.safetensors` | Tool-call discipline, schema obedience, precondition/postcondition sensitivity |
+| Uncertainty | `uncertainty_adapter/adapter` | `adapter_config.json`, `adapter_model.safetensors` | Runtime uncertainty calibration across answer, evidence, execution, specification, 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 |
 
-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.
+Each adapter is published independently. Users can load one adapter at a time for focused evaluation, or build their own adapter-selection policy around the public artifacts.
 
 ---
 
@@ -124,9 +127,7 @@ Each adapter is published independently. Users can load one adapter at a time fo
 pip install -U transformers peft accelerate safetensors
 ```
 
-For large-model inference, use an environment with adequate GPU memory and recent versions of `transformers`, `peft`, and `accelerate`.
-
-### Load the backbone
+### Load the Backbone
 
 ```python
 from transformers import AutoTokenizer, AutoModelForCausalLM
@@ -149,19 +150,29 @@ model = AutoModelForCausalLM.from_pretrained(
 model.eval()
 ```
 
-### Load a public VeriLoop adapter
+### Load One Public PEFT Adapter
 
 ```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
 from peft import PeftModel
+import torch
 
 repo_id = "veriloop-lab/veriloop-coder-e1"
+adapter_subfolder = "evidence_adapter/adapter"  # choose one adapter
 
-model = PeftModel.from_pretrained(
-    model,
+tokenizer = AutoTokenizer.from_pretrained(repo_id, trust_remote_code=True)
+base_model = AutoModelForCausalLM.from_pretrained(
     repo_id,
-    subfolder="evidence_adapter/adapter",
+    torch_dtype=torch.bfloat16,
+    device_map="auto",
+    trust_remote_code=True,
 )
 
+model = PeftModel.from_pretrained(
+    base_model,
+    repo_id,
+    subfolder=adapter_subfolder,
+)
 model.eval()
 ```
 
@@ -174,25 +185,28 @@ rollback_adapter/adapter
 evidence_adapter/adapter
 ```
 
-### Generate
+### Minimal Generation Example
 
 ```python
-prompt = "Write a robust Python function that validates and normalizes a repository file path. Include a minimal self-test."
+prompt = "Write a Python function that validates whether a patch should be accepted after unit tests."
 
 messages = [
-    {"role": "user", "content": prompt}
+    {"role": "user", "content": prompt},
 ]
 
-inputs = tokenizer.apply_chat_template(
+text = tokenizer.apply_chat_template(
     messages,
+    tokenize=False,
     add_generation_prompt=True,
-    return_tensors="pt",
-).to(model.device)
+)
 
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
 outputs = model.generate(
-    inputs,
-    max_new_tokens=2048,
-    do_sample=False,
+    **inputs,
+    max_new_tokens=1024,
+    temperature=0.6,
+    top_p=0.95,
+    do_sample=True,
 )
 
 print(tokenizer.decode(outputs[0], skip_special_tokens=True))
@@ -200,106 +214,58 @@ print(tokenizer.decode(outputs[0], skip_special_tokens=True))
 
 ---
 
-## vLLM / Serving Notes
+## Serving Notes
 
-The backbone can be served as a standard Hugging Face model in inference engines that support the underlying architecture.
+The repository root contains the backbone model files and can be served with standard inference engines that support the underlying architecture. PEFT adapters may require framework-specific LoRA loading support.
 
-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.
+### vLLM Backbone Serving
 
-A typical deployment pattern is:
+```bash
+vllm serve veriloop-lab/veriloop-coder-e1 \
+  --trust-remote-code \
+  --tensor-parallel-size 2 \
+  --max-model-len 131072
+```
 
-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.
+For public PEFT adapters, use the serving engine's LoRA/adapter loading mechanism if supported by your deployment configuration. The full VeriLoop production setup may use additional private runtime components that are not part of this public release.
 
 ---
 
 ## Recommended Use Cases
 
-VeriLoop Coder-E1 is intended for:
-
-- 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.
+VeriLoop Coder-E1 is intended for research and development in:
 
-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.
+- Coding-agent model evaluation.
+- Tool-mediated code generation.
+- Repository understanding and patch drafting.
+- Validator-aware repair experiments.
+- Evidence-aware coding workflows.
+- Uncertainty-aware software engineering agents.
+- Harness and runtime policy research.
 
 ---
 
 ## Limitations
 
-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.
-
-Important limitations:
-
-- 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.
-
----
-
-## Evaluation Status
-
-Public benchmark results are not yet included in this release.
-
-The current repository is a public model-asset release focused on:
-
-- Standard weight availability.
-- Adapter availability.
-- Reproducible loading.
-- Harness-oriented coding model alignment.
-
-External leaderboard and benchmark results will be added after controlled evaluation on standardized coding and agentic software-engineering benchmarks.
+- Public benchmark numbers are not yet included in this release and will be added after formal evaluation.
+- The public repository does not include private runtime heads or internal Harness orchestration.
+- Public adapter loading does not reproduce the complete VeriLoop production API behavior.
+- Long-context and high-throughput serving require appropriate GPU memory, KV-cache planning, and inference-engine configuration.
+- Users should validate generated code with tests, static analysis, sandboxing, and security review before deployment.
 
 ---
 
 ## Safety and Responsible Use
 
-VeriLoop Coder-E1 is a coding-oriented model and may generate incorrect, insecure, incomplete, or harmful code if used without validation.
-
-Recommended safeguards:
-
-- 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.
-
-For high-risk environments, deploy VeriLoop Coder-E1 behind explicit permission controls, audit logging, validation gates, and rollback procedures.
-
----
-
-## Public vs. Production Capability
-
-This Hugging Face repository provides the **public standard model layer**:
-
-```text
-27B backbone weights
-+ four public PEFT adapters
-+ public adapter manifests
-```
-
-A full production coding-agent stack may additionally include:
+VeriLoop Coder-E1 is a coding-focused model and may produce incorrect, insecure, incomplete, or environment-specific code. Users are responsible for validating outputs before use.
 
-```text
-runtime orchestration
-sandbox validation
-evidence management
-memory/context systems
-self-check and repair loops
-policy gates
-observability
-external expert routing
-```
+Recommended safeguards include:
 
-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.
+- Run generated code in isolated environments.
+- Review dependencies and shell commands before execution.
+- Use automated tests and linters.
+- Treat security-sensitive code paths as high risk.
+- Avoid using generated code for destructive actions without human review.
 
 ---
 
@@ -309,64 +275,69 @@ The public model is useful on its own for research and development. The stronges
 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
+tokenizer.json
+tokenizer_config.json
+generation_config.json
+special_tokens_map.json
 
-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
+ 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
 ```
 
 ---
 
+## Evaluation Status
+
+Formal benchmark results are planned. Future updates may include coding-agent benchmarks, repository-level tasks, tool-use evaluations, validation/rollback tests, and long-context software-engineering workflows.
+
+Until benchmark numbers are published, this model card should be interpreted as a release description and loading guide, not as a performance leaderboard claim.
+
+---
+
 ## Citation
 
-If you use VeriLoop Coder-E1 in your work, please cite this repository:
+If you use VeriLoop Coder-E1 in research, prototypes, or agent systems, please cite:
 
 ```bibtex
 @misc{veriloop_coder_e1_2026,
-  title        = {VeriLoop Coder-E1: Harness-Aligned Open-Weight Coding Model},
+  title        = {VeriLoop Coder-E1: Harness-Ready Open-Weight Coding Model Release},
   author       = {VeriLoop Lab},
   year         = {2026},
   howpublished = {Hugging Face model repository},
@@ -378,10 +349,4 @@ If you use VeriLoop Coder-E1 in your work, please cite this repository:
 
 ## Acknowledgements
 
-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.
-
----
-
-## 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.
+VeriLoop Coder-E1 is built on top of the Qwen3.6-27B open-weight backbone. We thank the open-source model and tooling communities for enabling reproducible model development, adapter-based experimentation, and open deployment workflows.