Skip to content

Merge Main to Staging #732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bkb2135 merged 19 commits into from
May 15, 2025
Merged

Merge Main to Staging #732

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
9ce554d
GEN-1220 initial debug logs added
May 12, 2025
b0e46e0
GEN-1220 type and length mistral response logs
May 12, 2025
8a3bd23
add debug settings
gevagorou-mai May 12, 2025
3dce79a
Merge remote-tracking branch 'origin/main' into gen_1220_debug_deep_r…
gevagorou-mai May 12, 2025
9c96dcd
make torch nonn optional
gevagorou-mai May 13, 2025
1f552e9
rm pydevd
gevagorou-mai May 13, 2025
048fb7a
Change job store to emit chunks
bkb2135 May 13, 2025
df285bc
GEN-1220 added seq_id to chunks, stored openai api in .env.api, added…
bkb2135 May 13, 2025
89cbe12
add utc offset
bkb2135 May 14, 2025
9467c92
Merge remote-tracking branch 'origin/main' into gen_1220_debug_deep_r…
gevagorou-mai May 14, 2025
5401a0a
Change JobStore to store chunks
gevagorou-mai May 14, 2025
2585358
Removed delete function in job_store.py
gevagorou-mai May 14, 2025
500fdeb
Rename methods
gevagorou-mai May 14, 2025
32aff62
Rm data, choices and delta key names
bkb2135 May 14, 2025
bbf02c0
Change type of result parameter in the doc string
gevagorou-mai May 14, 2025
3d19010
Run pre-commit hook
gevagorou-mai May 14, 2025
4ef053d
Merge pull request #726 from macrocosm-os/gen_1220_debug_deep_research_2
bkb2135 May 14, 2025
e301380
Updated Readme
richwardle May 14, 2025
979553a
Merge pull request #728 from macrocosm-os/SN1-481-enhance-docs-for-in…
bkb2135 May 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 107 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,66 +6,147 @@

<div align="center">

# **Bittensor SN1** <!-- omit in toc -->
# **Bittensor SN1: Apex - The Future of Decentralized AI** <!-- omit in toc -->
[![Discord Chat](https://img.shields.io/discord/308323056592486420.svg)](https://discord.gg/bittensor)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/macrocosm-os/apex)

---

### The Incentivized Internet <!-- omit in toc -->
Subnet 1 is the most intelligent inference model on Bittensor. As the first agent to achieve chain of thought reasoning on the protocol, it has long been the network's pioneer of decentralized intelligence. This repository is the **official codebase for Bittensor Subnet 1 (SN1) v1.0.0+, which was released on 22nd January 2024**.

[Discord](https://discord.gg/bittensor) • [Network](https://taostats.io/) • [Research](https://bittensor.com/whitepaper)

</div>

---

This repository is the **official codebase for Bittensor Subnet 1 (SN1) v1.0.0+, which was released on 22nd January 2024**. To learn more about the Bittensor project and the underlying mechanics, [read here.](https://docs.bittensor.com/).
## Our Product Suite: Apex & Beyond

# Introduction
Subnet 1 has several products:

This repo defines an incentive mechanism to create a distributed conversational AI for Subnet 1 (SN1).
### Apex Chat
This is our chat interface which provides a range of high-quality models, allowing users to select the model most appropriate for their own use case. Apex offers five distinct variations:

Validators and miners are based on large language models (LLM). The validation process uses **internet-scale datasets and goal-driven behaviour to drive human-like conversations**.
* **Basic** - our fastest model, perfect for conversations
* **Combined** - for results from multiple resources, for well-rounded responses
* **Web-enhanced** - for results driven by current online results
* **Deep Researcher** - for in-depth responses with individual steps
* **Reasoning** - for higher quality answers with advanced results

Try the Apex Chat app here: [app.macrocosmos.ai/apex](http://app.macrocosmos.ai/apex)

</div>
For a more detailed read, check our docs here: [docs.macrocosmos.ai/subnets/subnet-1-apex](https://docs.macrocosmos.ai/subnets/subnet-1-apex)

# Usage
You can also access Subnet 1, Apex via the API. Find out more here: [docs.macrocosmos.ai/developers/api-documentation/sn1-apex](https://docs.macrocosmos.ai/developers/api-documentation/sn1-apex)

<div align="center">
### Mission Commander
This is an agentic LLM chatbot built into Gravity, designed to help you pick the right terms and phrases for your data-scraping needs. Simply tell it what information you want and it'll offer suggestions and help with brainstorming. Mission Commander is built with Subnet 1, Apex, also owned by Macrocosmos. It lowers the barrier-of-entry even.

**[For Validators](./docs/validator.md)** · **[For Miners](./docs/epistula_miner.md)** · **[API Documentation]((./docs/API_docs.md))**
Try Mission Commander via Gravity here: [app.macrocosmos.ai/gravity](http://app.macrocosmos.ai/gravity)

For a more detailed read, check our docs here: [docs.macrocosmos.ai/constellation-user-guides/gravity](https://docs.macrocosmos.ai/constellation-user-guides/gravity)

</div>
### MCP (Macrocosmos Connect Protocol)
You can integrate Subnet 1, Apex, directly into Claude and Cursor via our MCP. This allows you to access our web-search options and inference via other routes, rather than only from our website. Will provide URL to Apex, api key, and a guide how to use the model.

# Agentic Tasks
Try the MCP by following our guide here: [docs.macrocosmos.ai/developers/tools/macrocosmos-mcp](https://docs.macrocosmos.ai/developers/tools/macrocosmos-mcp)

Subnet one utilizes the concept of "Tasks" to control the behavior of miners. Validator create a variety of tasks, which include a "challenge" for the miner to solve, and sends them to 100 miners, scoring all the completions they send back.
### Productizing other subnets with Apex
Apex is also powering inference across Bittensor. It's integrated with Squad.ai, Rayon Labs' agent platform built on SN64, Chutes - which means that Apex provides the reasoning abilities for agents built on Squad, boosting their capabilities and adding value to Rayon Labs through its cost-effective efficiencies. In other words, Apex provides more agentic opportunities to Bittensor.

## Market Opportunity & Traction

Subnet 1 provides access to decentralized, competitive intelligence. As its speed of inference continues to rise, and miner efficiencies compound, Apex is able to provide fast, flexible, and efficient inference at scale. With the market for AI applications only growing, the ability to provide fast, efficient inference while keeping cost per token low will become increasingly desirable, putting Apex in a strong position to benefit - and making it a strong investment proposition.

By combining real‑time web search with LLM‑grade synthesis in a single, developer‑friendly endpoint, the service sits squarely at the intersection of two explosive trends — AI‑native application stacks and the API‑first economy. Demand spans customer-facing chatbots, autonomous agents, research copilots, and data‑driven decision dashboards, giving the platform both horizontal reach and strong pricing power. Early adopters report dramatic boosts in user engagement and analyst productivity, and investors view the recurring‑revenue potential as "SaaS‑plus," since the engine continuously improves with every query. In short, the product is meeting a surging, underserved need at precisely the right moment, positioning it for rapid, sustainable growth.

### Indicators that this subnet's value will rise
Subnet 1 provides access to decentralized, competitive intelligence. As its speed of inference continues to rise, and miner efficiencies compound, Apex is able to provide fast, flexible, and efficient inference at scale. With the market for AI applications only growing, the ability to provide fast, efficient inference while keeping cost per token low will become increasingly desirable, putting Apex in a strong position to benefit - and making it a strong investment proposition.

By combining real‑time web search with LLM‑grade synthesis in a single, developer‑friendly endpoint, the service sits squarely at the intersection of two explosive trends — AI‑native application stacks and the API‑first economy. Demand spans customer-facing chatbots, autonomous agents, research copilots, and data‑driven decision dashboards, giving the platform both horizontal reach and strong pricing power. Early adopters report dramatic boosts in user engagement and analyst productivity, and investors view the recurring‑revenue potential as “SaaS‑plus,” since the engine continuously improves with every query. In short, the product is meeting a surging, underserved need at precisely the right moment, positioning it for rapid, sustainable growth.


### Long-term value potential
Thanks to its distributed architecture, Apex has the potential to provide inference at a scale, speed, and efficiency outmatching centralized competitors.

Moreover, many of the most valuable use cases for AI - including law, finance, and health - are so sensitive to data privacy that they cannot use centralized models. This creates a huge opportunity for decentralized competitors to provide decentralized alternatives that provide intelligence without amassing centralized data. As the most intelligent model on Bittensor, itself the foremost DeAI protocol on-chain, Apex is very well positioned to take advantage of this opportunity. For those who believe in DeAI, an investment in Subnet 1 represents a strong prospect.

### Interest from customers and users
Subnet 1, Apex has already built up strong support and positive user feedback. It consistently ranks in the top 10 subnets. It displays deep and broad market support. Along with Subnet 13, another Macrocosmos subnet, Apex was the only subnet to be available on Squad.ai, Rayon Labs' agent platform built on Sibnet 64, Chutes (itself the top-performing subnet on Bittensor) - showing its reliability, value, and desirability across Bittensor.

## Task Descriptions
## Key Use Cases & Potential
Subnet 1, Apex, has a range of use-cases:
* Agentic chat interfaces, designed to plug into other subnets or commercial tools.
* Fast and very cheap web search enhanced LLM inference.
* Deep research and reasoning models that can tackle complex mathematical and logic-based problems.

### 1. **Inference**
A question is given with some pre-seeded information and a random seed. The miner must perform an inference based on this information to provide the correct answer. Completions are scored based on similarity metrics.
Apex has the potential to become the flagship decentralized LLM experience across the tech world. By utilizing Bittensor's architecture, we offer speedy and low-cost inference that could soon rival SOTA models in the industry.

### 2. **Multistep Reasoning (MSRv2)**
This task operates in two stages: generative and discriminative.
In the generative stage, a single miner receives a challenge and generates a response.
In the discriminative stage, this generated response (or sometimes a validator-provided "real" answer) is presented to a set of discriminator miners. These discriminators must output a score (0-1) assessing the answer.
Rewards are then calculated: discriminators are rewarded based on how accurately their score reflects the ground truth (i.e., whether the answer was miner-generated or real). The original generator miner is rewarded based on the collective assessment of the discriminators. If a "real" answer was used, this portion of the reward is distributed among other non-discriminating miners.
## The Team Behind Subnet 1
Subnet 1 was built by Dr. Steffen Cruz, AKA @Macrocrux, when he was CTO of Bittensor. Steffen has led Apex through multiple iterations, overseeing its evolution into Bittensor's premiere provider of decentralized intelligence.

### 3. **Web Retrieval**
The miner is given a question based on a random web page and must return a scraped website that contains the answer. This requires searching the web to locate the most accurate and reliable source to provide the answer. The miner is scored based on the embedding similarity between the answer it returns and the original website that the validator generated the reference from.
Apex's engineering team is one of the most impressive on Bittensor. It includes Felix Quinque, who led its Chain of Thought, Reasoning, and Logits upgrades, Dmytro Brobenko with Organic Scoring and DeepResearcher, Rich Wardle's research and development, and Kalei Brady, who led GAN based architecture upgrade and leads SN1's Discord Community. It also receives the support of other Macrocosmos engineers, ensuring that Subnet 1 is one of the best-staffed projects on the protocol - all of which helps ensure its long-term viability.

# API Documentation
### Why this team is right for the project
Steffen Cruz designed Subnet 1 while CTO of Bittensor. His continued stewardship ensures ongoing retained knowledge, accrued from years of experience building on Bittensor and a deep understanding of how best to convene state-of-the-art intelligence on chain.

For detailed information on the available API endpoints, request/response formats, and usage examples, please refer to the [API Documentation](./docs/API_docs.md).
Will Squires, CEO and co-founder of Bittensor, first began working with Jacob Steeves (@Const) during Bittensor's Revolution upgrade in October 2023, meaning that Will contributed to the release enabling multiple subnets. Will's strong commercial background leading large multinational companies, combined with his experience in creating and leading AI start-up teams, ensure that Subnet 1, Apex has a strong leadership capable of both delivering innovation and establishing commercially viable partnerships.

## Technical Foundation (For Developers)
This repo defines an incentive mechanism to create a distributed conversational AI for Subnet 1 (SN1). Validators and miners are based on large language models (LLM). The validation process uses **internet-scale datasets and goal-driven behaviour to drive human-like conversations**. To learn more about the Bittensor project and the underlying mechanics, [read here.](https://docs.bittensor.com/).

### Agentic Tasks
Subnet one utilizes the concept of "Tasks" to control the behavior of miners. Validator create a variety of tasks, which include a "challenge" for the miner to solve, and sends them to 100 miners, scoring all the completions they send back.

#### Task Descriptions
1. **Inference**
A question is given with some pre-seeded information and a random seed. The miner must perform an inference based on this information to provide the correct answer. Completions are scored based on similarity metrics.

2. **Multistep Reasoning (MSRv2)**
This task operates in two stages: generative and discriminative.
In the generative stage, a single miner receives a challenge and generates a response.
In the discriminative stage, this generated response (or sometimes a validator-provided "real" answer) is presented to a set of discriminator miners. These discriminators must output a score (0-1) assessing the answer.
Rewards are then calculated: discriminators are rewarded based on how accurately their score reflects the ground truth (i.e., whether the answer was miner-generated or real). The original generator miner is rewarded based on the collective assessment of the discriminators. If a "real" answer was used, this portion of the reward is distributed among other non-discriminating miners.

3. **Web Retrieval**
The miner is given a question based on a random web page and must return a scraped website that contains the answer. This requires searching the web to locate the most accurate and reliable source to provide the answer. The miner is scored based on the embedding similarity between the answer it returns and the original website that the validator generated the reference from.

## Dashboards, Tools & Essential Resources

# Contribute
<div align="center">

**[Contribution guide](./assets/CONTRIBUTING.md)**
**Usage:** **[For Validators](./docs/validator.md)** · **[For Miners](./docs/epistula_miner.md)**

**API:** **[API Documentation](./docs/API_docs.md)** · [Subnet 1 API Docs](https://docs.macrocosmos.ai/developers/api-documentation/sn1-apex)

**Contribute:** **[Contribution guide](./assets/CONTRIBUTING.md)**

</div>

### General Resources
* **Website:** [macrocosmos.ai/sn1](https://macrocosmos.ai/sn1)
* **Apex Chat App:** [app.macrocosmos.ai/apex](http://app.macrocosmos.ai/apex)
* **SN1 Dashboard:** [macrocosmos.ai/sn1/dashboard](http://macrocosmos.ai/sn1/dashboard)
* *The Bittensor Subnet 1 Apex Dashboard gives builders, miners and delegators an instant, data-rich window into the network's beating heart: 30-day productivity charts and a real-time leaderboard expose each miner's incentive, emission and trust scores, letting anyone spot top performers and route TAO delegations with confidence.*
* *The same asymmetric evaluation pipeline that powers those metrics continuously suppresses hallucinations and, in the process, produces millions of high-quality tokens per day that flow straight into Subnet 37's fine-tuning stream—so the dashboard doubles as a live tap of fresh open-source training data; and because it links directly to Discord, GitHub and extensive developer docs, newcomers can jump from insight to implementation in a click, fuelling the virtuous cycle of research that has already made SN1 the flagship arena for agentic workflow innovation across the entire Bittensor protocol Macrocosmos.*
* **GitHub:** [github.com/macrocosm-os/apex](https://github.com/macrocosm-os/apex)
* **Technical Documentation:** [docs.macrocosmos.ai/subnets/subnet-1-apex](https://docs.macrocosmos.ai/subnets/subnet-1-apex)
* **MCP Guide:** [docs.macrocosmos.ai/developers/tools/macrocosmos-mcp](https://docs.macrocosmos.ai/developers/tools/macrocosmos-mcp)
* **Mission Commander (Gravity) Docs:** [docs.macrocosmos.ai/constellation-user-guides/gravity](https://docs.macrocosmos.ai/constellation-user-guides/gravity)

### R&D and Community
* **Substack Articles (R&D):**
* [Chain-of-thought: SN1 enhanced with multi-step reasoning](https://macrocosmosai.substack.com/p/chain-of-thought-sn1-enhanced-with) (Note: Link to specific article needed if available, currently points to general substack)
* [Mixture-of-Miners: improving SN1's performance](https://macrocosmosai.substack.com/p/mixture-of-miners-improving-sn1s)
* [Introducing SN1's dashboard: benchmarks, leaderboards, & miner stats](https://macrocosmosai.substack.com/p/introducing-sn1s-dashboard)
* [Task management: Redesigning SN1's validation mechanisms](https://macrocosmosai.substack.com/p/task-management-redesigning-sn1s)
* **Bittensor Discord:** [discord.com/channels/799672011265015819/1161764867166961704](https://discord.com/channels/799672011265015819/1161764867166961704)
* **Macrocosmos Discord:** [discord.com/channels/1238450997848707082/1238453047848599562](https://discord.com/channels/1238450997848707082/1238453047848599562)
* **Cosmonauts - Macrocosmos Telegram:** [t.me/macrocosmosai](https://t.me/macrocosmosai)
* **Follow us at Macrocosmos X:** [x.com/MacrocosmosAI](https://x.com/MacrocosmosAI)


---
*License: MIT*
Loading