README.md

---
license: apache-2.0
tags:
  - solana
  - agents
  - lora
  - peft
  - onchain-ai
  - x402
  - trading
---

<p align="center">
  <img src="https://raw.githubusercontent.com/Solizardking/solana-clawd/main/assets/solana-ai-model-kit.svg" alt="Solana AI Model Kit" width="100%"/>
</p>

# Solana Clawd

The Hugging Face home for the Solana Clawd model stack: public-safe datasets,
LoRA adapters, evaluation artifacts, and CAAP/1.0 registry metadata for
Solana-native AI agents.

**GitHub:** [Solizardking/solana-clawd](https://github.com/Solizardking/solana-clawd)  
**Onchain registry:** [onchain.x402.wtf](https://onchain.x402.wtf)  
**Registry JSON:** [/.well-known/clawd-registry.json](https://onchain.x402.wtf/.well-known/clawd-registry.json)  
**Model kit:** [`ai-training/model-kit`](https://github.com/Solizardking/solana-clawd/tree/main/ai-training/model-kit)

## Solana AI Model Kit

The kit is a one-shot path for building, publishing, training, registering, and
serving Solana AI models.

```bash
# Safe default: clone/update the repo, audit local release state, print next steps.
curl -fsSL https://raw.githubusercontent.com/Solizardking/solana-clawd/main/ai-training/scripts/solana_ai_model_kit.sh | bash

# From a checkout:
npm run model-kit
npm run model-kit:register
npm run model-kit:train
```

Live CAAP/1.0 registry POST:

```bash
bash ai-training/scripts/solana_ai_model_kit.sh \
  --local \
  --live-register \
  --hf-model YOUR_ORG/your-model \
  --endpoint https://your-router.example/v1 \
  --eval-accuracy 0.60 \
  --dataset-size 35173
```

## Current Artifacts

### Datasets

| Repo | Examples | What is inside |
| --- | ---: | --- |
| [`solanaclawd/solana-clawd-core-ai-instruct`](https://huggingface.co/datasets/solanaclawd/solana-clawd-core-ai-instruct) | 35,173 | Public-safe blend of `core-ai`, Helius/Clawd runtime files, knowledge JSONL, and cleaned SFT examples |
| [`solanaclawd/solana-clawd-realtime-research-instruct`](https://huggingface.co/datasets/solanaclawd/solana-clawd-realtime-research-instruct) | 29,058 | PDFs, notebooks, parquet Solana QA, ZK skill context, and realtime document ingestion outputs |
| [`solanaclawd/solana-clawd-nvidia-trading-factory-instruct`](https://huggingface.co/datasets/solanaclawd/solana-clawd-nvidia-trading-factory-instruct) | 142 | NVIDIA trading-factory plans, Solana spot/perps scenarios, cuFOLIO/cuOpt handoffs, Phoenix/Vulcan paper strategies, Rise read plans, and risk refusals |
| [`solanaclawd/solana-clawd-eval`](https://huggingface.co/datasets/solanaclawd/solana-clawd-eval) | 13 | Held-out capability, calibration, and red-team prompts |

### Models

| Repo | Status | Base |
| --- | --- | --- |
| [`solanaclawd/solana-clawd-core-ai-1.5b-lora`](https://huggingface.co/solanaclawd/solana-clawd-core-ai-1.5b-lora) | Recovery job `ordlibrary/6a35a6833093dba73ce2a86b` is running on `a100-large`; first HF job trained then failed during Hub push | `Qwen/Qwen2.5-1.5B-Instruct` |
| [`solanaclawd/solana-nvidia-trading-factory-8b-lora`](https://huggingface.co/solanaclawd/solana-nvidia-trading-factory-8b-lora) | Completed HF job `ordlibrary/6a35a2ce953ed90bfb945009`; train loss 1.1692, eval loss 0.8064, eval token accuracy 0.8547 | `NousResearch/Hermes-3-Llama-3.1-8B` |
| [`solanaclawd/solana-clawd-1.5b`](https://huggingface.co/solanaclawd/solana-clawd-1.5b) | Merged-model target | Qwen2.5 1.5B + LoRA |
| [`solanaclawd/solana-clawd-7b-lora`](https://huggingface.co/solanaclawd/solana-clawd-7b-lora) | Optional larger target | Qwen2.5 7B |

## Training Status

- Active Core AI retry: `ordlibrary/6a35a6833093dba73ce2a86b`
- Core recovery evidence: loaded `solanaclawd/solana-clawd-core-ai-instruct`,
  tokenized all `31,655` train rows, entered training, and reached at least
  step `221/3957` with mean token accuracy around `0.79`.
- Superseded failed trading job: `ordlibrary/6a359f0e953ed90bfb944faf`
- Failure mode: the HF job tried to load `/data/nvidia_trading_factory_processed`
  instead of the published Hub dataset.
- Fix: `scripts/train_lora.py` now falls back to `dataset_repo` when the
  configured local path is absent, and `prepare_dataset.py` normalizes metadata
  across train/eval/test splits for Hub pushes.
- Superseded failed replacement: `ordlibrary/6a35a02d953ed90bfb944fe3`
- Second fix: Hermes exposes `tokenizer.chat_template` as a dict and TRL
  expected a string when assistant-only loss was enabled. The trainer now
  normalizes dict templates and disables assistant-only loss when generation
  markers are unavailable.
- Successful retry: `ordlibrary/6a35a2ce953ed90bfb945009`
- Final evidence: active retry loaded the published Hub dataset, tokenized
  train/eval splits, built `SFTTrainer`, completed 48/48 steps, pushed adapter
  files, and verified `adapter_config.json` plus `adapter_model.safetensors`
  on Hub.
- Final metrics: train loss `1.1692`, eval loss `0.8064`,
  eval mean token accuracy `0.8547`.
- W&B: disabled unless `WANDB_API_KEY` is present in the launching environment.

## Onchain Registry

The registry API is served by OnChain-AI and indexed at `onchain.x402.wtf`.

```bash
curl -sS https://onchain.x402.wtf/.well-known/clawd-registry.json | python3 -m json.tool
curl -sS "https://onchain.x402.wtf/api/models?hf_id=solanaclawd/solana-clawd-core-ai-1.5b-lora" | python3 -m json.tool
```

Local sidecar:

```bash
export ONCHAIN_AI_ROOT=/Users/8bit/Downloads/OnChain-Ai-main

cd "$ONCHAIN_AI_ROOT/backend"
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
PORT=5001 python3 main.py

cd "$ONCHAIN_AI_ROOT/frontend"
npm install
VITE_API_BASE_URL=http://localhost:5001 npm run dev
```

## Safety

- No private keys, API tokens, OAuth client secrets, Google ADC JSON, W&B keys,
  or HF tokens belong in datasets, cards, commits, manifests, or Hub uploads.
- Trading-factory data defaults to paper mode.
- Live execution belongs outside model training data and requires explicit
  operator approval, wallet isolation, and pre-trade risk checks.
- The model is the planning layer; key-bearing execution clients are separate
  trust domains.

## Links

- [Solana Clawd GitHub](https://github.com/Solizardking/solana-clawd)
- [AI training README](https://github.com/Solizardking/solana-clawd/tree/main/ai-training)
- [Model kit guide](https://github.com/Solizardking/solana-clawd/tree/main/ai-training/model-kit)
- [Dataset card](https://github.com/Solizardking/solana-clawd/blob/main/ai-training/dataset_card.md)
- [Model card](https://github.com/Solizardking/solana-clawd/blob/main/ai-training/model_card.md)