Update README.md

README.md

@@ -1,3 +1,207 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+language:
+- en
+base_model:
+- Qwen/Qwen3-4B-Instruct-2507
+pipeline_tag: text-generation
+tags:
+- reasoning
+- planning
+- agent
+- long-horizon
+- adaptive
+- goal-driven
+---
+
+# Eunoia-4B-Mini
+
+## Model Details
+
+### Model Description
+
+**Eunoia-4B-Mini** is a lightweight but advanced reasoning-focused language model designed to improve **long-horizon coherence, goal tracking, and adaptive problem solving**.
+
+Unlike conventional instruction-tuned models that operate in a single-pass generation loop, Eunoia introduces an **external cognitive control layer** that enables:
+
+- Explicit goal hierarchies
+- Step-wise evaluation and retry logic
+- Adaptive goal mutation under failure
+- Controlled advancement or abandonment of reasoning paths
+
+The result is a model that remains compact (~4B parameters) while exhibiting **strong multi-step reasoning stability** and **reduced derailment over long outputs**.
+
+This release is intended as a **research-oriented open-source baseline** for goal-driven and agentic LLM systems.
+
+- **Developed by:** SHV Groups
+- **Model type:** Decoder-only transformer with external reasoning controller
+- **Language(s):** English
+- **License:** Apache 2.0
+- **Finetuned from:** Qwen/Qwen3-4B-Instruct-2507
+
+---
+
+## Model Sources
+
+- **Repository:** https://huggingface.co/shvgroups/Eunoia-4B-mini
+- **Paper:** Coming soon
+- **Demo:** Coming soon
+
+---
+
+## Uses
+
+### Direct Use
+
+Eunoia-4B-Mini can be used directly for:
+
+- Long-form explanations and essays
+- Multi-step reasoning tasks
+- Educational content generation
+- Structured problem solving
+- Agent-style workflows with external controllers
+- Research on planning, retry, and adaptive reasoning loops
+
+The model works with standard `text-generation` pipelines and does **not** require special token formats.
+
+---
+
+### Downstream Use
+
+Eunoia-4B-Mini is particularly suitable for downstream systems such as:
+
+- Autonomous or semi-autonomous agents
+- Planner–executor architectures
+- Tool-augmented reasoning systems
+- Goal-conditioned fine-tuning
+- Research into long-horizon alignment and stability
+
+---
+
+### Out-of-Scope Use
+
+This model is **not designed** for:
+
+- Safety-critical decision making
+- Medical, legal, or financial advice
+- Fully autonomous real-world control systems
+- Use cases requiring formal guarantees or verification
+
+---
+
+## Bias, Risks, and Limitations
+
+Like all large language models, Eunoia-4B-Mini may:
+
+- Produce incorrect or misleading information
+- Reflect biases present in its base model and training data
+- Fail on tasks requiring real-time knowledge or sensory grounding
+
+While the goal-control system improves structural reasoning, it does **not guarantee correctness**.
+
+---
+
+### Recommendations
+
+Users are encouraged to:
+
+- Combine the model with external verification where correctness matters
+- Monitor outputs in autonomous or agentic settings
+- Fine-tune or constrain the model for domain-specific use cases
+
+---
+
+## How to Get Started with the Model
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+
+tokenizer = AutoTokenizer.from_pretrained("shvgroups/Eunoia-4B-mini")
+model = AutoModelForCausalLM.from_pretrained("shvgroups/Eunoia-4B-mini")
+
+prompt = "Explain photosynthesis step by step."
+inputs = tokenizer(prompt, return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=256)
+
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+
+
+## Training Details
+
+### Training Data
+
+Eunoia-4B-Mini is built on top of the base model’s training corpus and further refined through:
+
+- Instruction-following supervision  
+- Reasoning-structured prompts  
+- Iterative evaluation and retry loops  
+- Goal-decomposition templates  
+
+No private or user data was used in training or refinement.
+
+---
+
+### Training Procedure
+
+#### Training Hyperparameters
+
+- **Training regime:** Mixed-precision fine-tuning (fp16 / bf16)  
+- **Architecture:** Decoder-only transformer with an external reasoning controller  
+
+---
+
+## Evaluation
+
+### Metrics
+
+The model is evaluated primarily on the following qualitative and behavioral metrics:
+
+- Long-horizon coherence  
+- Instruction adherence over extended outputs  
+- Multi-step reasoning stability  
+- Retry and recovery behavior under failure  
+
+Formal benchmark results will be released in future updates.
+
+---
+
+## Environmental Impact
+
+- **Hardware:** NVIDIA GPUs  
+- **Training setup:** Research-scale fine-tuning  
+- **Carbon impact:** Not formally measured  
+
+---
+
+## Technical Specifications
+
+### Model Architecture and Objective
+
+- **Base transformer:** Qwen3-4B-Instruct  
+
+- **External reasoning modules:**
+  - Goal Tree  
+  - Execution Gate  
+  - Goal Evaluator  
+  - Adaptive Goal Mutation Engine  
+
+These components operate outside the core transformer and guide generation iteratively through structured goal management and adaptive control logic.
+
+---
+
+## Citation
+
+If you use this model in academic work, please cite:
+
+### BibTeX
+
+```bibtex
+@misc{eunoia4bmini2025,
+  title={Eunoia-4B-Mini: Goal-Driven Long-Horizon Reasoning},
+  author={SHV Groups},
+  year={2025},
+  url={https://huggingface.co/shvgroups/Eunoia-4B-mini}
+}
+
+Model Card Authors
+SHV Groups Research Team