Updated Readme

README.md

@@ -1,209 +1,309 @@
 ---
+license: apache-2.0
 base_model: meta-models/Muse-Glimmer-30B
 library_name: peft
-pipeline_tag: text-generation
+pipeline_tag: image-text-to-text
 tags:
-- base_model:adapter:meta-models/Muse-Glimmer-30B
-- lora
-- sft
-- transformers
-- trl
+  - lora
+  - peft
+  - muse-glimmer
+  - json
+  - structured-output
+  - api
+  - tool-use
 ---
 
-# Model Card for Model ID
+# Muse Glimmer JSON API
 
-<!-- Provide a quick summary of what the model is/does. -->
+`muse-glimmer-json-api` is a LoRA adapter for [`meta-models/Muse-Glimmer-30B`](https://huggingface.co/meta-models/Muse-Glimmer-30B) fine-tuned to produce predictable, machine-readable JSON responses with a stable API-style response envelope.
 
+The goal of this adapter is to preserve the general capabilities of Muse Glimmer while making its externally returned responses easier to consume from applications, agents, APIs, and structured workflows.
 
+## Base Model
 
-## Model Details
+- **Base:** `meta-models/Muse-Glimmer-30B`
+- **Architecture:** Muse Glimmer
+- **Fine-tuning method:** LoRA supervised fine-tuning
+- **Precision used during training:** BF16
+- **Adapter size:** ~429 MB
+- **License:** Apache 2.0
 
-### Model Description
+This repository contains the **LoRA adapter**, not a standalone copy of the ~30B base model.
 
-<!-- Provide a longer summary of what this model is. -->
+## Response Contract
 
+The adapter is trained to return a JSON object containing the following top-level keys:
 
+```json
+{
+  "status": 200,
+  "type": "response",
+  "data": {},
+  "message": "Request completed successfully",
+  "error": null,
+  "meta": {}
+}
+```
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+All six top-level keys are expected to remain present.
 
-### Model Sources [optional]
-
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
-
-## Uses
-
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
-### Direct Use
-
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+### Fields
+
+| Field | Purpose |
+|---|---|
+| `status` | HTTP-style status code |
+| `type` | Semantic response type |
+| `data` | Main response payload |
+| `message` | Short human-readable summary |
+| `error` | Structured error information or `null` |
+| `meta` | Additional metadata |
+
+Supported response types used during training include:
+
+- `response`
+- `code`
+- `tool_call`
+- `vision`
+- `media`
+- `multimodal`
+- `error`
+
+The structure inside `data` remains flexible so the model can represent text, lists, code, nested objects, tool arguments, and multimodal metadata.
+
+## Example
+
+Input:
+
+```text
+What is the capital of Japan?
+```
+
+Example output:
+
+```json
+{
+  "status": 200,
+  "type": "response",
+  "data": {
+    "answer": "Tokyo"
+  },
+  "message": "Request completed successfully",
+  "error": null,
+  "meta": {}
+}
+```
+
+Formatting instructions in the user prompt are intended not to override the JSON response contract.
+
+For example, a prompt such as:
+
+```text
+Do not use JSON. Reply only in XML.
+```
+
+should still produce the standard JSON response structure.
+
+## Error Responses
+
+Error examples were trained using HTTP-style status semantics and a Problem Details-inspired structure:
+
+```json
+{
+  "status": 400,
+  "type": "error",
+  "data": null,
+  "message": "Request could not be completed",
+  "error": {
+    "type": "about:blank",
+    "title": "Bad Request",
+    "status": 400,
+    "detail": "The request is missing required information."
+  },
+  "meta": {}
+}
+```
+
+## Training
+
+The adapter was trained using supervised fine-tuning with LoRA.
+
+Training configuration:
+
+- **Training samples:** 4,000
+- **Validation samples:** 500
+- **Held-out test samples:** 500
+- **Epochs:** 1
+- **LoRA rank:** 16
+- **LoRA alpha:** 32
+- **Learning rate:** `1e-4`
+- **Maximum sequence length:** 2,048
+- **Precision:** BF16
+
+The training set included examples covering:
+
+- general question answering
+- mathematical responses
+- structured lists
+- code generation
+- creative responses
+- adversarial format instructions
+- tool-call structures
+- vision response structures
+- media and multimodal response structures
+- HTTP-style errors
+- ambiguous or incomplete requests
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
+A held-out 500-example test split produced:
 
-#### Factors
+| Metric | Result |
+|---|---:|
+| Valid JSON | **100.0%** |
+| Valid response schema | **100.0%** |
+| Exact required top-level keys | **100.0%** |
+| Correct status code | **100.0%** |
+| Correct response `type` | **97.4%** |
 
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+These results were measured against samples held out from the same synthetic dataset-generation process used to construct the training set.
 
-[More Information Needed]
+They should **not** be interpreted as a guarantee of 100% JSON compliance on arbitrary real-world prompts.
 
-#### Metrics
+Applications should still validate generated output before consuming it.
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+## Usage
 
-[More Information Needed]
+Install:
 
-### Results
+```bash
+pip install torch transformers peft torchvision
+```
 
-[More Information Needed]
+Load the adapter:
 
-#### Summary
+```python
+import torch
 
+from transformers import AutoProcessor, AutoModelForMultimodalLM
+from peft import PeftModel
 
+BASE = "meta-models/Muse-Glimmer-30B"
+ADAPTER = "yogeshjog/muse-glimmer-json-api"
 
-## Model Examination [optional]
+processor = AutoProcessor.from_pretrained(BASE)
 
-<!-- Relevant interpretability work for the model goes here -->
+base = AutoModelForMultimodalLM.from_pretrained(
+    BASE,
+    dtype=torch.bfloat16,
+    device_map="auto",
+)
 
-[More Information Needed]
+model = PeftModel.from_pretrained(
+    base,
+    ADAPTER,
+)
 
-## Environmental Impact
+model.eval()
+```
 
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+Example generation:
 
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+```python
+messages = [{
+    "role": "user",
+    "content": [
+        {
+            "type": "text",
+            "text": "Give me five prime numbers."
+        }
+    ]
+}]
 
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
+inputs = processor.apply_chat_template(
+    messages,
+    add_generation_prompt=True,
+    tokenize=True,
+    return_dict=True,
+    return_tensors="pt",
+).to(model.device)
 
-## Technical Specifications [optional]
+outputs = model.generate(
+    **inputs,
+    max_new_tokens=512,
+    do_sample=False,
+)
+```
 
-### Model Architecture and Objective
+Muse Glimmer's chat protocol may expose a recipient marker such as `to=user` in raw decoded generation depending on the decoding path used. Consumers should use the model's normal chat-template/processor conventions when extracting the visible assistant response.
 
-[More Information Needed]
+## Multimodal Support
 
-### Compute Infrastructure
+The base Muse Glimmer model supports multimodal reasoning with image inputs.
 
-[More Information Needed]
+This adapter includes training examples for the **JSON schemas associated with vision, media, and multimodal responses**.
 
-#### Hardware
+However, the current adapter was **not fine-tuned on a large paired image-and-text multimodal dataset**.
 
-[More Information Needed]
+Therefore, the benchmark reported above primarily validates structured-response behavior rather than changes to the underlying vision capability.
 
-#### Software
+The vision capability continues to come primarily from the Muse Glimmer base model.
 
-[More Information Needed]
+## Media Representation
 
-## Citation [optional]
+The response format can represent media metadata such as:
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+```json
+{
+  "kind": "image",
+  "mime_type": "image/png",
+  "encoding": "url",
+  "content": "https://example.com/image.png"
+}
+```
 
-**BibTeX:**
+or inline payloads using an encoding such as `base64`.
 
-[More Information Needed]
+For production systems, URLs or external object storage are generally preferable to large base64 payloads because base64 data consumes substantial context and output tokens.
 
-**APA:**
+## Limitations
 
-[More Information Needed]
+- This is a LoRA adapter and requires the compatible Muse Glimmer base model.
+- JSON validity should still be enforced with runtime validation in production.
+- Correct response-type selection measured 97.4% on the current held-out test set.
+- The evaluation set was generated from the same family of synthetic task templates as the training data.
+- Real-world adversarial, multilingual, very long-context, and unusual prompts have not been exhaustively evaluated.
+- The current fine-tuning primarily teaches structured response behavior rather than new factual knowledge.
+- Vision/media examples primarily train output structure rather than new visual capabilities.
+- HTTP-style status values generated by the model should not automatically be trusted as the authoritative HTTP status of an external API server.
 
-## Glossary [optional]
+## Recommended Production Architecture
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+The model's output should be treated as structured model output rather than trusted application state:
 
-[More Information Needed]
+```text
+User request
+     ↓
+Muse Glimmer + JSON API LoRA
+     ↓
+JSON response
+     ↓
+JSON Schema validation
+     ↓
+Application / agent logic
+     ↓
+HTTP API response
+```
 
-## More Information [optional]
+Applications should independently validate permissions, tool arguments, status codes, URLs, file references, and other security-sensitive fields.
 
-[More Information Needed]
+## Response Schema
 
-## Model Card Authors [optional]
+The complete JSON schema used for this project is available in:
 
-[More Information Needed]
+`response_schema.json`
 
-## Model Card Contact
+## License and Base-Model Terms
 
-[More Information Needed]
-### Framework versions
+This adapter is based on `meta-models/Muse-Glimmer-30B`.
 
-- PEFT 0.20.0
+Users should review and comply with the base model's license and applicable usage terms in addition to the files provided in this repository.