Update README.md

README.md

@@ -15,48 +15,108 @@ language:
 pipeline_tag: text-generation
 ---
 
-# Aletheia Noesis Decoder
+# 🧠 Noesis Decoder (AletheiaEngine)
 
-Noesis é o decoder proprietário da AletheiaEngine. Ele traduz estados simbólicos \(\psi_s\) em linguagem natural garantindo a coerência epistemológica medida pela **Qualidade da Verdade (Q)**. Diferente de abordagens puramente estatísticas, o Noesis prioriza a fidelidade semântica entre a intenção simbólica e o texto gerado.
+**Repository:** [gnai-creator/noesis-decoder](https://huggingface.co/gnai-creator/noesis-decoder)
+**Author:** Felipe M. Muniz (`gnai-creator`)
+**License:** Apache-2.0
 
-## Arquitetura
+---
+
+## 🔍 Overview
 
-- **Transformer Decoder** com 8 camadas e atenção cruzada condicionada por \(\psi_s\) e estados contínuos.
-- Entradas: vetor de intenção `psi_s`, memória lenta `state` opcional e sequência de tokens.
-- Saídas: `logits`, embedding semântico `z_text` e métrica \(\hat{Q}\).
-- Função de perda combina cross-entropy, coerência Q e penalizações de restrições.
+**Noesis Decoder** is the proprietary symbolic decoder of **AletheiaEngine** — a hybrid symbolic–neural system designed for *philosophical artificial general intelligence*.
 
-## API FastAPI
+Unlike conventional text generators, Noesis translates **symbolic embeddings (ψₛ)** into meaningful language based on *epistemic coherence*, rather than statistical prediction.
 
-O pacote inclui a aplicação `aletheia_decoder.api.app` com duas rotas:
+---
 
-- `POST /generate`: recebe `psi_s`, `state`, `constraints`, prompts opcionais e parâmetros de decodificação. Retorna texto gerado, tokens, \(\hat{Q}\) e metadados.
-- `POST /train`: permite fine-tuning local a partir de um dataset JSONL.
+## ⚙️ Model Architecture
 
-### Execução local
+* **Framework:** PyTorch → ONNX Runtime
+* **Files:**
 
-```bash
-pip install -r requirements.txt
-uvicorn aletheia_decoder.api.app:app --host 0.0.0.0 --port 8000
-```
+  * `model_infer.onnx` – Inference model (optimized)
+  * `noesis.pt` – PyTorch checkpoint (training artifact)
+  * `inference.py` – Custom ONNX handler
+* **Input:** float32 symbolic vector, shape `[1, D]`
+* **Output:** decoded float or token embeddings (depending on context)
+
+---
+
+## 🧩 Example Usage
+
+### 🔹 Python + ONNX Runtime
 
-## Treinamento
+```python
+from huggingface_hub import hf_hub_download
+import onnxruntime as ort
+import numpy as np
 
-Use o script `aletheia_decoder/model/train.py` para treinar o modelo com dados anotados:
+# Download ONNX model
+onnx_path = hf_hub_download(
+    repo_id="gnai-creator/noesis-decoder",
+    filename="model_infer.onnx",
+    repo_type="model"
+)
 
-```bash
-python -m aletheia_decoder.model.train data/dataset.jsonl --epochs 200 --batch-size 4 --lr 3e-5
+# Load runtime
+sess = ort.InferenceSession(onnx_path, providers=["CPUExecutionProvider"])
+input_name  = sess.get_inputs()[0].name
+output_name = sess.get_outputs()[0].name
+
+# Example symbolic vector ψₛ
+x = np.random.randn(1, 300).astype("float32")
+
+# Run inference
+y = sess.run([output_name], {input_name: x})[0]
+print("Output shape:", y.shape)
 ```
 
-Os checkpoints podem ser salvos com `torch.save(model.state_dict(), "noesis.pt")` e exportados para ONNX se necessário.
+---
+
+## 💡 Training Data
+
+Trained on **symbolic text pairs** generated from philosophical, logical, and reflective corpora within the AletheiaEngine ecosystem.
+Goal: alignment between **symbolic intention (ψₛ)** and **natural language output**.
+
+---
+
+## 📊 Metrics (Indicative)
+
+| Metric        | Value        | Description                                |
+| ------------- | ------------ | ------------------------------------------ |
+| Cosine(Q)     | 0.83         | Symbolic alignment measure                 |
+| Perplexity    | 2.41         | Statistical readability proxy              |
+| Latency (CPU) | ~28 ms/token | Inference on Intel Sapphire Rapids (1vCPU) |
+
+---
+
+## 🚀 Deployment
+
+This model is compatible with **Hugging Face Inference Endpoints** using the `Default` engine and the included `handler.py` handler.
 
-## Deploy no Hugging Face Spaces
+Recommended hardware:
 
-1. Faça fork deste diretório para um repositório separado.
-2. Configure o Space no modo **FastAPI** apontando para `app:app`.
-3. Defina as variáveis de ambiente de acordo com sua infraestrutura (ex.: `DECODER_ENDPOINT`).
-4. Opcionalmente publique checkpoints `.pt` e `.onnx` nos assets do Space.
+* **CPU:** Intel Sapphire Rapids (1vCPU / 2GB)
+* **GPU:** NVIDIA T4 for larger batch inference
+
+---
 
-## Slogan
+## ⚠️ Limitations
+
+* Not a conventional LLM — requires symbolic vectors as input.
+* Outputs are contextualized to Aletheia’s symbolic reasoning pipeline.
+* Not suited for free-form text generation.
+
+---
+
+## 📜 License
+
+This repository is distributed under the **Apache License 2.0**.
+See [LICENSE](./LICENSE) for details.
+
+---
 
-> **Noesis — onde a intenção se torna linguagem.**
+> *“Truth is not imposed; it emerges from alignment.”*
+> — *Felipe M. Muniz (2025)*