Update README.md

README.md

@@ -1,7 +1,634 @@
 ---
 license: mit
 ---
+<div align="center">
 
+# Nexora-Qwen-Coder-4B
 
-![image](https://cdn-uploads.huggingface.co/production/uploads/644afe169279988e0cbcd2d9/AVI5Rk73jQfx76ePPXx90.png)
+### Compact Agentic Coding Model
 
+**Coding · Debugging · Tool Use · Structured Reasoning · Local AI**
+
+[![Hugging Face](https://img.shields.io/badge/Hugging%20Face-Nexora--Qwen--Coder--4B-yellow?logo=huggingface)](https://huggingface.co/guell00/Nexora-Qwen-Coder-4B)
+[![GGUF](https://img.shields.io/badge/Format-GGUF-blue)](https://github.com/ggerganov/llama.cpp)
+[![Unsloth](https://img.shields.io/badge/Fine--Tuning-Unsloth-orange)](https://unsloth.ai/)
+[![License](https://img.shields.io/badge/Model-Research%20%2F%20Community-lightgrey)](#-disclaimer)
+
+</div>
+
+<p align="center">
+  <img src="https://cdn-uploads.huggingface.co/production/uploads/644afe169279988e0cbcd2d9/AVI5Rk73jQfx76ePPXx90.png" width="100%">
+</p>
+
+---
+
+> **Nexora-Qwen-Coder-4B** is a compact coding-focused language model fine-tuned from the **Qwen 3.5 4B family**, optimized for **code generation, debugging, structured reasoning, tool calling, and local agentic workflows**.
+
+Designed around a simple idea:
+
+> **A small model should not just write code. It should be able to reason about the problem, interact with tools, inspect feedback, and fix what it got wrong.**
+
+---
+
+## Model at a Glance
+
+|                      |                                |
+| -------------------- | ------------------------------ |
+| **Model**            | `Nexora-Qwen-Coder-4B`         |
+| **Hugging Face**     | `guell00/Nexora-Qwen-Coder-4B` |
+| **Base Model**       | Qwen 3.5 4B                    |
+| **Architecture**     | Dense Transformer              |
+| **Specialization**   | Coding & Agentic Workflows     |
+| **Fine-Tuning**      | Nexora Fine-Tuning             |
+| **Training**         | SFT + Curriculum Learning      |
+| **Reasoning Data**   | Trace Inversion                |
+| **Agent Data**       | Tool-Use & Agent Trajectories  |
+| **MTP Evaluation**   | `n=2`                          |
+| **Training Context** | Up to 32K tokens               |
+| **Format**           | GGUF                           |
+| **Inference**        | llama.cpp compatible           |
+
+---
+
+# Why Nexora-Qwen-Coder-4B?
+
+The goal of Nexora-Qwen-Coder-4B is not to compete purely on parameter count.
+
+It is designed to maximize the practical usefulness of a **compact local model** for software development.
+
+The training pipeline focuses on four areas:
+
+### `01` Coding
+
+Code generation, completion, explanation, refactoring, and implementation of programming tasks.
+
+### `02` Debugging
+
+Bug localization, error analysis, reasoning about failures, and minimal code repair.
+
+### `03` Agentic Workflows
+
+Learning to operate in environments where the model can inspect files, call tools, execute actions, receive feedback, and iterate.
+
+### `04` Structured Reasoning
+
+Improving consistency on multi-step technical tasks that require planning before producing the final solution.
+
+---
+
+# Benchmark Performance
+
+Nexora-Qwen-Coder-4B was evaluated locally using the **benchlocal** evaluation framework.
+
+The evaluation focuses on practical developer workflows rather than only general knowledge benchmarks.
+
+### Evaluation Areas
+
+```text
+┌─────────────────────────────────────────────┐
+│                                             │
+│   🐛 Debugging                              │
+│   🧠 Agent Workflow                         │
+│   🛠️ Tool Routing                           │
+│   📄 Instruction Following                  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Results
+
+| Benchmark             | Nexora-Qwen-Coder-4B | Qwen 3.5 4B |   Delta |
+| :-------------------- | -------------------: | ----------: | ------: |
+| **BugFind-15**        |         **71 / 100** |    52 / 100 | **+19** |
+| **HermesAgent-20**    |         **64 / 100** |    61 / 100 |  **+3** |
+| **ToolCall-15**       |        **100 / 100** |    90 / 100 | **+10** |
+| **InstructFollow-15** |         **93 / 100** |    93 / 100 |   **0** |
+
+---
+
+## Benchmark Highlights
+
+### 🐛 BugFind-15
+
+**71 / 100**
+
+The model showed a significant improvement over the Qwen 3.5 4B baseline in the evaluated debugging scenarios.
+
+**+19 points over baseline**
+
+---
+
+### 🛠️ ToolCall-15
+
+**100 / 100**
+
+Nexora-Qwen-Coder-4B achieved a **perfect score** in the evaluated tool-routing benchmark.
+
+This benchmark measures the model's ability to select and structure tool calls correctly.
+
+---
+
+### 🧠 HermesAgent-20
+
+**64 / 100**
+
+The model showed improved performance over the base 4B model in the evaluated agent workflow scenarios.
+
+The benchmark covers areas including:
+
+* Memory recall
+* Workspace orchestration
+* Procedural skills
+* Scheduling and delivery behavior
+
+---
+
+### 📄 InstructFollow-15
+
+**93 / 100**
+
+Nexora-Qwen-Coder-4B matched the Qwen 3.5 4B baseline in the evaluated instruction-following benchmark.
+
+This indicates strong reliability in structured output and constraint-following tasks.
+
+---
+
+# Benchmark Positioning
+
+The evaluated results indicate that Nexora-Qwen-Coder-4B is particularly strong in **coding-oriented and agentic workflows** relative to its compact parameter class.
+
+```text
+                 Nexora-Qwen-Coder-4B
+
+          Coding        ████████████████████
+          Debugging     ████████████████████
+          Tool Use      ████████████████████
+          Agent Tasks   █████████████████░░░
+          Instruction   ███████████████████░
+          Local Use     ████████████████████
+```
+
+The strongest observed areas are:
+
+* **Code debugging**
+* **Tool routing**
+* **Structured coding workflows**
+* **Instruction following**
+* **Local agent deployment**
+
+Benchmark results are evaluation snapshots and may vary depending on model quantization, inference backend, prompt format, context length, sampling parameters, and hardware.
+
+---
+
+# Training Approach
+
+Nexora-Qwen-Coder-4B uses a multi-stage fine-tuning pipeline designed around **coding + reasoning + agent interaction**.
+
+The overall training philosophy can be summarized as:
+
+```text
+          Raw Coding Data
+                 │
+                 ▼
+        Structured SFT Data
+                 │
+                 ▼
+          Trace Inversion
+                 │
+                 ▼
+       Agent Trajectories
+                 │
+                 ▼
+       Curriculum Learning
+                 │
+                 ▼
+       Long-Context SFT
+                 │
+                 ▼
+        Nexora-Qwen-Coder-4B
+```
+
+The training mixture includes:
+
+* Coding tasks
+* Debugging examples
+* Structured reasoning
+* Tool-use trajectories
+* Multi-turn interactions
+* Agent workflows
+* Long-context samples
+* Instruction-following data
+
+---
+
+# Trace Inversion
+
+A core component of the training pipeline is **Trace Inversion**.
+
+The approach is designed to reconstruct more complete reasoning traces from compressed reasoning outputs and use these traces as additional training signals.
+
+The resulting data is combined with the original prompt and final response to create structured training examples.
+
+Conceptually:
+
+```text
+Original Prompt
+      │
+      ▼
+Compressed Reasoning
+      │
+      ▼
+Trace Inversion
+      │
+      ▼
+Reconstructed Reasoning Trace
+      │
+      ▼
+Prompt + Reasoning + Response
+      │
+      ▼
+      SFT Dataset
+```
+
+The goal is to improve the model's ability to handle tasks requiring multiple reasoning steps, particularly:
+
+* Debugging
+* Code analysis
+* Error diagnosis
+* Tool selection
+* Multi-step programming
+* Agentic workflows
+
+Trace Inversion is a training technique and does not guarantee improved performance on every task.
+
+---
+
+# Curriculum Learning
+
+The fine-tuning process follows a three-stage curriculum.
+
+| Stage       | Focus                                   |   Context  |
+| :---------- | :-------------------------------------- | :--------: |
+| **Stage 1** | Format stability & structured reasoning |   `< 4K`   |
+| **Stage 2** | Coding, debugging & agent trajectories  |  `4K – 8K` |
+| **Stage 3** | Long-context & multi-turn SFT           | `8K – 32K` |
+
+### Stage 1 · Format Inception
+
+The model is first exposed to shorter, cleaner examples.
+
+The objective is to establish:
+
+* Stable output formatting
+* Instruction following
+* Structured reasoning behavior
+* Consistent response boundaries
+
+### Stage 2 · Complexity Expansion
+
+The training mixture becomes more complex.
+
+The model is introduced to:
+
+* Harder coding problems
+* Debugging scenarios
+* Tool calls
+* Multi-turn interactions
+* Agent trajectories
+* Environment feedback
+
+### Stage 3 · Long-Context SFT
+
+The final stage introduces longer samples and multi-turn workflows while replaying high-quality shorter examples.
+
+This helps reduce instruction-following drift while improving performance on longer technical tasks.
+
+> **Note:** The 32K token value describes the training sequence length and data distribution used during fine-tuning. It should not automatically be interpreted as a hard architectural context limit.
+
+---
+
+# Agentic Coding
+
+Nexora-Qwen-Coder-4B is designed for workflows where the model is not limited to generating a single static response.
+
+A typical agent loop looks like this:
+
+```text
+┌──────────────┐
+│ User Request │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Understand   │
+│ the Task     │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Plan         │
+│ Solution     │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Select Tool  │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Execute      │
+│ Action       │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Inspect      │
+│ Feedback     │
+└──────┬───────┘
+       │
+       ├───────────────┐
+       │               │
+       ▼               │
+   Success?            │
+       │               │
+    Yes│               │No
+       │               │
+       ▼               │
+  Final Answer ◄───────┘
+```
+
+This makes the model suitable for local environments that provide tools such as:
+
+* File operations
+* Terminal execution
+* Code search
+* Repository inspection
+* Build systems
+* Test runners
+* Linters
+* Debugging environments
+
+Tool-call reliability depends heavily on the prompt template and tool schema used by the application.
+
+---
+
+# Quick Start
+
+## llama.cpp
+
+Run the model directly from Hugging Face:
+
+```bash
+llama-cli -hf guell00/Nexora-Qwen-Coder-4B --jinja
+```
+
+For a local OpenAI-compatible server:
+
+```bash
+llama-server -hf guell00/Nexora-Qwen-Coder-4B --jinja
+```
+
+> Command availability may depend on your `llama.cpp` version and the model files available in the repository.
+
+---
+
+# Model Files
+
+Nexora-Qwen-Coder-4B is available in GGUF format for efficient local inference.
+
+| Quantization | Recommended For                               |
+| :----------- | :-------------------------------------------- |
+| **Q8_0**     | Maximum quality with higher memory usage      |
+| **Q6_K**     | High quality with reduced memory requirements |
+| **Q5_K_M**   | Excellent quality-to-size ratio               |
+| **Q4_K_M**   | Best general-purpose local deployment         |
+
+### Recommended
+
+**Q4_K_M**
+
+Recommended for most users looking for a strong balance between:
+
+`Quality` · `Memory` · `Speed`
+
+**Q8_0**
+
+Recommended when memory is not a major constraint and maximum quantized quality is preferred.
+
+---
+
+# Context Length
+
+The model was fine-tuned with sequences reaching approximately **32K tokens**.
+
+The underlying Qwen 3.5 family may support larger context windows depending on the specific architecture and inference backend.
+
+For long-context inference, performance depends on:
+
+* Backend support
+* RoPE configuration
+* YaRN scaling
+* Quantization
+* KV cache
+* Available memory
+* Context size
+
+When extending beyond the training distribution, users should validate the model on their own workloads.
+
+Example `llama.cpp` configuration:
+
+```bash
+./llama-server \
+  -m model.gguf \
+  --ctx-size 131072 \
+  --rope-scaling yarn \
+  --rope-scale 4 \
+  --yarn-orig-ctx 32768
+```
+
+> **Important:** Increasing `--ctx-size` alone does not guarantee reliable long-context behavior.
+
+---
+
+# Recommended Generation Settings
+
+For deterministic coding and debugging workflows:
+
+| Parameter              |  Value |
+| :--------------------- | :----: |
+| **Temperature**        |   `0`  |
+| **Top P**              | `0.95` |
+| **Top K**              |  `40`  |
+| **Min P**              | `0.05` |
+| **Repetition Penalty** |  `1.1` |
+| **Presence Penalty**   |   Off  |
+| **Max Tokens**         |   Max  |
+
+```text
+Temperature:        0
+Top P:              0.95
+Top K:              40
+Min P:              0.05
+Repetition Penalty: 1.1
+Presence Penalty:   Off
+Max Tokens:         Max
+```
+
+For creative coding tasks or brainstorming, a higher temperature may be useful.
+
+For debugging, code generation, and agentic workflows, lower temperatures generally provide more deterministic behavior.
+
+---
+
+# Recommended Use Cases
+
+Nexora-Qwen-Coder-4B is designed for:
+
+| Use Case              |  Fit  |
+| :-------------------- | :---: |
+| Code Generation       | ★★★★★ |
+| Debugging             | ★★★★★ |
+| Tool Calling          | ★★★★★ |
+| Code Explanation      | ★★★★★ |
+| Refactoring           | ★★★★☆ |
+| Repository Analysis   | ★★★★☆ |
+| Technical Reasoning   | ★★★★☆ |
+| Local Coding Agents   | ★★★★★ |
+| Documentation         | ★★★★☆ |
+| Software Architecture | ★★★☆☆ |
+
+### Best suited for
+
+* Code generation
+* Code completion
+* Debugging
+* Bug localization
+* Refactoring
+* Error analysis
+* Technical reasoning
+* Repository inspection
+* Tool calling
+* Local coding agents
+* Multi-step development tasks
+
+---
+
+# Built for Local AI
+
+The 4B parameter class is intentionally compact.
+
+Nexora-Qwen-Coder-4B aims to provide a practical balance between:
+
+```text
+        CAPABILITY
+            ▲
+            │
+            │       ● Nexora-Qwen-Coder-4B
+            │
+            │
+            │
+            └──────────────────────────►
+                LOCAL EFFICIENCY
+```
+
+The goal is to make capable coding and agentic behavior accessible on consumer hardware without requiring a large datacenter-scale deployment.
+
+This makes the model suitable for:
+
+* Local development
+* Personal coding assistants
+* Offline workflows
+* Lightweight coding agents
+* Developer workstations
+* Experimental AI agents
+
+---
+
+# ⚠️ Limitations
+
+Nexora-Qwen-Coder-4B is a compact 4B-class model.
+
+It may struggle with:
+
+* Extremely large repository-wide changes
+* Complex multi-file dependencies
+* Highly specialized professional domains
+* Tasks requiring extensive external knowledge
+* Long autonomous workflows without verification
+* Deep architectural decisions involving large systems
+
+The model should be treated as a **coding assistant**, not a fully autonomous software engineer.
+
+Generated code should always be:
+
+> **Reviewed → Tested → Validated**
+
+before being deployed to production.
+
+Depending on the inference template, the model may produce reasoning content inside:
+
+```text
+<think>
+...
+</think>
+```
+
+Applications may parse, hide, or otherwise handle these sections according to their requirements.
+
+---
+
+# 🛠️ Built With
+
+| Technology     | Role                               |
+| :------------- | :--------------------------------- |
+| **Qwen**       | Base model family                  |
+| **Unsloth**    | Fine-tuning & conversion workflows |
+| **GGUF**       | Local model format                 |
+| **llama.cpp**  | Local inference                    |
+| **benchlocal** | Coding & agent evaluation          |
+
+---
+
+# Acknowledgements
+
+Special thanks to:
+
+* The **Qwen team** for the base model family.
+* The **Unsloth team** for efficient fine-tuning and conversion tooling.
+* The open-source AI community for datasets, tools, and research.
+* Contributors supporting local hardware testing and evaluation.
+
+---
+
+# Disclaimer
+
+Nexora-Qwen-Coder-4B is provided for **research, development, experimentation, and local inference**.
+
+Actual performance may vary depending on:
+
+* Quantization method
+* Inference backend
+* Hardware
+* Context length
+* Prompt formatting
+* Sampling parameters
+* Evaluation methodology
+
+Benchmark results represent specific evaluation runs and should not be interpreted as guaranteed performance across all environments or tasks.
+
+Always review and test generated code before using it in production systems.
+
+---
+
+<div align="center">
+
+# Nexora
+
+### Intelligence. Code. Evolve.
+
+**Built for developers who want capable AI coding assistance running locally.**
+
+`guell00/Nexora-Qwen-Coder-4B`
+
+</div>