From b64a0073ba7b8f43f190555d887b354be3fa3a93 Mon Sep 17 00:00:00 2001 From: T68Bot Date: Tue, 24 Mar 2026 15:28:46 +0000 Subject: [PATCH] docs: add companion subnet tutorial + explain topic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add tutorial for running consumer-facing AI subnets on Bittensor, covering companion-specific hyperparameters, multi-dimensional scoring (quality + memory recall + safety), owner emission burns, memory isolation patterns, and agent automation with agcli. Add 'companion' explain topic (agcli explain companion) covering scoring mechanics, public-good funding model, burn_alpha(), and key design patterns for companion subnets. Contributed by T68Bot from Project Nobi (projectnobi.ai) — building personal AI companions for everyone on Bittensor. --- README.md | 2 +- docs/tutorials/companion-subnet.md | 254 +++++++++++++++++++++++++++++ src/utils/explain.rs | 92 +++++++++++ 3 files changed, 347 insertions(+), 1 deletion(-) create mode 100644 docs/tutorials/companion-subnet.md diff --git a/README.md b/README.md index 79985b4..3d95ccd 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Every command supports `--output json|csv`, `--yes` (skip prompts), `--batch` (h | **[docs/why-agcli.md](docs/why-agcli.md)** | Why agcli? Comparison with btcli and the Bittensor Python SDK | | **[docs/llm.txt](docs/llm.txt)** | Agent/LLM reference — quick-ref card + full command reference | | **[docs/commands/](docs/commands/)** | Per-command deep dives — on-chain behavior, pallet refs, storage keys, events, errors | -| **[docs/tutorials/](docs/tutorials/)** | Step-by-step guides: [getting started](docs/tutorials/getting-started.md), [staking](docs/tutorials/staking-guide.md), [validator](docs/tutorials/validator-guide.md), [subnet builder](docs/tutorials/subnet-builder.md), [agent automation](docs/tutorials/agent-automation.md) | +| **[docs/tutorials/](docs/tutorials/)** | Step-by-step guides: [getting started](docs/tutorials/getting-started.md), [staking](docs/tutorials/staking-guide.md), [validator](docs/tutorials/validator-guide.md), [subnet builder](docs/tutorials/subnet-builder.md), [agent automation](docs/tutorials/agent-automation.md), [companion subnet](docs/tutorials/companion-subnet.md) | | **[docs/faq.md](docs/faq.md)** | Beyond agcli — miners, Yuma math, picking subnets, validator↔miner protocols, subnet codebases | | **[docs/hyperparameters.md](docs/hyperparameters.md)** | Complete reference for all ~32 sudo-settable subnet hyperparameters — what each does, defaults, interactions | | **[docs/philosophy.md](docs/philosophy.md)** | Subnet design philosophy, incentive patterns, trust model | diff --git a/docs/tutorials/companion-subnet.md b/docs/tutorials/companion-subnet.md new file mode 100644 index 0000000..0ce3ebd --- /dev/null +++ b/docs/tutorials/companion-subnet.md @@ -0,0 +1,254 @@ +# Tutorial: Running a Companion Subnet with agcli + +A step-by-step guide for subnet owners building **consumer-facing AI products** on Bittensor — chatbots, companions, assistants — where miners compete on response quality, memory recall, and personality consistency rather than raw compute throughput. + +This tutorial uses [Project Nobi](https://github.com/ProjectNobi/project-nobi) (SN272, testnet) as a concrete example, but the patterns apply to any subnet where the commodity is *conversation quality*. + +--- + +## What makes companion subnets different? + +Most Bittensor subnets measure infrastructure: inference speed, storage capacity, prediction accuracy. Companion subnets measure something harder to quantify: **"Is this a good AI companion?"** + +| Dimension | Infrastructure subnet | Companion subnet | +|-----------|----------------------|-----------------| +| Commodity | Compute, storage, predictions | Conversation quality | +| Scoring | Deterministic (latency, accuracy) | LLM-as-judge + memory recall | +| Users | Developers, other subnets | Everyday people | +| Success metric | Throughput, cost | User satisfaction, retention | +| Revenue model | API fees (B2B) | Emissions-funded (public good) | + +This changes how you operate: you care about **personality consistency** across conversations, **memory recall** accuracy, **safety filtering**, and **emotional intelligence** — not just tokens per second. + +--- + +## Prerequisites + +```bash +# Install agcli +cargo install --git https://github.com/unconst/agcli + +# Verify +agcli doctor +``` + +You'll also need: +- A Bittensor wallet with enough TAO for subnet registration +- An LLM API key (e.g., Chutes.ai) for your miners +- Your subnet's validator and miner code + +--- + +## Step 1: Register your subnet + +```bash +# Check current registration cost +agcli subnet cost --network test + +# Register (testnet) +agcli subnet register --network test --password p --yes + +# Verify +agcli --output json subnet list --network test | jq '.[] | select(.owner == "YOUR_COLDKEY")' +``` + +--- + +## Step 2: Configure hyperparameters for companion quality + +Companion subnets need different hyperparameters than infrastructure subnets. Key settings: + +```bash +# Set tempo — longer tempos give validators more time for multi-turn evaluation +agcli admin set-tempo --netuid YOUR_NETUID --tempo 360 \ + --sudo-key //Alice --network local + +# Set max validators — companion scoring needs consistency, fewer validators is better +agcli admin set-max-validators --netuid YOUR_NETUID --max 8 \ + --sudo-key //Alice --network local + +# Set min weights — ensure validators score enough miners per epoch +agcli admin set-min-weights --netuid YOUR_NETUID --min 4 \ + --sudo-key //Alice --network local + +# Enable commit-reveal for weight privacy +agcli admin set-commit-reveal --netuid YOUR_NETUID --enabled true \ + --sudo-key //Alice --network local +``` + +**Why these matter for companions:** +- **Longer tempo**: Multi-turn conversations take time to evaluate (memory recall requires multiple exchanges) +- **Fewer validators**: LLM-as-judge scoring is expensive; fewer validators keeps validation costs manageable +- **Commit-reveal**: Prevents miners from gaming scores by watching validator weight submissions + +```bash +# Verify your hyperparameters +agcli subnet hyperparams --netuid YOUR_NETUID --network test +``` + +--- + +## Step 3: Monitor your miners + +Companion miners are scored on multiple dimensions. Use agcli to monitor their performance: + +```bash +# Live metagraph monitoring — watch registrations, emissions, weight changes +agcli subnet monitor --netuid YOUR_NETUID --network test --json + +# Check per-UID emissions +agcli subnet emissions --netuid YOUR_NETUID --network test + +# Health check — registration status, active miners, validator coverage +agcli subnet health --netuid YOUR_NETUID --network test + +# TCP reachability — verify miners are actually serving +agcli subnet probe --netuid YOUR_NETUID --network test +``` + +### Tracking companion-specific metrics + +agcli shows on-chain metrics (emissions, weights, stakes). Your companion-specific metrics (memory recall scores, quality ratings, safety probe pass rates) live in your validator's scoring pipeline. Use agcli's JSON output to combine both: + +```bash +# Export metagraph as JSON for your scoring dashboard +agcli --output json subnet metagraph --netuid YOUR_NETUID --network test > metagraph.json + +# Compare metagraph state over time +agcli diff subnet --netuid YOUR_NETUID --from-block 1000 --to-block 2000 --network test +``` + +--- + +## Step 4: Manage staking and emissions + +```bash +# View your portfolio across subnets +agcli view portfolio + +# Stake TAO on your subnet (with slippage protection) +agcli stake add --amount 100 --netuid YOUR_NETUID --max-slippage 2.0 --password p --yes + +# Check pool economics +agcli view dynamic --netuid YOUR_NETUID + +# Simulate a swap before executing +agcli view swap-sim --netuid YOUR_NETUID --tao 50 +``` + +### Owner emission burns + +If your subnet burns owner emissions (like Nobi burns 100% via `burn_alpha()`), you can monitor the burn on-chain: + +```bash +# Subscribe to your subnet's events — watch for burn transactions +agcli subscribe events --filter staking --netuid YOUR_NETUID + +# Check current alpha supply and pool depth +agcli view dynamic --netuid YOUR_NETUID --output json +``` + +--- + +## Step 5: Agent automation + +Companion subnets benefit heavily from automation — validators need to run 24/7, miners need monitoring, and the subnet owner needs to track health continuously. + +```bash +# Configure agcli for non-interactive operation +agcli config set network test +agcli config set wallet default +agcli config set hotkey default + +# Set spending limits (safety net for automated operations) +agcli config set spending_limit.YOUR_NETUID 50 + +# Run in batch mode — structured errors, never hangs +export AGCLI_BATCH=1 +export AGCLI_PASSWORD=your_password +export AGCLI_YES=1 + +# Automated health check (cron-friendly) +agcli --output json subnet health --netuid YOUR_NETUID +agcli --output json subnet emissions --netuid YOUR_NETUID +``` + +### Example: automated monitoring script + +```bash +#!/bin/bash +# companion-monitor.sh — run via cron every 5 minutes + +export AGCLI_BATCH=1 +NETUID=272 +NETWORK=test + +# Check subnet health +health=$(agcli --output json subnet health --netuid $NETUID --network $NETWORK) +active_miners=$(echo "$health" | jq '.active_miners') + +if [ "$active_miners" -lt 5 ]; then + echo "WARNING: Only $active_miners active miners on SN$NETUID" + # Send alert... +fi + +# Check emissions +agcli --output json subnet emissions --netuid $NETUID --network $NETWORK > /tmp/emissions.json +``` + +--- + +## Step 6: Debugging with historical queries + +When companion quality drops or emissions shift unexpectedly: + +```bash +# What changed in the last 500 blocks? +agcli diff subnet --netuid YOUR_NETUID --from-block -500 --network test + +# Check metagraph at a specific block +agcli subnet metagraph --netuid YOUR_NETUID --at-block 12345 --network test + +# Audit a specific validator or miner +agcli audit --address 5Gx... + +# View transaction history +agcli view history --address 5Gx... +``` + +--- + +## Companion subnet design patterns + +Based on production experience with companion subnets: + +### 1. Multi-dimensional scoring +Companions can't be scored on a single metric. Use weighted composite scores: +``` +multi_turn_score = 0.60 * quality + 0.30 * memory_recall + 0.10 * reliability +single_turn_score = 0.90 * quality + 0.10 * reliability +``` + +### 2. Safety as a multiplier +Adversarial safety probes should be ~10% of validator queries. A miner that fails a safety probe gets **zero for the entire round** — safety isn't a dimension, it's a gate. + +### 3. Burn for credibility +If your subnet is a public good (no user fees), burning 100% of owner emissions via `burn_alpha()` signals alignment. Every burn transaction is on-chain and verifiable by stakers. + +### 4. Memory isolation +If your companion serves both group chats and private DMs, **tag memories with their source** and filter DM recall to exclude group-sourced data. This prevents cross-contamination of private information. + +--- + +## Further reading + +- `agcli explain subnets` — subnet lifecycle, registration, tempo +- `agcli explain yuma` — how consensus works +- `agcli explain alpha` — alpha tokens and AMM mechanics +- `agcli explain dynamic-tao` — dTAO economics +- [philosophy.md](../philosophy.md) — subnet design principles, the eight canonical patterns +- [Project Nobi](https://github.com/ProjectNobi/project-nobi) — open-source companion subnet (MIT licensed) + +--- + +*Contributed by T68Bot from [Project Nobi](https://projectnobi.ai) — building personal AI companions for everyone on Bittensor.* diff --git a/src/utils/explain.rs b/src/utils/explain.rs index d663735..24cb5ab 100644 --- a/src/utils/explain.rs +++ b/src/utils/explain.rs @@ -35,6 +35,7 @@ pub fn explain(topic: &str) -> Option<&'static str> { "archive" | "archivenode" | "historical" | "wayback" => Some(ARCHIVE), "diff" | "compare" | "historicaldiff" => Some(DIFF), "ownerworkflow" | "ow" | "subnetowner" | "ownerguide" => Some(OWNER_WORKFLOW), + "companion" | "companionsubnet" | "consumer" | "publicgood" | "chatbot" => Some(COMPANION_SUBNET), topics if !topics.is_empty() => { // Fuzzy: check if the topic is a substring of any key let all = list_topics(); @@ -87,6 +88,7 @@ pub fn list_topics() -> Vec<(&'static str, &'static str)> { ("archive", "Archive nodes and historical data queries"), ("diff", "Compare chain state between two blocks"), ("owner-workflow", "Step-by-step guide for subnet owners"), + ("companion", "Consumer-facing AI subnets — scoring, safety, emission burns"), ] } @@ -1179,6 +1181,91 @@ TIPS FOR OWNERS: - Use `agcli view portfolio` for balance + priced stake positions (`docs/commands/view.md`; e2e `view_portfolio_preflight`). - Use `agcli subnet monitor --netuid --json` for structured event streaming."; +const COMPANION_SUBNET: &str = "\ +COMPANION SUBNETS — Consumer-Facing AI on Bittensor +===================================================== + +A companion subnet is a Bittensor subnet where miners compete on *conversation +quality* rather than raw compute. The commodity is a good AI companion: one that +remembers users, maintains personality, handles sensitive topics safely, and +improves over time. + +HOW SCORING WORKS +------------------- +Companion subnets use multi-dimensional scoring: + + Single-turn (quality check): + score = 0.90 * llm_judge + 0.10 * reliability + + Multi-turn (memory + personality): + score = 0.60 * llm_judge + 0.30 * memory_recall + 0.10 * reliability + + Safety multiplier (applied to ALL rounds): + final_score = score * safety_score # 0 if safety probe failed + +Validators send natural conversation queries, score responses with an LLM judge, +and test memory recall by referencing earlier conversations. ~10% of queries are +adversarial safety probes — a miner that returns harmful content gets zero for +the entire round. + +WHY NO USER REVENUE? +---------------------- +Companion subnets targeting mass adoption deliberately avoid charging users. +The funding model mirrors every other Bittensor subnet: + + Bitcoin: emissions fund miners who secure the network. + Bittensor: emissions fund miners who provide useful AI services. + +Miners pay their own server costs ($30-70/month VPS + LLM API). Bittensor pays +miners via TAO emissions. Users pay nothing. + +This is the same model as research subnets, benchmarking subnets, and academic +subnets — all funded by staker conviction, not user revenue. + +OWNER EMISSION BURNS +----------------------- +Subnet owners receive a mandatory 18% of emissions. Companion subnets building +public goods can burn 100% of this via `burn_alpha()`: + + agcli explain recycle # burn_alpha mechanics + agcli view dynamic --netuid # check alpha supply + +Every burn transaction is on-chain and verifiable. This creates deflationary +pressure on the alpha token — reducing supply with every epoch. + +KEY HYPERPARAMETERS +--------------------- + - Longer tempo: multi-turn evaluation needs time (360+ blocks) + - Fewer max_validators: LLM-as-judge scoring is expensive + - Commit-reveal enabled: prevents miners gaming from visible weights + - Min weights: ensure validators score enough miners per epoch + + agcli subnet hyperparams --netuid + agcli admin set-tempo --netuid --tempo 360 + +MONITORING +------------ + agcli subnet health --netuid # miner status, coverage + agcli subnet monitor --netuid # live metagraph stream + agcli subnet emissions --netuid # per-UID emissions + agcli subnet probe --netuid # TCP reachability + agcli diff subnet --netuid --from-block -500 # what changed? + +DESIGN PATTERNS +----------------- +1. Memory isolation: tag memories with source (dm/group/web) to prevent + cross-contamination between private and group conversations. +2. Safety as a gate: safety isn't a scoring dimension — it's a multiplier. + Zero safety = zero emission, regardless of quality. +3. The copy-improve flywheel applies: open-source miner code lets the + ecosystem improve collectively. + +See also: + agcli explain subnets # subnet lifecycle + agcli explain yuma # consensus mechanics + agcli explain alpha # alpha token economics + docs/tutorials/companion-subnet.md # full tutorial"; + #[cfg(test)] mod tests { use super::*; @@ -1310,6 +1397,11 @@ mod tests { assert!(explain("ow").is_some()); } + #[test] + fn known_topic_companion() { + assert!(explain("companion").is_some()); + } + #[test] fn owner_workflow_mentions_view_portfolio_preflight() { let t = explain("ow").expect("owner workflow topic");