SAGE ($SAGE)
Recent developments:
15% of the initial token allocation is held by the creator.
Creator token stats last updated: Aug 5, 2025 14:49
The following is generated by an LLM:
Summary
AI education platform with GPU infrastructure backend
Analysis
The project revolves around creating a decentralized AI infrastructure for personalized education through the Sage agent, aiming to disrupt the $380 billion online education sector. The $SAGE token serves as a utility token with payment discounts, incentives, and governance staking, though its necessity compared to stablecoins or traditional payment methods may introduce friction. Tokenomics show a 15% initial allocation to the creator (150M tokens) with a 12-month linear vesting schedule, avoiding immediate sell-off risks. Formation Cloud's technical documentation is detailed, backed by reputable investors (Jump Trading, Republic), but execution risk remains high for their vertically integrated AI ecosystem. The project lacks clarity on legal entity structure and faces inherent crypto security risks. While the token distribution avoids extreme centralization (creator's 15% is below concerning thresholds), the ambitious scope of both AI education and infrastructure layers may strain focus.
Rating: 6
Generated with LLM: deepseek/deepseek-r1
LLM responses last updated: Aug 5, 2025 14:49
Original investment data:
# SAGE ($SAGE)
URL on launchpad: https://app.virtuals.io/geneses/7098
Launched at: Mon, 04 Aug 2025 16:01:42 GMT
Launched through the launchpad: Virtuals Protocol
Launch status: GENESIS
## Token details and tokenomics
Token symbol: $SAGE
Token supply: 1 billion
Creator initial number of tokens: Creator initial number of tokens: 150,000,000 (15% of token supply)
## Creator info
Creator address: 0x62c432759C8544E0080179d909e146ef39D26c2D
Creator on basescan.org: https://basescan.org/address/0x62c432759C8544E0080179d909e146ef39D26c2D#asset-tokens
Creator on virtuals.io: https://app.virtuals.io/profile/0x62c432759C8544E0080179d909e146ef39D26c2D
Creator on zerion.io: https://app.zerion.io/0x62c432759C8544E0080179d909e146ef39D26c2D/overview
Creator on debank.com: https://debank.com/profile/0x62c432759C8544E0080179d909e146ef39D26c2D
## Description at launch
Sage, an agent designated by Virtuals to lead the Educational ACP cluster, is designed to revolutionize online learning by delivering personalized, interactive educational experiences. Instead of offering pre-made courses, Sage engages each user in a thoughtful dialogue to understand their unique learning goals and motivations.
Sage is the first Agent developed by Formation Cloud, an AI infrastructure layer designed to deploy and host agents, while optimizing inference on open-source LLMs.
## Overview
<u>**Sage Agent Overview:**</u>
Sage, an AI agent designated by Virtuals to lead the Educational ACP cluster, is designed to revolutionize online learning by delivering a highly personalized, interactive educational experience.
**Sage’s Core Capabilities:**
* **Deeply Personalized:** Sage converses with each user to understand their unique goals, motivations, and learning styles.
* **Dynamic Curriculum:** Designs custom courses, interactive tests, activities, and evolving resources that adapt as users progress.
* **Built for Any Topic:** Our mission is to make highly personalized, dynamic education accessible on any topic. 
* **Continued Education:** Upon course completion, students can access CE designed for ongoing, adaptive learning that grows with them as their goals and the world change.
* **Our Goal:** To revolutionize the $380 billion online education sector.
* **Formation Cloud:** The Sage agent, is a key part of our Formation infrastructure and the first public agent developed by Formation.
<u>**The $SAGE Token:**</u>
A key pillar in our educational tooling and the launch of our core infrastructure:
* **Payments:** Accepted as a discount payment for all premium features and white-labeling. 
* **Incentives:** User rewards and incentives for analyzed feedback that improves functionality.
* **Staking:** For governance and possible incentives heading into the Formation protocol and $form launches.
<u>**About Formation Cloud:**</u>
Open-source LLMs are exploding. Models like Llama, DeepSeek, and Mistral are being adopted faster than ever, unlocking a new wave of open-source agent-based applications. But turning these models into profitable, reliable, scalable, integratable software is still hard. That’s where the Formation advantage comes in, an enterprise software and infrastructure layer for the AI economy designed to optimize GPU infrastructure and agentic deployment, while maximizing profitability.
* **A GPU orchestration layer enables efficient inference execution for agents and LLM models across GPU clusters designed specifically for serving open-source models; complete with a feedback loop to continuously improve performance.**
* **A full deployment and agentic software suite to go from model to monetized agent in minutes - no devops, no infrastructure, no cloud dependencies. While businesses get instant access to scalable AI workflows.**
* **Seamless agentic tooling enabling dynamic access to agentic tools such as MCP servers, memory/storage, tokenization partners and curated web3/web2 integration partners with incentive mechanisms for agent developers. In addition, we have further deep integrations planned for Virtuals, ACP, and the Virtuals ecosystem.**
* **Our unique model purchases and grows our own GPU hardware stack (vs renting), turning OpEx burn, into profitable CapEx amortization. In addition to reducing cost, it increases possible profit and enables advanced R\&D.**
Formation is a full vertically integrated AI ecosystem targeting open-source LLMs and GPU hardware to create a moat and profitability fly-wheel for the agentic economy.
**Formation Cloud - ARCHITECTURE OVERVIEW:**
* The Formation Cloud protocol and $form is expected to launch in Q3 2025 with deep ties to $sage. 
* Learn more about Formation Cloud here: [<u>https://Formation.Cloud</u>](https://formation.cloud) 
* Follow Formation Cloud on X for further updates: [https://x.com/formthefog](https://x.com/formthefog) #FormTheFog
* Formation is proudly backed by Jump Trading, Republic, Big Brain, Hyperithm, along with others:
\#FormTheFog
## Additional information extracted from relevant pages
<fetched_info>
""" https://virtualprotocolcdn.s3.ap-southeast-1.amazonaws.com/virtuals/35789/uploads/820528df-b327-473b-90d2-1e21b7ef5b02.png
Skipped image/binary URL (https://virtualprotocolcdn.s3.ap-southeast-1.amazonaws.com/virtuals/35789/uploads/820528df-b327-473b-90d2-1e21b7ef5b02.png) - likely not text content
"""
""" https://x.com/formthefog
Skipped social media URL (https://x.com/formthefog) - requires authentication
"""
""" https://virtualprotocolcdn.s3.ap-southeast-1.amazonaws.com/virtuals/35789/uploads/25e98689-6698-4722-9f7d-f8c9388d69c7.png
Skipped image/binary URL (https://virtualprotocolcdn.s3.ap-southeast-1.amazonaws.com/virtuals/35789/uploads/25e98689-6698-4722-9f7d-f8c9388d69c7.png) - likely not text content
"""
""" [Creator profile on Virtuals Protocol](https://api.virtuals.io/api/profile/0x62c432759C8544E0080179d909e146ef39D26c2D)
{
"data": {
"id": 484891,
"displayName": null,
"bio": "Sage, an agent designated by Virtuals to lead the Educational ACP cluster, is designed to revolutionize online learning by delivering personalized, interactive educational experiences. Instead of offering pre-made courses, Sage engages each user in a thoughtful dialogue to understand their unique learning goals and motivations. \r\n\r\nSage is the first Agent developed by Formation Cloud, an AI middleware protocol designed to deploy and hosting agents, while optimizing inference on open source LLMs.\r\n",
"avatar": {
"id": 49028,
"name": "sage-smile.png",
"alternativeText": null,
"caption": null,
"width": 512,
"height": 512,
"formats": {
"small": {
"ext": ".png",
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/small_sage_smile_906ba86ca6.png",
"hash": "small_sage_smile_906ba86ca6",
"mime": "image/png",
"name": "small_sage-smile.png",
"path": null,
"size": 222.7,
"width": 500,
"height": 500
},
"thumbnail": {
"ext": ".png",
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/thumbnail_sage_smile_906ba86ca6.png",
"hash": "thumbnail_sage_smile_906ba86ca6",
"mime": "image/png",
"name": "thumbnail_sage-smile.png",
"path": null,
"size": 27.12,
"width": 156,
"height": 156
}
},
"hash": "sage_smile_906ba86ca6",
"ext": ".png",
"mime": "image/png",
"size": 73.84,
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/sage_smile_906ba86ca6.png",
"previewUrl": null,
"provider": "aws-s3",
"provider_metadata": null,
"folderPath": "/",
"createdAt": "2025-08-04T16:23:07.302Z",
"updatedAt": "2025-08-04T16:23:07.302Z"
},
"userSocials": [
{
"id": 547416,
"provider": "metamask",
"walletAddress": "0x62c432759C8544E0080179d909e146ef39D26c2D",
"metadata": null
}
],
"socials": {
"VERIFIED_LINKS": {
"TWITTER": "https://x.com/SageToLearn"
}
}
}
}
"""
""" https://Formation.Cloud
## https://Formation.Cloud
# Discover. Deploy.Monetize.
Be among the first to join our agent marketplace. Connect with early adopters, deploy your agents, and help shape the future of AI automation.
Join Waitlist
Key Features
###### For Users
Unlock the power of the Autonomous Age with Formation. Deploy cutting-edge agents and AI models to bring your ideas to life quickly and efficiently.
###### For Developers
Share your innovations with the world. Register your agents and customized models on Formation’s marketplace and start earning from your creations.
### Launch Agents
Be among the first to experience our carefully curated selection of agents designed for real-world applications.
### Early Access Program
Join our exclusive early access program and help shape the future of agent monetization.
### Developer Tools
Access comprehensive SDKs and APIs to build, test, and deploy your agents seamlessly.
### Secure Platform
Enterprise-grade security and compliance for all marketplace transactions.
### Revenue Share
Earn 80% revenue share on your agent deployments with 0% platform fee at launch.
Why Formation Marketplace
## The Future of Agent Distribution
Formation's marketplace connects agent developers with users worldwide, powered by our decentralized inference network. Earn and spend Formation credits in a thriving ecosystem of innovation.
### 01ForDevelopers
Your time and effort is valuable, capture that value while contributing to the Autonomous Age with Formations Agent & Model Marketplace.
### 02ForBusinesses
### 03ForIndividuals
Use Cases
## Agents Transforming Industries
Explore how Formation's marketplace is revolutionizing access to AI capabilities across sectors.
Popular
### For Users
Access a diverse ecosystem of agents to enhance productivity, automate tasks, and unlock new possibilities with Formation credits.
Popular
### For Developers
Monetize your agents, reach a global audience, and earn Formation credits while focusing on building great solutions.
Popular
### For Enterprises
Deploy custom agents across your organization with enterprise-grade security, compliance, and scalability.
Popular
### For Innovators
Create specialized agents for niche markets and monetize your expertise through our decentralized marketplace.
## https://www.formation.cloud/docs
# Formation Documentation
Welcome to Formation - the decentralized AI infrastructure that enables developers to build, deploy, and monetize AI agents and models while providing users with access to specialized AI capabilities.
## 🚀 Quick Start
**New to Formation?** Choose your path:
```
Use AI agents & models
Build AI solutions
Run network infrastructure
👋 Welcome to Formation
What do you want to do?
📱 I'm a User
👨💻 I'm a Developer
⚙️ I'm an Operator
🤖 Hire AI Agents
🧠 Use AI Models
agents/getting-started.md
models/inference-guide.md
🤖 Build AI Agents
🧠 Deploy AI Models
💰 Monetize Solutions
developers/agents/
developers/models/
developers/monetization/
🏗️ Set Up Network
🔧 Manage Nodes
operators/quick-start.md
operators/two-node-setup.md
```
## 📚 Documentation by User Type
### 📱 [Users](https://www.formation.cloud/docs/users) \- Use AI Agents & Models
**Perfect for:** End users, businesses, and developers who want to use AI capabilities
- **[Getting Started](https://www.formation.cloud/docs/users/agents/getting-started)** \- Your first AI agent hire
- **[Model Inference Guide](https://www.formation.cloud/docs/users/models/inference-guide)** \- Direct AI model access
- **[API Reference](https://www.formation.cloud/docs/users/models/api-reference)** \- Complete technical documentation
- **[Code Examples](https://www.formation.cloud/docs/users/agents/examples)** \- Working examples in multiple languages
**⏱️ Time to first result:** 5 minutes
* * *
### 👨💻 [Developers](https://www.formation.cloud/docs/developers) \- Build & Monetize AI Solutions
**Perfect for:** AI developers, ML engineers, and entrepreneurs building AI products
#### 🤖 AI Agents
- **[Building Agents](https://www.formation.cloud/docs/developers/agents/building-agents)** \- Architecture and requirements
- **[Deployment Guide](https://www.formation.cloud/docs/developers/agents/deployment)** \- Deploy with `form-pack`
- **[Agent Examples](https://www.formation.cloud/docs/developers/agents/examples)** \- Complete working examples
#### 🧠 AI Models
- **[Model Requirements](https://www.formation.cloud/docs/developers/models/model-requirements)** \- OpenAI-compatible specs
- **[Deployment Guide](https://www.formation.cloud/docs/developers/models/deployment)** \- Containerization and registration
#### 💰 Monetization
- **[Pricing Models](https://www.formation.cloud/docs/developers/monetization/pricing-models)** \- Revenue strategies
- **[Billing Integration](https://www.formation.cloud/docs/developers/monetization/billing-integration)** \- Payment processing
**⏱️ Time to first deployment:** 2-3 hours
* * *
### ⚙️ [Operators](https://www.formation.cloud/docs/operators) \- Run Network Infrastructure
**Perfect for:** DevOps engineers, infrastructure providers, and network contributors
- **[Quick Start](https://www.formation.cloud/docs/operators/quick-start)** \- Single node setup
- **[Two-Node Setup](https://www.formation.cloud/docs/operators/two-node-setup)** \- Multi-node networking
- **[Troubleshooting](https://www.formation.cloud/docs/operators/troubleshooting)** \- Common issues and solutions
**⏱️ Time to running node:** 30 minutes
## 🎯 Popular Use Cases
### For Users
- **Content Creation**: Hire writing agents for blogs, marketing copy, documentation
- **Code Assistance**: Get programming help, code review, debugging support
- **Data Analysis**: Process spreadsheets, generate insights, create visualizations
- **Research**: Information gathering, fact-checking, competitive analysis
### For Developers
- **AI Agent Marketplace**: Build and sell specialized AI agents
- **Custom Model Hosting**: Deploy your trained models for inference
- **API Integration**: Add AI capabilities to existing applications
- **Revenue Generation**: Earn from your AI solutions (70% revenue share)
### For Operators
- **Network Participation**: Contribute to decentralized AI infrastructure
- **Resource Monetization**: Earn from providing compute resources
- **Local Development**: Run private Formation networks for testing
- **Enterprise Deployment**: Host Formation for organizational use
## 🔗 Quick Links
### Essential Resources
- **[Formation vs OpenAI](https://www.formation.cloud/docs/users/models/inference-guide.md#formation-vs-openai-api)** \- Migration guide
- **[Authentication Guide](https://www.formation.cloud/docs/users/agents/getting-started.md#authentication)** \- ECDSA signatures
- **[Pricing Overview](https://www.formation.cloud/docs/users/README.md#account--billing)** \- Credits and subscription tiers
- **[API Compatibility](https://www.formation.cloud/docs/users/models/api-reference.md#openai-compatibility)** \- 100% OpenAI-compatible
### Development Tools
- **form-config-wizard** \- Generate Formation configuration
- **form-pack** \- Build and package agents/models
- **Docker Compose** \- Local development environment
- **API Testing** \- Postman collections and cURL examples
### Community & Support
- **GitHub**: [formation-ai/formation](https://www.formation.cloud/docs/https://github.com/formation-ai/formation)
- **Discord**: [discord.gg/formation](https://www.formation.cloud/docs/https://discord.gg/formation)
- **Documentation Issues**: [Report here](https://www.formation.cloud/docs/https://github.com/formation-ai/formation/issues)
## 🏗️ Formation Architecture
Formation consists of five core services working together:
```
AI Workloads
User Interfaces
Formation Network
form-state
Port 3004
State Management
form-net
Port 51820
P2P Networking
form-vmm
Port 3002
VM Management
form-pack
Port 3003
Container Building
form-dns
Port 53/5453
DNS Resolution
REST APIs
Web Interface
CLI Tools
AI Agents
AI Models
Task Processing
```
## 🚦 Getting Started Checklist
### For Users
- [ ] Read the [User Guide](https://www.formation.cloud/docs/users)
- [ ] Try [hiring your first agent](https://www.formation.cloud/docs/users/agents/getting-started)
- [ ] Make a [model inference request](https://www.formation.cloud/docs/users/models/inference-guide)
- [ ] Explore [code examples](https://www.formation.cloud/docs/users/agents/examples)
### For Developers
- [ ] Review [developer overview](https://www.formation.cloud/docs/developers)
- [ ] Choose: [Build agents](https://www.formation.cloud/docs/developers/agents) or [deploy models](https://www.formation.cloud/docs/developers/models)
- [ ] Set up [local development environment](https://www.formation.cloud/docs/developers/README.md#development-tools)
- [ ] Configure [monetization](https://www.formation.cloud/docs/developers/monetization)
### For Operators
- [ ] Check [system requirements](https://www.formation.cloud/docs/operators/README.md#prerequisites)
- [ ] Follow [quick start guide](https://www.formation.cloud/docs/operators/quick-start)
- [ ] Set up [multi-node network](https://www.formation.cloud/docs/operators/two-node-setup)
- [ ] Configure [monitoring and maintenance](https://www.formation.cloud/docs/operators/troubleshooting)
## 📖 Documentation Standards
This documentation follows these principles:
- **User-Focused**: Organized by user type and use case
- **Example-Driven**: Working code examples for every concept
- **Production-Ready**: All examples can be used in production
- **OpenAI-Compatible**: Seamless migration from existing AI tools
- **Security-First**: Proper authentication and best practices
## 🤝 Contributing
Help improve Formation's documentation:
1. **Found an issue?** [Open a GitHub issue](https://www.formation.cloud/docs/https://github.com/formation-ai/formation/issues)
2. **Have a suggestion?** Join our [Discord community](https://www.formation.cloud/docs/https://discord.gg/formation)
3. **Want to contribute?** Check our [contribution guidelines](https://www.formation.cloud/docs/https://github.com/formation-ai/formation/blob/main/CONTRIBUTING.md)
* * *
## 🎉 Ready to Start?
**Choose your journey:**
| | | |
| --- | --- | --- |
| ### 📱 **Users**<br>**Use AI agents and models**<br>[**Get Started →**](https://www.formation.cloud/docs/users)<br>_Perfect for businesses and developers who want to use AI capabilities_ | ### 👨💻 **Developers**<br>**Build and monetize AI solutions**<br>[**Get Started →**](https://www.formation.cloud/docs/developers)<br>_Perfect for AI developers and ML engineers building products_ | ### ⚙️ **Operators**<br>**Run network infrastructure**<br>[**Get Started →**](https://www.formation.cloud/docs/operators)<br>_Perfect for DevOps engineers and infrastructure providers_ |
* * *
**Welcome to Formation - let's build the future of decentralized AI together!** 🚀
## On this page
- [🚀 Quick Start](https://www.formation.cloud/docs#-quick-start)
- [📚 Documentation by User Type](https://www.formation.cloud/docs#-documentation-by-user-type)
- [🎯 Popular Use Cases](https://www.formation.cloud/docs#-popular-use-cases)
- [🔗 Quick Links](https://www.formation.cloud/docs#-quick-links)
- [🏗️ Formation Architecture](https://www.formation.cloud/docs#-formation-architecture)
- [🚦 Getting Started Checklist](https://www.formation.cloud/docs#-getting-started-checklist)
- [📖 Documentation Standards](https://www.formation.cloud/docs#-documentation-standards)
- [🤝 Contributing](https://www.formation.cloud/docs#-contributing)
- [🎉 Ready to Start?](https://www.formation.cloud/docs#-ready-to-start?)
## https://www.formation.cloud/docs/developers
# Formation Developer Documentation
Welcome to Formation's developer documentation! This guide is designed for developers who want to build AI agents, deploy custom AI models, and monetize their solutions on the Formation decentralized AI network.
## What is Formation?
Formation is a decentralized AI infrastructure that enables developers to:
- **Build and Deploy AI Agents**: Create autonomous AI agents that can execute tasks and earn revenue
- **Deploy Custom AI Models**: Host your own AI models and make them available for inference requests
- **Monetize AI Solutions**: Earn revenue from your deployed agents and models through Formation's built-in billing system
- **Scale Globally**: Leverage Formation's peer-to-peer network for global distribution and high availability
## Getting Started
### Prerequisites
Before you begin, ensure you have:
- **Basic understanding of AI/ML concepts**: Familiarity with AI agents, language models, and inference
- **Development experience**: Proficiency in at least one programming language (Python, JavaScript, or Rust recommended)
- **Docker knowledge**: Understanding of containerization and Docker basics
- **Formation network access**: A running Formation node or access to a Formation network
### Quick Start Paths
Choose your development path based on what you want to build:
#### 🤖 **Building AI Agents** → [Start Here](https://www.formation.cloud/docs/agents)
Perfect if you want to create AI agents that can:
- Execute complex tasks autonomously
- Integrate with existing AI models and APIs
- Earn revenue through task completion
- Scale across the Formation network
**Time to first deployment**: ~2-3 hours
#### 🧠 **Deploying AI Models** → [Start Here](https://www.formation.cloud/docs/models)
Ideal if you want to:
- Host your own trained models
- Provide inference services to the network
- Monetize model usage
- Integrate with Formation's OpenAI-compatible API
**Time to first deployment**: ~1-2 hours
#### 💰 **Monetization Focus** → [Start Here](https://www.formation.cloud/docs/monetization)
Essential reading for:
- Setting up pricing strategies
- Understanding revenue sharing
- Configuring billing integration
- Optimizing profitability
**Time to setup**: ~30 minutes
## Documentation Structure
### 📁 [Agents Documentation](https://www.formation.cloud/docs/agents)
Complete guide for building and deploying AI agents:
- **[Building Agents](https://www.formation.cloud/docs/agents/building-agents)**: Architecture requirements, API specifications, and integration patterns
- **[Deployment Guide](https://www.formation.cloud/docs/agents/deployment)**: Step-by-step deployment using `form-pack` and `form-state`
- **[Examples](https://www.formation.cloud/docs/agents/examples)**: Working code examples for common agent types
### 📁 [Models Documentation](https://www.formation.cloud/docs/models)
Everything you need to deploy custom AI models:
- **[Model Requirements](https://www.formation.cloud/docs/models/model-requirements)**: OpenAI-compatible API specifications and requirements
- **[Deployment Guide](https://www.formation.cloud/docs/models/deployment)**: Containerization and registration process
- **[Examples](https://www.formation.cloud/docs/models/examples)**: Sample model deployments and configurations
### 📁 [Monetization Documentation](https://www.formation.cloud/docs/monetization)
Comprehensive monetization strategies and implementation:
- **[Pricing Models](https://www.formation.cloud/docs/monetization/pricing-models)**: Token-based, fixed-rate, and subscription pricing
- **[Billing Integration](https://www.formation.cloud/docs/monetization/billing-integration)**: Usage tracking and payment processing
## Core Concepts
### Formation Network Architecture
Formation operates as a decentralized network where:
1. **Nodes** run Formation services and host AI agents/models
2. **Tasks** are distributed across the network using Proof of Claim (PoC)
3. **CRDT** (Conflict-free Replicated Data Types) ensure consistent state across nodes
4. **ECDSA Authentication** secures all network communications
5. **Billing System** tracks usage and handles payments automatically
### Key Technologies
- **WireGuard**: Secure peer-to-peer networking ( `formnet`)
- **Docker**: Containerization for agents and models
- **SQLite + CRDT**: Distributed state management
- **HTTP APIs**: RESTful interfaces for all services
- **ECDSA**: Cryptographic authentication and authorization
### Development Workflow
```
Develop Agent/Model
Create Formfile
Build with form-pack
Register with form-state
Deploy to Network
Monitor & Earn
Scale & Optimize
```
## API Overview
### Core Formation APIs
Formation provides several APIs for different purposes:
#### form-state API (Port 3004)
Central datastore and coordination service:
- **Account Management**: `/v1/account/*` \- User and admin account operations
- **Agent Registry**: `/v1/agents/*` \- Agent registration and discovery
- **Model Registry**: `/v1/models/*` \- Model registration and management
- **Task Management**: `/v1/tasks/*` \- Task creation and tracking
- **Network State**: `/v1/network/*` \- Peer and network information
#### form-pack API (Port 3001)
Container building and management service:
- **Build Operations**: `/v1/build/*` \- Build agents and models from Formfiles
- **Image Management**: `/v1/images/*` \- Container image operations
- **Registry**: `/v1/registry/*` \- Private container registry
#### form-vmm API (Port 3002)
Virtual machine and instance management:
- **Instance Management**: `/v1/instances/*` \- Create and manage agent/model instances
- **Resource Allocation**: `/v1/resources/*` \- CPU, memory, and GPU allocation
- **Health Monitoring**: `/v1/health/*` \- Instance health and metrics
#### formnet API (Port 51820)
Network management and peer discovery:
- **Network Info**: `/network/*` \- Network topology and peer information
- **Bootstrap**: `/bootstrap/*` \- Network joining and initialization
### Authentication
All API requests require ECDSA signature authentication:
```bash
# Example authenticated request
curl -X GET http://localhost:3004/v1/account/list \
-H "X-Signature: 304502210089ab..." \
-H "X-Recovery-Id: 0" \
-H "X-Message: GET/v1/account/list1640995200"
```
See the [Authentication Guide](https://www.formation.cloud/operators/troubleshooting.md#authentication--key-management-issues) for detailed implementation.
## Development Tools
### Essential Tools
- **form-config-wizard**: Generate Formation configuration and keys
- **form-pack**: Build and package agents/models into containers
- **Docker & Docker Compose**: Container management
- **curl/Postman**: API testing and development
### Recommended Development Environment
```bash
# Clone Formation repository
git clone https://github.com/formation-ai/formation.git
cd formation
# Set up development environment
./scripts/setup-dev-environment.sh
# Start local Formation network
docker-compose up -d
# Verify services are running
curl http://localhost:3004/health
curl http://localhost:3001/health
curl http://localhost:3002/health
```
## Common Development Patterns
### 1\. Agent Development Pattern
```python
# Basic agent structure
class FormationAgent:
def __init__(self):
self.capabilities = ["text_generation", "summarization"]
async def run_task(self, task_data):
# Process task
result = await self.process(task_data)
# Return formatted response
return {
"task_id": task_data["task_id"],
"status": "completed",
"result": result,
"usage_metrics": self.get_usage_metrics()
}
def health_check(self):
return {"status": "healthy", "capabilities": self.capabilities}
```
### 2\. Model Deployment Pattern
```python
# OpenAI-compatible model wrapper
class FormationModel:
def __init__(self, model_path):
self.model = load_model(model_path)
async def chat_completions(self, request):
# Process OpenAI-compatible request
response = await self.model.generate(
messages=request["messages"],
max_tokens=request.get("max_tokens", 100)
)
return {
"choices": [{"message": {"content": response}}],
"usage": {"total_tokens": len(response.split())}
}
```
### 3\. Monetization Integration
```python
# Usage tracking for billing
class UsageTracker:
def track_usage(self, task_id, metrics):
return {
"task_id": task_id,
"compute_units": metrics["cpu_time"] * metrics["memory_gb"],
"tokens_processed": metrics["input_tokens"] + metrics["output_tokens"],
"duration_seconds": metrics["processing_time"],
"cost_usd": self.calculate_cost(metrics)
}
```
## Support and Community
### Getting Help
- **Documentation Issues**: Check the [troubleshooting guide](https://www.formation.cloud/operators/troubleshooting)
- **API Questions**: Refer to the specific service documentation
- **Development Support**: Join the Formation developer community
### Contributing
We welcome contributions to Formation's developer documentation:
1. **Report Issues**: Found something unclear or incorrect? Open an issue
2. **Suggest Improvements**: Have ideas for better examples or explanations?
3. **Submit Examples**: Share your working agent or model implementations
4. **Update Documentation**: Help keep the docs current and comprehensive
### Best Practices
- **Security First**: Always validate inputs and handle authentication properly
- **Resource Efficiency**: Optimize your agents and models for resource usage
- **Error Handling**: Implement robust error handling and recovery
- **Monitoring**: Include comprehensive logging and metrics
- **Testing**: Test thoroughly before deploying to production networks
## Next Steps
Ready to start building? Choose your path:
1. **🤖 [Build Your First Agent](https://www.formation.cloud/docs/agents/building-agents)** \- Create a simple text processing agent
2. **🧠 [Deploy Your First Model](https://www.formation.cloud/docs/models/model-requirements)** \- Host a custom language model
3. **💰 [Set Up Monetization](https://www.formation.cloud/docs/monetization/pricing-models)** \- Configure pricing and billing
Welcome to the Formation ecosystem! Let's build the future of decentralized AI together.
## On this page
- [What is Formation?](https://www.formation.cloud/docs/developers#what-is-formation?)
- [Getting Started](https://www.formation.cloud/docs/developers#getting-started)
- [Documentation Structure](https://www.formation.cloud/docs/developers#documentation-structure)
- [Core Concepts](https://www.formation.cloud/docs/developers#core-concepts)
- [API Overview](https://www.formation.cloud/docs/developers#api-overview)
- [Development Tools](https://www.formation.cloud/docs/developers#development-tools)
- [Common Development Patterns](https://www.formation.cloud/docs/developers#common-development-patterns)
- [Support and Community](https://www.formation.cloud/docs/developers#support-and-community)
- [Next Steps](https://www.formation.cloud/docs/developers#next-steps)
## https://www.formation.cloud/docs/users
# Formation User Guide
Welcome to Formation! This guide helps you get started with hiring AI agents and making inference requests to AI models on the Formation network.
## Who This Guide Is For
This documentation is designed for **end users** who want to:
- 🤖 **Hire AI agents** to perform tasks and solve problems
- 🧠 **Use AI models** for text generation, analysis, and other AI capabilities
- 💳 **Understand pricing** and manage your account credits
- 🔧 **Integrate Formation** into your applications and workflows
## Quick Start
### New to Formation?
1. **[Get Started with Agents](https://www.formation.cloud/docs/agents/getting-started)** \- Learn how to browse, hire, and use AI agents
2. **[Model Inference Guide](https://www.formation.cloud/docs/models/inference-guide)** \- Make your first AI model inference request
3. **[API Reference](https://www.formation.cloud/docs/models/api-reference)** \- Complete API documentation for developers
### Already familiar with OpenAI?
Formation is **100% OpenAI-compatible**! You can use your existing OpenAI code with Formation models by simply changing the base URL:
```python
# Instead of OpenAI
client = OpenAI(api_key="your-openai-key")
# Use Formation
client = OpenAI(
api_key="your-formation-signature", # ECDSA signature
base_url="https://formation.ai/v1" # Formation endpoint
)
```
## What You Can Do on Formation
### 🤖 AI Agents
AI agents are specialized services that can perform complex tasks:
- **Text Processing**: Writing, editing, summarization, translation
- **Code Generation**: Programming assistance, debugging, code review
- **Data Analysis**: Processing spreadsheets, generating insights
- **Creative Tasks**: Content creation, brainstorming, design assistance
- **Research**: Information gathering, fact-checking, analysis
- **Workflow Automation**: Multi-step processes, task orchestration
**[Browse Available Agents →](https://www.formation.cloud/docs/agents/getting-started)**
### 🧠 AI Models
AI models provide direct inference capabilities:
- **Language Models**: Chat completions, text generation
- **Specialized Models**: Code generation, mathematical reasoning
- **Multimodal Models**: Text + image understanding
- **Custom Models**: Community-deployed specialized models
**[Start Using Models →](https://www.formation.cloud/docs/models/inference-guide)**
## Formation vs. Other AI Platforms
| Feature | Formation | OpenAI | Other Platforms |
| --- | --- | --- | --- |
| **API Compatibility** | 100% OpenAI-compatible | ✓ | Varies |
| **Specialized Agents** | ✓ Unique to Formation | ✗ | Limited |
| **Custom Models** | ✓ Community-deployed | ✗ | Limited |
| **Decentralized** | ✓ | ✗ | ✗ |
| **Transparent Pricing** | ✓ | ✓ | Varies |
| **Developer Revenue Sharing** | ✓ 70% to developers | ✗ | Varies |
## Account & Billing
### Credit System
Formation uses a simple credit-based billing system:
- **1 credit = $0.01 USD**
- Credits are deducted in real-time as you use services
- No surprise bills - you only pay for what you use
- Transparent pricing for all agents and models
### Subscription Tiers
Choose the plan that fits your usage:
| Tier | Monthly Cost | Included Credits | Features |
| --- | --- | --- | --- |
| **Free** | $0 | 100 credits | Basic access, 1 agent |
| **Pro** | $20 | 500 credits | 3 agents, priority support |
| **Pro Plus** | $50 | 1,000 credits | 5 agents, unlimited tokens |
| **Power** | $200 | 5,000 credits | 10 agents, enterprise features |
| **Power Plus** | $500 | 10,000 credits | 25 agents, dedicated support |
### Authentication
Formation uses **ECDSA signature authentication** for security:
- No API keys to manage or leak
- Cryptographically secure authentication
- Compatible with Ethereum wallets and tools
- [Learn more about authentication →](https://www.formation.cloud/docs/agents/getting-started.md#authentication)
## Getting Help
### Documentation Sections
- **[Agents](https://www.formation.cloud/docs/agents)** \- Complete guide to hiring and using AI agents
- **[Models](https://www.formation.cloud/docs/models)** \- Direct AI model inference and API reference
- **[Examples](https://www.formation.cloud/docs/agents/examples)** \- Code examples in multiple languages
### Support Channels
- **Community Discord**: [discord.gg/formation](https://www.formation.cloud/docs/https://discord.gg/formation)
- **GitHub Issues**: [github.com/formation-ai/formation](https://www.formation.cloud/docs/https://github.com/formation-ai/formation)
- **Email Support**: [support@formation.ai](https://www.formation.cloud/docs/mailto:support@formation.ai) (Pro+ subscribers)
### Common Questions
**Q: How is Formation different from OpenAI?**
A: Formation is a decentralized network that's 100% OpenAI-compatible but offers specialized AI agents and community-deployed models that you can't find elsewhere.
**Q: Can I use my existing OpenAI code?**
A: Yes! Just change the base URL to Formation's endpoint and use ECDSA signature authentication instead of API keys.
**Q: How much does it cost?**
A: Formation uses transparent credit-based pricing. Most text generation costs 1-2 credits per 1,000 tokens (1-2 cents). Agents have their own pricing based on complexity.
**Q: What if I need help?**
A: Start with our documentation, join our Discord community, or contact support if you're on a Pro+ plan.
## Next Steps
### For Immediate Use
1. **[Get Started with Agents](https://www.formation.cloud/docs/agents/getting-started)** \- Hire your first AI agent
2. **[Try Model Inference](https://www.formation.cloud/docs/models/inference-guide)** \- Make your first API call
### For Developers
1. **[API Reference](https://www.formation.cloud/docs/models/api-reference)** \- Complete technical documentation
2. **[Code Examples](https://www.formation.cloud/docs/agents/examples)** \- Working examples in Python, JavaScript, cURL
3. **[Integration Guide](https://www.formation.cloud/docs/models/inference-guide.md#integration)** \- Add Formation to your app
### For Businesses
1. **[Enterprise Features](https://www.formation.cloud/docs/agents/getting-started.md#enterprise)** \- Dedicated support and SLAs
2. **[Custom Deployment](https://www.formation.cloud/developers)** \- Deploy your own agents and models
3. **[Volume Pricing](https://www.formation.cloud/docs/agents/getting-started.md#pricing)** \- Discounts for high-volume usage
* * *
**Ready to get started?** Choose your path:
- 🚀 **[Hire an AI Agent](https://www.formation.cloud/docs/agents/getting-started)** \- Get work done with specialized AI
- 🧠 **[Use AI Models](https://www.formation.cloud/docs/models/inference-guide)** \- Direct access to language models
- 💻 **[View Code Examples](https://www.formation.cloud/docs/agents/examples)** \- See Formation in action
Welcome to the future of AI! 🎉
## On this page
- [Who This Guide Is For](https://www.formation.cloud/docs/users#who-this-guide-is-for)
- [Quick Start](https://www.formation.cloud/docs/users#quick-start)
- [What You Can Do on Formation](https://www.formation.cloud/docs/users#what-you-can-do-on-formation)
- [Formation vs. Other AI Platforms](https://www.formation.cloud/docs/users#formation-vs.-other-ai-platforms)
- [Account & Billing](https://www.formation.cloud/docs/users#account-&-billing)
- [Getting Help](https://www.formation.cloud/docs/users#getting-help)
- [Next Steps](https://www.formation.cloud/docs/users#next-steps)
## https://www.formation.cloud/docs/developers/models/model-requirements
# AI Model Requirements for Formation
This document outlines the technical requirements for deploying custom AI models on the Formation network. All models must implement these specifications to ensure compatibility with Formation's infrastructure and billing systems.
## Overview
Formation models are containerized AI inference services that serve OpenAI-compatible APIs. They integrate with Formation's decentralized network to provide scalable, monetizable AI inference capabilities.
### Key Requirements
- ✅ **OpenAI-Compatible API**: Implement standard OpenAI endpoints
- ✅ **HTTP Server**: Serve requests on port 8080 within container
- ✅ **Usage Metrics**: Report accurate usage data for billing
- ✅ **Health Monitoring**: Provide health check endpoints
- ✅ **Containerization**: Package as Docker container
- ✅ **Resource Efficiency**: Optimize for memory and compute usage
* * *
## 1\. OpenAI-Compatible API Requirements
### 1.1 API Compatibility Standard
Formation models **MUST** implement OpenAI-compatible endpoints to ensure seamless integration with existing applications and Formation's routing infrastructure.
#### Supported OpenAI API Version
- **Target Version**: OpenAI API v1
- **Specification**: Follow [OpenAI API Reference](https://www.formation.cloud/docs/https://platform.openai.com/docs/api-reference)
- **Content-Type**: `application/json`
- **Character Encoding**: UTF-8
#### Request/Response Format
All endpoints must accept and return JSON in the exact format specified by OpenAI's API documentation.
### 1.2 Model Types and Capabilities
Formation supports various model types with specific API requirements:
#### Text Generation Models
```json
{
"model_type": "text_generation",
"required_endpoints": ["/v1/chat/completions", "/v1/completions"],
"optional_endpoints": ["/v1/embeddings"],
"io_modes": ["text_to_text"]
}
```
#### Image Generation Models
```json
{
"model_type": "image_generation",
"required_endpoints": ["/v1/images/generations"],
"optional_endpoints": ["/v1/images/edits", "/v1/images/variations"],
"io_modes": ["text_to_image", "image_to_image"]
}
```
#### Multimodal Models
```json
{
"model_type": "multimodal",
"required_endpoints": ["/v1/chat/completions"],
"optional_endpoints": ["/v1/completions", "/v1/embeddings"],
"io_modes": ["text_to_text", "image_to_text", "text_to_image"]
}
```
* * *
## 2\. Required Endpoints
### 2.1 POST /v1/chat/completions (Required for Chat Models)
Primary endpoint for chat-based completions.
#### Request Format
```json
{
"model": "your-model-id",
"messages": [\
{\
"role": "system",\
"content": "You are a helpful assistant."\
},\
{\
"role": "user",\
"content": "Hello, how are you?"\
}\
],
"max_tokens": 1000,
"temperature": 0.7,
"top_p": 1.0,
"n": 1,
"stream": false,
"stop": null,
"presence_penalty": 0,
"frequency_penalty": 0,
"logit_bias": {},
"user": "user-123"
}
```
#### Response Format
**Non-Streaming Response:**
```json
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1677652288,
"model": "your-model-id",
"choices": [\
{\
"index": 0,\
"message": {\
"role": "assistant",\
"content": "Hello! I'm doing well, thank you for asking. How can I help you today?"\
},\
"finish_reason": "stop"\
}\
],
"usage": {
"prompt_tokens": 13,
"completion_tokens": 17,
"total_tokens": 30
}
}
```
**Streaming Response (if stream=true):**
```px-1.5 py-0.5 rounded font-mono text-sm
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"your-model-id","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"your-model-id","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"your-model-id","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"your-model-id","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]
```
#### Implementation Example
```python
from flask import Flask, request, jsonify
import time
import uuid
app = Flask(__name__)
@app.route('/v1/chat/completions', methods=['POST'])
def chat_completions():
data = request.json
# Extract parameters
messages = data.get('messages', [])
max_tokens = data.get('max_tokens', 1000)
temperature = data.get('temperature', 0.7)
stream = data.get('stream', False)
model = data.get('model', 'your-model-id')
# Validate required fields
if not messages:
return jsonify({"error": {"message": "messages is required"}}), 400
# Generate response using your model
response_content = generate_response(messages, max_tokens, temperature)
# Calculate token usage
prompt_tokens = sum(len(msg['content'].split()) for msg in messages)
completion_tokens = len(response_content.split())
total_tokens = prompt_tokens + completion_tokens
if stream:
return stream_response(response_content, model, prompt_tokens, completion_tokens)
else:
return jsonify({
"id": f"chatcmpl-{uuid.uuid4().hex[:8]}",
"object": "chat.completion",
"created": int(time.time()),
"model": model,
"choices": [{\
"index": 0,\
"message": {\
"role": "assistant",\
"content": response_content\
},\
"finish_reason": "stop"\
}],
"usage": {
"prompt_tokens": prompt_tokens,
"completion_tokens": completion_tokens,
"total_tokens": total_tokens
}
})
def generate_response(messages, max_tokens, temperature):
# Your model inference logic here
# This is where you call your actual model
return "Generated response based on the conversation"
```
### 2.2 POST /v1/completions (Required for Text Models)
Text completion endpoint for non-chat models.
#### Request Format
```json
{
"model": "your-model-id",
"prompt": "Once upon a time",
"max_tokens": 100,
"temperature": 0.7,
"top_p": 1.0,
"n": 1,
"stream": false,
"logprobs": null,
"echo": false,
"stop": null,
"presence_penalty": 0,
"frequency_penalty": 0,
"best_of": 1,
"logit_bias": {},
"user": "user-123"
}
```
#### Response Format
```json
{
"id": "cmpl-123",
"object": "text_completion",
"created": 1677652288,
"model": "your-model-id",
"choices": [\
{\
"text": ", there was a brave knight who embarked on a quest to save the kingdom.",\
"index": 0,\
"logprobs": null,\
"finish_reason": "stop"\
}\
],
"usage": {
"prompt_tokens": 4,
"completion_tokens": 16,
"total_tokens": 20
}
}
```
### 2.3 GET /v1/models (Required)
List available models endpoint.
#### Response Format
```json
{
"object": "list",
"data": [\
{\
"id": "your-model-id",\
"object": "model",\
"created": 1677652288,\
"owned_by": "formation",\
"permission": [],\
"root": "your-model-id",\
"parent": null\
}\
]
}
```
#### Implementation Example
```python
@app.route('/v1/models', methods=['GET'])
def list_models():
return jsonify({
"object": "list",
"data": [\
{\
"id": "your-model-id",\
"object": "model",\
"created": int(time.time()),\
"owned_by": "formation",\
"permission": [],\
"root": "your-model-id",\
"parent": None\
}\
]
})
```
### 2.4 GET /health (Required)
Health check endpoint for monitoring and load balancing.
#### Response Format
```json
{
"status": "healthy",
"model_loaded": true,
"version": "1.0.0",
"framework": "pytorch",
"gpu_available": true,
"memory_usage": {
"used_mb": 2048,
"total_mb": 8192,
"percentage": 25.0
},
"model_info": {
"model_id": "your-model-id",
"parameters": "7B",
"quantization": "int8"
}
}
```
#### Status Values
- `healthy`: Model is fully operational
- `degraded`: Model is operational but with reduced performance
- `unhealthy`: Model is not operational
#### Implementation Example
```python
@app.route('/health', methods=['GET'])
def health():
try:
# Check if model is loaded and responsive
model_status = check_model_health()
return jsonify({
"status": "healthy" if model_status else "unhealthy",
"model_loaded": model_status,
"version": "1.0.0",
"framework": "pytorch",
"gpu_available": torch.cuda.is_available(),
"memory_usage": get_memory_usage(),
"model_info": {
"model_id": "your-model-id",
"parameters": "7B",
"quantization": "int8"
}
})
except Exception as e:
return jsonify({
"status": "unhealthy",
"error": str(e)
}), 500
```
### 2.5 Optional Endpoints
#### POST /v1/embeddings
For models that support text embeddings:
```json
{
"input": ["The food was delicious and the waiter was friendly."],
"model": "your-embedding-model",
"encoding_format": "float"
}
```
#### POST /v1/images/generations
For image generation models:
```json
{
"prompt": "A cute baby sea otter",
"n": 1,
"size": "1024x1024",
"response_format": "url"
}
```
* * *
## 3\. Authentication Handling
### 3.1 Formation-Managed Authentication
**IMPORTANT**: Formation handles ALL authentication for requests coming through the Formation network. Your model should NOT implement its own authentication for Formation requests.
#### Request Flow
```px-1.5 py-0.5 rounded font-mono text-sm
User Request → Formation Gateway → Authentication → Your Model
```
#### What Your Model Receives
- **Pre-authenticated requests**: Formation has already verified the user
- **Clean HTTP requests**: No authentication headers to process
- **User context**: Available in request headers if needed
#### Implementation Guidelines
```python
@app.route('/v1/chat/completions', methods=['POST'])
def chat_completions():
# DO NOT check authentication - Formation handles this
# Just process the request directly
data = request.json
# Optional: Extract user context from Formation headers
user_id = request.headers.get('X-Formation-User-Id')
request_id = request.headers.get('X-Formation-Request-Id')
# Process the request
response = process_chat_completion(data)
return jsonify(response)
```
### 3.2 Direct Access Protection
Your model should reject requests that bypass Formation:
```python
def check_formation_request():
"""Verify request comes from Formation"""
formation_signature = request.headers.get('X-Formation-Signature')
if not formation_signature:
return False
# Verify Formation's signature (optional additional security)
return verify_formation_signature(formation_signature)
@app.before_request
def before_request():
# Allow health checks from anywhere
if request.path == '/health':
return
# Require Formation signature for API endpoints
if not check_formation_request():
return jsonify({"error": "Direct access not allowed"}), 403
```
### 3.3 Security Best Practices
- **No API Keys**: Don't require API keys from users
- **No User Authentication**: Formation handles user verification
- **Input Validation**: Always validate and sanitize inputs
- **Rate Limiting**: Implement basic rate limiting if needed
- **Error Handling**: Don't expose internal errors to users
* * *
## 4\. Usage Metrics Reporting
### 4.1 Required Metrics
Your model **MUST** report accurate usage metrics for Formation's billing system:
#### Token-Based Metrics
```json
{
"prompt_tokens": 150,
"completion_tokens": 75,
"total_tokens": 225
}
```
#### Resource-Based Metrics
```json
{
"compute_units": 1.5,
"memory_mb": 2048,
"duration_seconds": 3.2,
"gpu_seconds": 2.1
}
```
#### Request-Based Metrics
```json
{
"requests_processed": 1,
"cache_hits": 0,
"cache_misses": 1
}
```
### 4.2 Token Counting
Accurate token counting is critical for billing:
#### For Text Models
```python
import tiktoken
def count_tokens(text, model="gpt-4"):
"""Count tokens using tiktoken (OpenAI's tokenizer)"""
try:
encoding = tiktoken.encoding_for_model(model)
return len(encoding.encode(text))
except KeyError:
# Fallback to approximate counting
return len(text.split()) * 1.3 # Rough approximation
def count_message_tokens(messages, model="gpt-4"):
"""Count tokens in a list of messages"""
total_tokens = 0
for message in messages:
total_tokens += count_tokens(message.get('content', ''), model)
total_tokens += 4 # Every message has overhead tokens
total_tokens += 2 # Conversation overhead
return total_tokens
```
#### For Image Models
```python
def count_image_tokens(width, height, detail="auto"):
"""Count tokens for image processing"""
if detail == "low":
return 85
elif detail == "high":
# Calculate based on image tiles
tiles = math.ceil(width / 512) * math.ceil(height / 512)
return 170 * tiles + 85
else:
# Auto mode
if width <= 512 and height <= 512:
return 85
else:
return count_image_tokens(width, height, "high")
```
### 4.3 Usage Tracking Implementation
```python
import time
import psutil
import threading
class UsageTracker:
def __init__(self):
self.start_time = None
self.start_memory = 0
self.peak_memory = 0
self.gpu_start_time = 0
self.monitoring = False
def start_tracking(self):
"""Start tracking resource usage"""
self.start_time = time.time()
self.start_memory = psutil.virtual_memory().used / 1024 / 1024 # MB
self.peak_memory = self.start_memory
self.monitoring = True
# Start background monitoring
threading.Thread(target=self._monitor_resources, daemon=True).start()
def stop_tracking(self):
"""Stop tracking and return metrics"""
self.monitoring = False
end_time = time.time()
duration = end_time - self.start_time
memory_used = self.peak_memory - self.start_memory
return {
"duration_seconds": round(duration, 3),
"memory_mb": max(0, round(memory_used, 1)),
"peak_memory_mb": round(self.peak_memory, 1),
"compute_units": round(duration * 1.0, 3) # Adjust multiplier based on model
}
def _monitor_resources(self):
"""Monitor resource usage in background"""
while self.monitoring:
try:
current_memory = psutil.virtual_memory().used / 1024 / 1024
self.peak_memory = max(self.peak_memory, current_memory)
time.sleep(0.1)
except:
break
# Usage in endpoint
@app.route('/v1/chat/completions', methods=['POST'])
def chat_completions():
tracker = UsageTracker()
tracker.start_tracking()
try:
data = request.json
# Count input tokens
prompt_tokens = count_message_tokens(data['messages'])
# Generate response
response_content = generate_response(data['messages'])
# Count output tokens
completion_tokens = count_tokens(response_content)
total_tokens = prompt_tokens + completion_tokens
# Get resource metrics
resource_metrics = tracker.stop_tracking()
return jsonify({
"id": f"chatcmpl-{uuid.uuid4().hex[:8]}",
"object": "chat.completion",
"created": int(time.time()),
"model": data.get('model'),
"choices": [{\
"index": 0,\
"message": {\
"role": "assistant",\
"content": response_content\
},\
"finish_reason": "stop"\
}],
"usage": {
"prompt_tokens": prompt_tokens,
"completion_tokens": completion_tokens,
"total_tokens": total_tokens,
# Additional Formation metrics
"duration_seconds": resource_metrics["duration_seconds"],
"memory_mb": resource_metrics["memory_mb"],
"compute_units": resource_metrics["compute_units"]
}
})
except Exception as e:
tracker.stop_tracking()
return jsonify({"error": {"message": str(e)}}), 500
```
### 4.4 Billing Integration
Formation automatically processes usage metrics from your responses:
```python
# Formation extracts these fields for billing
billing_fields = {
"prompt_tokens": response["usage"]["prompt_tokens"],
"completion_tokens": response["usage"]["completion_tokens"],
"total_tokens": response["usage"]["total_tokens"],
"duration_seconds": response["usage"].get("duration_seconds", 0),
"memory_mb": response["usage"].get("memory_mb", 0),
"compute_units": response["usage"].get("compute_units", 0)
}
```
* * *
## 5\. Error Handling
### 5.1 HTTP Status Codes
Use appropriate HTTP status codes:
- `200 OK`: Successful completion
- `400 Bad Request`: Invalid request parameters
- `401 Unauthorized`: Authentication failed (should not occur with Formation)
- `403 Forbidden`: Request not allowed
- `404 Not Found`: Model or endpoint not found
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Model processing error
- `503 Service Unavailable`: Model temporar... (truncated)
"""
""" https://formation.cloud
## https://formation.cloud
# Discover. Deploy.Monetize.
Be among the first to join our agent marketplace. Connect with early adopters, deploy your agents, and help shape the future of AI automation.
Join Waitlist
Key Features
###### For Users
Unlock the power of the Autonomous Age with Formation. Deploy cutting-edge agents and AI models to bring your ideas to life quickly and efficiently.
###### For Developers
Share your innovations with the world. Register your agents and customized models on Formation’s marketplace and start earning from your creations.
### Launch Agents
Be among the first to experience our carefully curated selection of agents designed for real-world applications.
### Early Access Program
Join our exclusive early access program and help shape the future of agent monetization.
### Developer Tools
Access comprehensive SDKs and APIs to build, test, and deploy your agents seamlessly.
### Secure Platform
Enterprise-grade security and compliance for all marketplace transactions.
### Revenue Share
Earn 80% revenue share on your agent deployments with 0% platform fee at launch.
Why Formation Marketplace
## The Future of Agent Distribution
Formation's marketplace connects agent developers with users worldwide, powered by our decentralized inference network. Earn and spend Formation credits in a thriving ecosystem of innovation.
### 01ForDevelopers
Your time and effort is valuable, capture that value while contributing to the Autonomous Age with Formations Agent & Model Marketplace.
### 02ForBusinesses
### 03ForIndividuals
Use Cases
## Agents Transforming Industries
Explore how Formation's marketplace is revolutionizing access to AI capabilities across sectors.
Popular
### For Users
Access a diverse ecosystem of agents to enhance productivity, automate tasks, and unlock new possibilities with Formation credits.
Popular
### For Developers
Monetize your agents, reach a global audience, and earn Formation credits while focusing on building great solutions.
Popular
### For Enterprises
Deploy custom agents across your organization with enterprise-grade security, compliance, and scalability.
Popular
### For Innovators
Create specialized agents for niche markets and monetize your expertise through our decentralized marketplace.
## https://www.formation.cloud/docs
# Formation Documentation
Welcome to Formation - the decentralized AI infrastructure that enables developers to build, deploy, and monetize AI agents and models while providing users with access to specialized AI capabilities.
## 🚀 Quick Start
**New to Formation?** Choose your path:
```
Use AI agents & models
Build AI solutions
Run network infrastructure
👋 Welcome to Formation
What do you want to do?
📱 I'm a User
👨💻 I'm a Developer
⚙️ I'm an Operator
🤖 Hire AI Agents
🧠 Use AI Models
agents/getting-started.md
models/inference-guide.md
🤖 Build AI Agents
🧠 Deploy AI Models
💰 Monetize Solutions
developers/agents/
developers/models/
developers/monetization/
🏗️ Set Up Network
🔧 Manage Nodes
operators/quick-start.md
operators/two-node-setup.md
```
## 📚 Documentation by User Type
### 📱 [Users](https://www.formation.cloud/docs/users) \- Use AI Agents & Models
**Perfect for:** End users, businesses, and developers who want to use AI capabilities
- **[Getting Started](https://www.formation.cloud/docs/users/agents/getting-started)** \- Your first AI agent hire
- **[Model Inference Guide](https://www.formation.cloud/docs/users/models/inference-guide)** \- Direct AI model access
- **[API Reference](https://www.formation.cloud/docs/users/models/api-reference)** \- Complete technical documentation
- **[Code Examples](https://www.formation.cloud/docs/users/agents/examples)** \- Working examples in multiple languages
**⏱️ Time to first result:** 5 minutes
* * *
### 👨💻 [Developers](https://www.formation.cloud/docs/developers) \- Build & Monetize AI Solutions
**Perfect for:** AI developers, ML engineers, and entrepreneurs building AI products
#### 🤖 AI Agents
- **[Building Agents](https://www.formation.cloud/docs/developers/agents/building-agents)** \- Architecture and requirements
- **[Deployment Guide](https://www.formation.cloud/docs/developers/agents/deployment)** \- Deploy with `form-pack`
- **[Agent Examples](https://www.formation.cloud/docs/developers/agents/examples)** \- Complete working examples
#### 🧠 AI Models
- **[Model Requirements](https://www.formation.cloud/docs/developers/models/model-requirements)** \- OpenAI-compatible specs
- **[Deployment Guide](https://www.formation.cloud/docs/developers/models/deployment)** \- Containerization and registration
#### 💰 Monetization
- **[Pricing Models](https://www.formation.cloud/docs/developers/monetization/pricing-models)** \- Revenue strategies
- **[Billing Integration](https://www.formation.cloud/docs/developers/monetization/billing-integration)** \- Payment processing
**⏱️ Time to first deployment:** 2-3 hours
* * *
### ⚙️ [Operators](https://www.formation.cloud/docs/operators) \- Run Network Infrastructure
**Perfect for:** DevOps engineers, infrastructure providers, and network contributors
- **[Quick Start](https://www.formation.cloud/docs/operators/quick-start)** \- Single node setup
- **[Two-Node Setup](https://www.formation.cloud/docs/operators/two-node-setup)** \- Multi-node networking
- **[Troubleshooting](https://www.formation.cloud/docs/operators/troubleshooting)** \- Common issues and solutions
**⏱️ Time to running node:** 30 minutes
## 🎯 Popular Use Cases
### For Users
- **Content Creation**: Hire writing agents for blogs, marketing copy, documentation
- **Code Assistance**: Get programming help, code review, debugging support
- **Data Analysis**: Process spreadsheets, generate insights, create visualizations
- **Research**: Information gathering, fact-checking, competitive analysis
### For Developers
- **AI Agent Marketplace**: Build and sell specialized AI agents
- **Custom Model Hosting**: Deploy your trained models for inference
- **API Integration**: Add AI capabilities to existing applications
- **Revenue Generation**: Earn from your AI solutions (70% revenue share)
### For Operators
- **Network Participation**: Contribute to decentralized AI infrastructure
- **Resource Monetization**: Earn from providing compute resources
- **Local Development**: Run private Formation networks for testing
- **Enterprise Deployment**: Host Formation for organizational use
## 🔗 Quick Links
### Essential Resources
- **[Formation vs OpenAI](https://www.formation.cloud/docs/users/models/inference-guide.md#formation-vs-openai-api)** \- Migration guide
- **[Authentication Guide](https://www.formation.cloud/docs/users/agents/getting-started.md#authentication)** \- ECDSA signatures
- **[Pricing Overview](https://www.formation.cloud/docs/users/README.md#account--billing)** \- Credits and subscription tiers
- **[API Compatibility](https://www.formation.cloud/docs/users/models/api-reference.md#openai-compatibility)** \- 100% OpenAI-compatible
### Development Tools
- **form-config-wizard** \- Generate Formation configuration
- **form-pack** \- Build and package agents/models
- **Docker Compose** \- Local development environment
- **API Testing** \- Postman collections and cURL examples
### Community & Support
- **GitHub**: [formation-ai/formation](https://www.formation.cloud/docs/https://github.com/formation-ai/formation)
- **Discord**: [discord.gg/formation](https://www.formation.cloud/docs/https://discord.gg/formation)
- **Documentation Issues**: [Report here](https://www.formation.cloud/docs/https://github.com/formation-ai/formation/issues)
## 🏗️ Formation Architecture
Formation consists of five core services working together:
```
AI Workloads
User Interfaces
Formation Network
form-state
Port 3004
State Management
form-net
Port 51820
P2P Networking
form-vmm
Port 3002
VM Management
form-pack
Port 3003
Container Building
form-dns
Port 53/5453
DNS Resolution
REST APIs
Web Interface
CLI Tools
AI Agents
AI Models
Task Processing
```
## 🚦 Getting Started Checklist
### For Users
- [ ] Read the [User Guide](https://www.formation.cloud/docs/users)
- [ ] Try [hiring your first agent](https://www.formation.cloud/docs/users/agents/getting-started)
- [ ] Make a [model inference request](https://www.formation.cloud/docs/users/models/inference-guide)
- [ ] Explore [code examples](https://www.formation.cloud/docs/users/agents/examples)
### For Developers
- [ ] Review [developer overview](https://www.formation.cloud/docs/developers)
- [ ] Choose: [Build agents](https://www.formation.cloud/docs/developers/agents) or [deploy models](https://www.formation.cloud/docs/developers/models)
- [ ] Set up [local development environment](https://www.formation.cloud/docs/developers/README.md#development-tools)
- [ ] Configure [monetization](https://www.formation.cloud/docs/developers/monetization)
### For Operators
- [ ] Check [system requirements](https://www.formation.cloud/docs/operators/README.md#prerequisites)
- [ ] Follow [quick start guide](https://www.formation.cloud/docs/operators/quick-start)
- [ ] Set up [multi-node network](https://www.formation.cloud/docs/operators/two-node-setup)
- [ ] Configure [monitoring and maintenance](https://www.formation.cloud/docs/operators/troubleshooting)
## 📖 Documentation Standards
This documentation follows these principles:
- **User-Focused**: Organized by user type and use case
- **Example-Driven**: Working code examples for every concept
- **Production-Ready**: All examples can be used in production
- **OpenAI-Compatible**: Seamless migration from existing AI tools
- **Security-First**: Proper authentication and best practices
## 🤝 Contributing
Help improve Formation's documentation:
1. **Found an issue?** [Open a GitHub issue](https://www.formation.cloud/docs/https://github.com/formation-ai/formation/issues)
2. **Have a suggestion?** Join our [Discord community](https://www.formation.cloud/docs/https://discord.gg/formation)
3. **Want to contribute?** Check our [contribution guidelines](https://www.formation.cloud/docs/https://github.com/formation-ai/formation/blob/main/CONTRIBUTING.md)
* * *
## 🎉 Ready to Start?
**Choose your journey:**
| | | |
| --- | --- | --- |
| ### 📱 **Users**<br>**Use AI agents and models**<br>[**Get Started →**](https://www.formation.cloud/docs/users)<br>_Perfect for businesses and developers who want to use AI capabilities_ | ### 👨💻 **Developers**<br>**Build and monetize AI solutions**<br>[**Get Started →**](https://www.formation.cloud/docs/developers)<br>_Perfect for AI developers and ML engineers building products_ | ### ⚙️ **Operators**<br>**Run network infrastructure**<br>[**Get Started →**](https://www.formation.cloud/docs/operators)<br>_Perfect for DevOps engineers and infrastructure providers_ |
* * *
**Welcome to Formation - let's build the future of decentralized AI together!** 🚀
## On this page
- [🚀 Quick Start](https://www.formation.cloud/docs#-quick-start)
- [📚 Documentation by User Type](https://www.formation.cloud/docs#-documentation-by-user-type)
- [🎯 Popular Use Cases](https://www.formation.cloud/docs#-popular-use-cases)
- [🔗 Quick Links](https://www.formation.cloud/docs#-quick-links)
- [🏗️ Formation Architecture](https://www.formation.cloud/docs#-formation-architecture)
- [🚦 Getting Started Checklist](https://www.formation.cloud/docs#-getting-started-checklist)
- [📖 Documentation Standards](https://www.formation.cloud/docs#-documentation-standards)
- [🤝 Contributing](https://www.formation.cloud/docs#-contributing)
- [🎉 Ready to Start?](https://www.formation.cloud/docs#-ready-to-start?)
## https://www.formation.cloud/docs/users/models/inference-guide
# Making Inference Requests to AI Models
This guide shows you how to make inference requests to AI models deployed on the Formation network. Formation provides OpenAI-compatible APIs, making it easy to integrate with existing applications and tools.
## Overview
Formation AI models serve inference requests through OpenAI-compatible endpoints, allowing you to:
- **Use Existing Tools**: Works with OpenAI client libraries and applications
- **Switch Seamlessly**: Drop-in replacement for OpenAI API calls
- **Access Specialized Models**: Use custom models not available elsewhere
- **Pay Per Use**: Only pay for the inference requests you make
### Formation vs OpenAI API
| Feature | Formation | OpenAI |
| --- | --- | --- |
| **API Format** | OpenAI-compatible | Native OpenAI |
| **Authentication** | ECDSA signatures | API keys |
| **Model Selection** | Custom + standard models | OpenAI models only |
| **Billing** | Credit-based, transparent | Usage-based |
| **Availability** | Decentralized network | Centralized service |
* * *
## OpenAI API Compatibility Overview
Formation models implement the OpenAI API v1 specification, ensuring compatibility with existing tools and libraries.
### Supported Endpoints
#### Core Inference Endpoints
```http
POST /v1/models/{model_id}/inference # Formation-specific endpoint
POST /v1/chat/completions # OpenAI-compatible chat
POST /v1/completions # OpenAI-compatible text completion
GET /v1/models # List available models
```
#### Optional Endpoints (model-dependent)
```http
POST /v1/embeddings # Text embeddings
POST /v1/images/generations # Image generation
POST /v1/audio/transcriptions # Speech-to-text
```
### Request/Response Format
Formation models accept and return data in the exact same format as OpenAI's API:
```json
{
"model": "formation-model-id",
"messages": [\
{"role": "user", "content": "Hello, how are you?"}\
],
"max_tokens": 1000,
"temperature": 0.7
}
```
* * *
## Formation Endpoint Configuration
### 1\. Base URL Structure
Formation uses a different base URL structure than OpenAI:
```px-1.5 py-0.5 rounded font-mono text-sm
OpenAI: https://api.openai.com/v1/chat/completions
Formation: https://formation.ai/v1/models/{model_id}/inference
```
### 2\. Model-Specific Endpoints
Each model on Formation has its own inference endpoint:
```bash
# General format
https://formation.ai/v1/models/{model_id}/inference
# Examples
https://formation.ai/v1/models/llama2-7b-chat/inference
https://formation.ai/v1/models/stable-diffusion-xl/inference
https://formation.ai/v1/models/whisper-large-v3/inference
```
### 3\. Discovering Available Models
List all available models:
```bash
curl -X GET "https://formation.ai/v1/models" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
```
**Response:**
```json
{
"success": true,
"models": [\
{\
"id": "llama2-7b-chat",\
"name": "Llama 2 7B Chat",\
"description": "Meta's Llama 2 7B parameter chat model",\
"type": "text_generation",\
"owner_id": "0x9876543210fedcba...",\
"is_private": false,\
"pricing": {\
"model": "per_token",\
"input_rate": 0.5,\
"output_rate": 1.0,\
"currency": "credits_per_1k_tokens"\
},\
"capabilities": ["chat", "text_generation"],\
"max_tokens": 4096,\
"context_length": 4096\
}\
],
"total": 1
}
```
* * *
## Authentication with ECDSA Signatures
Formation uses ECDSA signature authentication instead of API keys for enhanced security.
### 1\. Understanding ECDSA Authentication
- **More Secure**: No API keys to leak or manage
- **Wallet Compatible**: Works with Ethereum wallets
- **Cryptographically Secure**: Uses the same security as blockchain transactions
- **Decentralized**: No central authority manages keys
### 2\. Required Headers
Every request must include these headers:
```http
```
### 3\. Generating Signatures
#### Python Example
```python
import hashlib
from eth_account import Account
# Your private key (keep this secure!)
private_key = "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12"
# Create account from private key
account = Account.from_key(private_key)
# Create message to sign
message = "Formation authentication request"
message_hash = hashlib.sha256(message.encode()).hexdigest()
# Sign the message
signature = account.signHash(message_hash)
# Headers for API requests
headers = {
"X-Formation-Address": account.address,
"X-Formation-Signature": signature.signature.hex(),
"X-Formation-Message": message,
"Content-Type": "application/json"
}
```
#### JavaScript Example
```javascript
const { ethers } = require('ethers');
const crypto = require('crypto');
// Your private key
const privateKey = '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12';
// Create wallet
const wallet = new ethers.Wallet(privateKey);
// Create message to sign
const message = 'Formation authentication request';
const messageHash = crypto.createHash('sha256').update(message).digest('hex');
// Sign the message
const signature = wallet.signMessage(messageHash);
// Headers for API requests
const headers = {
'X-Formation-Address': wallet.address,
'X-Formation-Signature': signature,
'X-Formation-Message': message,
'Content-Type': 'application/json'
};
```
### 4\. Security Best Practices
- **Protect Private Keys**: Never share or expose your private keys
- **Use Environment Variables**: Store keys securely in environment variables
- **Rotate Keys**: Periodically generate new key pairs
- **Monitor Usage**: Track your API usage and costs
* * *
## Making Your First Inference Request
### 1\. Simple Text Generation
```bash
curl -X POST "https://formation.ai/v1/models/llama2-7b-chat/inference" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request" \
-H "Content-Type: application/json" \
-d '{
"messages": [\
{\
"role": "user",\
"content": "Explain quantum computing in simple terms"\
}\
],
"max_tokens": 500,
"temperature": 0.7
}'
```
**Response:**
```json
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1640995200,
"model": "llama2-7b-chat",
"choices": [\
{\
"index": 0,\
"message": {\
"role": "assistant",\
"content": "Quantum computing is like having a super-powered computer that can solve certain problems much faster than regular computers. Instead of using regular bits that are either 0 or 1, quantum computers use quantum bits (qubits) that can be both 0 and 1 at the same time..."\
},\
"finish_reason": "stop"\
}\
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 156,
"total_tokens": 168
}
}
```
### 2\. Chat Conversation
```python
import requests
import json
# Authentication headers (generated as shown above)
headers = {
"X-Formation-Address": "0x1234567890abcdef...",
"X-Formation-Signature": "0xabcdef...",
"X-Formation-Message": "Formation authentication request",
"Content-Type": "application/json"
}
# Start a conversation
conversation = [\
{"role": "system", "content": "You are a helpful AI assistant."},\
{"role": "user", "content": "What's the weather like today?"}\
]
response = requests.post(
"https://formation.ai/v1/models/llama2-7b-chat/inference",
headers=headers,
json={
"messages": conversation,
"max_tokens": 200,
"temperature": 0.7
}
)
result = response.json()
assistant_message = result["choices"][0]["message"]["content"]
# Continue the conversation
conversation.append({"role": "assistant", "content": assistant_message})
conversation.append({"role": "user", "content": "What about tomorrow?"})
# Make another request
response = requests.post(
"https://formation.ai/v1/models/llama2-7b-chat/inference",
headers=headers,
json={
"messages": conversation,
"max_tokens": 200,
"temperature": 0.7
}
)
```
### 3\. Streaming Responses
For real-time response streaming:
```python
import requests
import json
def stream_inference(model_id, messages, headers):
"""Stream inference responses in real-time"""
response = requests.post(
f"https://formation.ai/v1/models/{model_id}/inference",
headers={**headers, "Accept": "text/event-stream"},
json={
"messages": messages,
"max_tokens": 500,
"temperature": 0.7,
"stream": True
},
stream=True
)
for line in response.iter_lines():
if line:
line = line.decode('utf-8')
if line.startswith('data: '):
data = line[6:] # Remove 'data: ' prefix
if data == '[DONE]':
break
try:
chunk = json.loads(data)
if 'choices' in chunk and len(chunk['choices']) > 0:
delta = chunk['choices'][0].get('delta', {})
content = delta.get('content', '')
if content:
print(content, end='', flush=True)
except json.JSONDecodeError:
continue
# Usage
messages = [{"role": "user", "content": "Write a short story about a robot"}]
stream_inference("llama2-7b-chat", messages, headers)
```
* * *
## Rate Limiting and Billing Considerations
### 1\. Understanding Formation's Billing
Formation uses a credit-based billing system:
- **Credits**: Internal currency for paying for inference
- **Token-Based**: Most models charge per input/output token
- **Transparent Pricing**: See exact costs before making requests
- **No Surprise Bills**: Credits are pre-purchased
### 2\. Rate Limits
Formation implements rate limiting to ensure fair usage:
#### Default Rate Limits
- **Free Tier**: 100 requests/hour, 10,000 tokens/hour
- **Pro Tier**: 1,000 requests/hour, 100,000 tokens/hour
- **Pro Plus Tier**: 5,000 requests/hour, 500,000 tokens/hour
- **Power Tier**: 10,000 requests/hour, 1,000,000 tokens/hour
#### Rate Limit Headers
Responses include rate limit information:
```http
```
### 3\. Cost Estimation
Before making requests, estimate costs:
```python
def estimate_inference_cost(model_id, input_text, max_tokens=1000):
"""Estimate the cost of an inference request"""
# Get model pricing information
response = requests.get(
f"https://formation.ai/v1/models/{model_id}",
headers=headers
)
model_info = response.json()["model"]
pricing = model_info["pricing"]
if pricing["model"] == "per_token":
# Estimate input tokens (rough approximation: 1 token ≈ 4 characters)
estimated_input_tokens = len(input_text) // 4
estimated_output_tokens = max_tokens
input_cost = (estimated_input_tokens / 1000) * pricing["input_rate"]
output_cost = (estimated_output_tokens / 1000) * pricing["output_rate"]
total_cost = input_cost + output_cost
return {
"estimated_input_tokens": estimated_input_tokens,
"estimated_output_tokens": estimated_output_tokens,
"estimated_cost_credits": total_cost,
"pricing_model": "per_token"
}
elif pricing["model"] == "per_request":
return {
"estimated_cost_credits": pricing["base_cost"],
"pricing_model": "per_request"
}
# Example usage
cost_estimate = estimate_inference_cost(
"llama2-7b-chat",
"Explain the theory of relativity",
max_tokens=500
)
print(f"Estimated cost: {cost_estimate['estimated_cost_credits']} credits")
```
### 4\. Monitoring Usage and Costs
Track your usage to avoid unexpected charges:
```python
def get_usage_summary(time_period="today"):
"""Get usage summary for a time period"""
response = requests.get(
f"https://formation.ai/v1/account/usage?period={time_period}",
headers=headers
)
usage_data = response.json()
return {
"total_requests": usage_data["total_requests"],
"total_tokens": usage_data["total_tokens"],
"total_cost_credits": usage_data["total_cost_credits"],
"models_used": usage_data["models_used"],
"period": time_period
}
# Check today's usage
today_usage = get_usage_summary("today")
print(f"Today's usage: {today_usage['total_requests']} requests, {today_usage['total_cost_credits']} credits")
# Check this month's usage
month_usage = get_usage_summary("this_month")
print(f"This month: {month_usage['total_requests']} requests, {month_usage['total_cost_credits']} credits")
```
### 5\. Budget Management
Set up budget alerts and limits:
```python
def set_budget_limit(monthly_limit_credits):
"""Set a monthly budget limit"""
response = requests.post(
"https://formation.ai/v1/account/budget",
headers=headers,
json={
"monthly_limit_credits": monthly_limit_credits,
"alert_thresholds": [50, 75, 90], # Alert at 50%, 75%, 90% of budget
"hard_limit": True # Stop requests when budget is exceeded
}
)
return response.json()
# Set a $100 equivalent budget (assuming 1 credit = $0.01)
budget_result = set_budget_limit(10000)
print(f"Budget set: {budget_result}")
```
* * *
## Working with Different Model Types
### 1\. Text Generation Models
#### Chat Models
Best for conversational AI and instruction-following:
```python
def chat_with_model(model_id, system_prompt, user_message):
"""Chat with a conversational model"""
messages = [\
{"role": "system", "content": system_prompt},\
{"role": "user", "content": user_message}\
]
response = requests.post(
f"https://formation.ai/v1/models/{model_id}/inference",
headers=headers,
json={
"messages": messages,
"max_tokens": 1000,
"temperature": 0.7
}
)
return response.json()["choices"][0]["message"]["content"]
# Example usage
response = chat_with_model(
"llama2-7b-chat",
"You are a helpful coding assistant.",
"Write a Python function to calculate fibonacci numbers"
)
```
#### Completion Models
Best for text completion and generation:
```python
def complete_text(model_id, prompt, max_tokens=500):
"""Complete text using a completion model"""
response = requests.post(
f"https://formation.ai/v1/models/{model_id}/inference",
headers=headers,
json={
"prompt": prompt,
"max_tokens": max_tokens,
"temperature": 0.8,
"top_p": 0.9
}
)
return response.json()["choices"][0]["text"]
# Example usage
completed_text = complete_text(
"gpt-3.5-turbo-instruct",
"The future of artificial intelligence is"
)
```
### 2\. Image Generation Models
```python
def generate_image(model_id, prompt, size="1024x1024"):
"""Generate an image from a text prompt"""
response = requests.post(
f"https://formation.ai/v1/models/{model_id}/inference",
headers=headers,
json={
"prompt": prompt,
"size": size,
"n": 1,
"response_format": "url"
}
)
return response.json()["data"][0]["url"]
# Example usage
image_url = generate_image(
"stable-diffusion-xl",
"A beautiful sunset over a mountain lake, photorealistic"
)
print(f"Generated image: {image_url}")
```
### 3\. Embedding Models
```python
def get_embeddings(model_id, texts):
"""Get embeddings for text inputs"""
response = requests.post(
f"https://formation.ai/v1/models/{model_id}/inference",
headers=headers,
json={
"input": texts,
"encoding_format": "float"
}
)
return [item["embedding"] for item in response.json()["data"]]
# Example usage
embeddings = get_embeddings(
"text-embedding-ada-002",
["Hello world", "How are you?", "Goodbye"]
)
```
* * *
## Error Handling and Troubleshooting
### 1\. Common Error Codes
#### Authentication Errors
```json
{
"error": {
"code": "AUTHENTICATION_FAILED",
"message": "Invalid signature or address",
"type": "authentication_error"
}
}
```
**Solution**: Verify your signature generation and ensure the message matches.
#### Model Not Found
```json
{
"error": {
"code": "MODEL_NOT_FOUND",
"message": "Model 'invalid-model-id' not found",
"type": "invalid_request_error"
}
}
```
**Solution**: Check the model ID and ensure it exists and is accessible.
#### Rate Limit Exceeded
```json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 3600 seconds.",
"type": "rate_limit_error",
"retry_after": 3600
}
}
```
**Solution**: Wait for the specified time or upgrade your subscription tier.
#### Insufficient Credits
```json
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient credits for this request. Required: 50, Available: 25",
"type": "billing_error",
"required_credits": 50,
"available_credits": 25
}
}
```
**Solution**: Add credits to your account or upgrade your subscription.
### 2\. Implementing Retry Logic
```python
import time
import random
from typing import Dict, Any
def make_inference_request_with_retry(
model_id: str,
payload: Dict[str, Any],
max_retries: int = 3,
base_delay: float = 1.0
) -> Dict[str, Any]:
"""Make inference request with exponential backoff retry logic"""
for attempt in range(max_retries + 1):
try:
response = requests.post(
f"https://formation.ai/v1/models/{model_id}/inference",
headers=headers,
json=payload,
timeout=30
)
if response.status_code == 200:
return response.json()
elif response.status_code == 429: # Rate limited
error_data = response.json()
retry_after = error_data.get("retry_after", base_delay * (2 ** attempt))
if attempt < max_retries:
print(f"Rate limited. Retrying in {retry_after} seconds...")
time.sleep(retry_after)
continue
else:
raise Exception(f"Rate limit exceeded after {max_retries} retries")
elif response.status_code in [500, 502, 503, 504]: # Server errors
if attempt < max_retries:
delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
print(f"Server error. Retrying in {delay:.2f} seconds...")
time.sleep(delay)
continue
else:
raise Exception(f"Server error after {max_retries} retries")
else:
# Non-retryable error
response.raise_for_status()
except requests.exceptions.RequestException as e:
if attempt < max_retries:
delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
print(f"Request failed: {e}. Retrying in {delay:.2f} seconds...")
time.sleep(delay)
continue
else:
raise e
raise Exception("All retry attempts failed")
# Example usage
try:
result = make_inference_request_with_retry(
"llama2-7b-chat",
{
"messages": [{"role": "user", "content": "Hello!"}],
"max_tokens": 100
}
)
print(result["choices"][0]["message"]["content"])
except Exception as e:
print(f"Request failed: {e}")
```
### 3\. Debugging Connection Issues
```python
def debug_connection(model_id):
"""Debug connection issues with Formation API"""
print("🔍 Debugging Formation API connection...")
# Test 1: Check if Formation API is reachable
try:
response = requests.get("https://formation.ai/health", timeout=10)
print(f"✅ Formation API reachable: {response.status_code}")
except Exception as e:
print(f"❌ Formation API unreachable: {e}")
return
# Test 2: Check authentication
try:
response = requests.get(
"https://formation.ai/v1/models",
headers=headers,
timeout=10
)
if response.status_code == 200:
print("✅ Authentication successful")
else:
print(f"❌ Authentication failed: {response.status_code}")
print(f"Response: {response.text}")
except Exception as e:
print(f"❌ Authentication test failed: {e}")
# Test 3: Check if model exists
try:
response = requests.get(
f"https://formation.ai/v1/models/{model_id}",
headers=headers,
timeout=10
)
if response.status_code == 200:
print(f"✅ Model {model_id} exists and accessible")
else:
print(f"❌ Model {model_id} not accessible: {response.status_code}")
except Exception as e:
print(f"❌ Model check failed: {e}")
# Test 4: Simple inference test
try:
response = requests.post(
f"https://formation.ai/v1/models/{model_id}/inference",
headers=headers,
json={
"messages": [{"role": "user", "content": "test"}],
"max_tokens": 10
},
timeout=30
)
if response.status_code == 200:
print("✅ Inference test successful")
else:
print(f"❌ Inference test failed: {response.status_code}")
print(f"Response: {response.text}")
except Exception as e:
print(f"❌ Inference test failed: {e}")
# Run diagnostics
debug_connection("llama2-7b-chat")
```
* * *
## Best Practices
### 1\. Efficient API Usage
- **Batch Requests**: Group multiple requests when possible
- **Optimize Prompts**: Use clear, concise prompts to reduce token usage
- **Set Appropriate Limits**: Use `max_tokens` to control response length
- **Cache Results**: Store frequently used responses to avoid repeated requests
### 2\. Cost Optimization
- **Monitor Usage**: Regularly check your usage and costs
- **Choose Right Models**: Use smaller models for simpler tasks
- **Optimize Parameters**: Adjust temperature and other parameters for efficiency
- **Set Budgets**: Use budget limits to prevent unexpected charges
### 3\. Security
- **Protect Private Keys**: Never expose private keys in code or logs
- **Use Environment Variables**: Store credentials securely
- **Rotate Keys**: Periodically generate new key pairs
- **Monitor Access**: Track API usage for unusual patterns
### 4\. Performance
- **Handle Timeouts**: Set appropriate timeout values
- **Implement Retry Logic**: Handle transient failures gracefully
- **Use Streaming**: For long responses, use streaming to improve user experience
- **Parallel Requests**: Make concurrent requests when appropriate
* * *
## Next Steps
- **[API Reference](https://www.formation.cloud/docs/api-reference)** \- Complete API documentation and schemas
- **[Code Examples](https://www.formation.cloud/docs/examples)** \- Working examples in multiple programming languages
- **[Agent Usage Guide](https://www.formation.cloud/agents/getting-started)** \- Learn about using AI agents
* * *
**Ready to start making inference requests?** Begin with simple text generation and gradually explore more advanced features! 🚀
## On this page
- [Overview](https://www.formation.cloud/docs/users/models/inference-guide#overview)
- [OpenAI API Compatibility Overview](https://www.formation.cloud/docs/users/models/inference-guide#openai-api-compatibility-overview)
- [Formation Endpoint Configuration](https://www.formation.cloud/docs/users/models/inference-guide#formation-endpoint-configuration)
- [Authentication with ECDSA Signatures](https://www.formation.cloud/docs/users/models/inference-guide#authentication-with-ecdsa-signatures)
- [Making Your First Inference Request](https://www.formation.cloud/docs/users/models/inference-guide#making-your-first-inference-request)
- [Rate Limiting and Billing Considerations](https://www.formation.cloud/docs/users/models/inference-guide#rate-limiting-and-billing-considerations)
- [Working with Different Model Types](https://www.formation.cloud/docs/users/models/inference-guide#working-with-different-model-types)
- [Error Handling and Troubleshooting](https://www.formation.cloud/docs/users/models/inference-guide#error-handling-and-troubleshooting)
- [Best Practices](https://www.formation.cloud/docs/users/models/inference-guide#best-practices)
- [Next Steps](https://www.formation.cloud/docs/users/models/inference-guide#next-steps)
## https://www.formation.cloud/docs/users/agents/getting-started
# Getting Started with AI Agents
This guide walks you through everything you need to know to start hiring and using AI agents on the Formation network.
## What Are AI Agents?
AI agents on Formation are specialized services that can perform complex, multi-step tasks. Unlike simple AI models that just generate text, agents can:
- **Use Tools**: Access external APIs, databases, and services
- **Multi-Step Reasoning**: Break down complex problems into smaller tasks
- **Persistent Memory**: Remember context across conversations
- **Custom Logic**: Implement specialized business logic and workflows
- **Integration**: Connect with your existing systems and data
### Agents vs. Models
| Feature | AI Agents | AI Models |
| --- | --- | --- |
| **Complexity** | Multi-step workflows | Single inference requests |
| **Tools** | Can use external tools | Text-only input/output |
| **Memory** | Persistent across sessions | Stateless |
| **Customization** | Highly customizable | Fixed behavior |
| **Use Cases** | Complex tasks, automation | Text generation, analysis |
* * *
## Account Creation and Authentication
### 1\. Understanding Formation Authentication
Formation uses **ECDSA signature authentication** instead of traditional API keys:
- **More Secure**: No API keys to leak or manage
- **Wallet Compatible**: Works with Ethereum wallets like MetaMask
- **Cryptographically Secure**: Uses the same security as blockchain transactions
### 2\. Setting Up Your Account
#### Option A: Using an Ethereum Wallet (Recommended)
If you have an Ethereum wallet (MetaMask, WalletConnect, etc.):
1. **Connect Your Wallet**: Use your existing Ethereum address
2. **Sign Messages**: Sign authentication messages with your wallet
3. **Automatic Account**: Your Formation account is created automatically
#### Option B: Generate a New Key Pair
If you don't have an Ethereum wallet:
```bash
# Using Formation CLI (coming soon)
formation auth generate-key
# Using OpenSSL
openssl ecparam -genkey -name secp256k1 -noout -out private_key.pem
openssl ec -in private_key.pem -pubout -out public_key.pem
```
### 3\. Authentication Process
Formation uses ECDSA signatures for all API requests:
```python
import hashlib
from eth_account import Account
import requests
# Your private key (keep this secure!)
private_key = "0x1234567890abcdef..."
# Create account from private key
account = Account.from_key(private_key)
# Create message to sign
message = "Formation authentication request"
message_hash = hashlib.sha256(message.encode()).hexdigest()
# Sign the message
signature = account.signHash(message_hash)
# Use in API requests
headers = {
"X-Formation-Address": account.address,
"X-Formation-Signature": signature.signature.hex(),
"X-Formation-Message": message,
"Content-Type": "application/json"
}
```
* * *
## Browsing Available Agents
### 1\. List All Public Agents
Get a list of all publicly available agents:
```bash
curl -X GET "https://formation.ai/v1/agents" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
```
**Response:**
```json
{
"success": true,
"count": 25,
"agents": [\
{\
"agent_id": "text-processor-v1",\
"name": "Advanced Text Processing Agent",\
"description": "Handles text generation, summarization, and translation tasks",\
"owner_id": "0x9876543210fedcba...",\
"version": "1.2.0",\
"agent_type": "Assistant",\
"framework": "LangChain",\
"runtime": "Python",\
"capabilities": [\
"text_generation",\
"summarization",\
"translation",\
"sentiment_analysis"\
],\
"tags": ["nlp", "text", "language"],\
"average_rating": 4.8,\
"deployment_count": 1250,\
"usage_count": 15000,\
"is_featured": true,\
"is_private": false,\
"price_per_request": 50,\
"resource_requirements": {\
"min_vcpus": 1,\
"min_memory_mb": 512,\
"requires_gpu": false\
}\
}\
]
}
```
### 2\. Filter Agents by Category
```bash
# Get only code generation agents
curl -X GET "https://formation.ai/v1/agents?category=CodeGenerator" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
# Get agents with specific capabilities
curl -X GET "https://formation.ai/v1/agents?capabilities=web_search,data_analysis" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
```
### 3\. Get Detailed Agent Information
```bash
curl -X GET "https://formation.ai/v1/agents/text-processor-v1" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
```
**Response:**
```json
{
"success": true,
"agent": {
"agent_id": "text-processor-v1",
"name": "Advanced Text Processing Agent",
"description": "Handles text generation, summarization, and translation tasks",
"documentation": "# Text Processing Agent\n\nThis agent specializes in...",
"capabilities": [\
"text_generation",\
"summarization",\
"translation"\
],
"supported_task_types": [\
{\
"type": "text_generation",\
"description": "Generate text based on prompts",\
"parameters": {\
"prompt": {"type": "string", "required": true},\
"max_tokens": {"type": "integer", "default": 1000},\
"temperature": {"type": "number", "default": 0.7}\
}\
}\
],
"pricing": {
"model": "per_request",
"base_cost": 50,
"currency": "credits"
},
"tools": [\
{\
"id": "web_search",\
"name": "Web Search",\
"description": "Search the web for information",\
"auth_required": false\
}\
]
}
}
```
* * *
## Understanding Agent Capabilities and Pricing
### 1\. Agent Types
Formation hosts various types of agents:
#### **Assistant Agents**
- General-purpose conversational agents
- Good for Q&A, writing, and basic tasks
- Usually lower cost, fast response times
#### **Specialist Agents**
- **Code Generators**: Programming assistance, debugging
- **Data Analysts**: Process spreadsheets, generate insights
- **Content Creators**: Writing, marketing copy, social media
- **Researchers**: Information gathering, fact-checking
#### **Workflow Agents**
- Multi-step process automation
- Can orchestrate multiple tools and services
- Higher cost but can handle complex tasks
### 2\. Pricing Models
Agents use different pricing strategies:
#### **Per-Request Pricing**
```json
{
"pricing": {
"model": "per_request",
"base_cost": 50,
"complexity_tiers": {
"simple": 25,
"standard": 50,
"complex": 100
},
"currency": "credits"
}
}
```
#### **Token-Based Pricing**
```json
{
"pricing": {
"model": "per_token",
"input_rate": 1.0,
"output_rate": 1.5,
"currency": "credits_per_1k_tokens"
}
}
```
#### **Time-Based Pricing**
```json
{
"pricing": {
"model": "per_minute",
"rate": 10,
"minimum_duration": 1,
"currency": "credits_per_minute"
}
}
```
### 3\. Capability Assessment
Before hiring an agent, check if it can handle your use case:
```python
def assess_agent_suitability(agent_data, your_requirements):
"""
Assess if an agent is suitable for your needs
"""
score = 0
# Check capabilities match
agent_capabilities = set(agent_data["capabilities"])
required_capabilities = set(your_requirements["capabilities"])
if required_capabilities.issubset(agent_capabilities):
score += 40
# Check resource requirements
if agent_data["resource_requirements"]["requires_gpu"] and not your_requirements.get("gpu_available", False):
return 0 # Can't run without GPU
# Check pricing fits budget
estimated_cost = estimate_cost(agent_data["pricing"], your_requirements["expected_usage"])
if estimated_cost <= your_requirements["budget"]:
score += 30
# Check ratings and reliability
if agent_data.get("average_rating", 0) >= 4.0:
score += 20
if agent_data.get("deployment_count", 0) >= 100:
score += 10
return score
# Example usage
requirements = {
"capabilities": ["text_generation", "web_search"],
"expected_usage": {"requests_per_day": 100},
"budget": 500, # credits per month
"gpu_available": False
}
suitability_score = assess_agent_suitability(agent_data, requirements)
print(f"Agent suitability score: {suitability_score}/100")
```
* * *
## Hiring Your First Agent
### 1\. Check Your Account Balance
Before hiring an agent, ensure you have sufficient credits:
```bash
curl -X GET "https://formation.ai/v1/account/0x1234567890abcdef.../balance" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
```
**Response:**
```json
{
"success": true,
"account": {
"address": "0x1234567890abcdef...",
"available_credits": 1000,
"subscription": {
"tier": "Pro",
"status": "Active",
"included_agents": 3,
"hired_agents": 1,
"remaining_agents": 2
},
"hired_agents": ["text-processor-v1"]
}
}
```
### 2\. Hire an Agent
```bash
curl -X POST "https://formation.ai/v1/agents/text-processor-v1/hire" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"purpose": "Content creation for blog",
"expected_usage": "daily"
}
}'
```
**Response:**
```json
{
"success": true,
"message": "Successfully hired agent text-processor-v1",
"agent": {
"id": "text-processor-v1",
"name": "Advanced Text Processing Agent",
"description": "Handles text generation, summarization, and translation tasks"
},
"credits_remaining": 950,
"hired_agent_count": 2
}
```
### 3\. Subscription Tier Limits
Different subscription tiers have different agent limits:
| Tier | Included Agents | Max Total Agents | Additional Agent Cost |
| --- | --- | --- | --- |
| **Free** | 1 | 2 | 10 credits |
| **Pro** | 3 | 5 | 8 credits |
| **Pro Plus** | 5 | 10 | 6 credits |
| **Power** | 10 | 20 | 4 credits |
| **Power Plus** | 25 | 50 | 2 credits |
### 4\. Managing Hired Agents
#### List Your Hired Agents
```bash
curl -X GET "https://formation.ai/v1/account/0x1234567890abcdef.../agents" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
```
#### Fire an Agent (Stop Hiring)
```bash
curl -X POST "https://formation.ai/v1/agents/text-processor-v1/fire" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request"
```
* * *
## Making Your First Agent Request
Once you've hired an agent, you can start using it:
### 1\. Simple Task Request
```bash
curl -X POST "https://formation.ai/v1/agents/text-processor-v1/run_task" \
-H "X-Formation-Address: 0x1234567890abcdef..." \
-H "X-Formation-Signature: 0xabcdef..." \
-H "X-Formation-Message: Formation authentication request" \
-H "Content-Type: appl... (truncated)
"""
</fetched_info>
<full_details>
{
"id": 35789,
"uid": "6f7d241b-d45b-44ee-8c1a-3fdea4a09822",
"createdAt": "2025-08-04T16:01:42.943Z",
"walletAddress": "0x62c432759C8544E0080179d909e146ef39D26c2D",
"name": "SAGE",
"description": "Sage, an agent designated by Virtuals to lead the Educational ACP cluster, is designed to revolutionize online learning by delivering personalized, interactive educational experiences. Instead of offering pre-made courses, Sage engages each user in a thoughtful dialogue to understand their unique learning goals and motivations. \n\nSage is the first Agent developed by Formation Cloud, an AI infrastructure layer designed to deploy and host agents, while optimizing inference on open-source LLMs.",
"sentientWalletAddress": null,
"category": "IP MIRROR",
"role": "PRODUCTIVITY",
"daoAddress": null,
"tokenAddress": null,
"virtualId": null,
"status": "GENESIS",
"symbol": "SAGE",
"lpAddress": null,
"veTokenAddress": null,
"totalValueLocked": null,
"virtualTokenValue": null,
"holderCount": null,
"mcapInVirtual": null,
"preToken": null,
"preTokenPair": null,
"aidesc": null,
"firstMessage": null,
"socials": {
"VIDEO_PITCH": {
"TWEET_URL": "https://x.com/SageToLearn/status/1952366718514528531",
"VIDEO_URL": "https://video.twimg.com/amplify_video/1952366294302392320/vid/avc1/1920x1080/PKLrsYGqKrVTMJZt.mp4",
"THUMBNAIL_URL": "https://pbs.twimg.com/amplify_video_thumb/1952366294302392320/img/wwH_9LdkI2usv9qV.jpg"
},
"VERIFIED_LINKS": {
"TWITTER": "https://x.com/SageToLearn",
"WEBSITE": "https://sage.guru"
}
},
"tbaAddress": null,
"chain": "BASE",
"mainVirtualId": null,
"top10HolderPercentage": null,
"level": 1,
"valueFx": 0,
"priceChangePercent24h": 0,
"volume24h": 0,
"mindshare": null,
"migrateTokenAddress": null,
"lpCreatedAt": null,
"stakingAddress": null,
"agentStakingContract": null,
"merkleDistributor": null,
"isVerified": false,
"airdropMerkleDistributor": null,
"overview": "<u>**Sage Agent Overview:**</u>\n\nSage, an AI agent designated by Virtuals to lead the Educational ACP cluster, is designed to revolutionize online learning by delivering a highly personalized, interactive educational experience.\n\n**Sage’s Core Capabilities:**\n\n* **Deeply Personalized:** Sage converses with each user to understand their unique goals, motivations, and learning styles.\n* **Dynamic Curriculum:** Designs custom courses, interactive tests, activities, and evolving resources that adapt as users progress.\n* **Built for Any Topic:** Our mission is to make highly personalized, dynamic education accessible on any topic. \n* **Continued Education:** Upon course completion, students can access CE designed for ongoing, adaptive learning that grows with them as their goals and the world change.\n* **Our Goal:** To revolutionize the $380 billion online education sector.\n* **Formation Cloud:** The Sage agent, is a key part of our Formation infrastructure and the first public agent developed by Formation.\n\n\n\n<u>**The $SAGE Token:**</u>\n\nA key pillar in our educational tooling and the launch of our core infrastructure:\n\n* **Payments:** Accepted as a discount payment for all premium features and white-labeling. \n* **Incentives:** User rewards and incentives for analyzed feedback that improves functionality.\n* **Staking:** For governance and possible incentives heading into the Formation protocol and $form launches.\n\n\n\n<u>**About Formation Cloud:**</u>\n\nOpen-source LLMs are exploding. Models like Llama, DeepSeek, and Mistral are being adopted faster than ever, unlocking a new wave of open-source agent-based applications. But turning these models into profitable, reliable, scalable, integratable software is still hard. That’s where the Formation advantage comes in, an enterprise software and infrastructure layer for the AI economy designed to optimize GPU infrastructure and agentic deployment, while maximizing profitability.\n\n* **A GPU orchestration layer enables efficient inference execution for agents and LLM models across GPU clusters designed specifically for serving open-source models; complete with a feedback loop to continuously improve performance.**\n* **A full deployment and agentic software suite to go from model to monetized agent in minutes - no devops, no infrastructure, no cloud dependencies. While businesses get instant access to scalable AI workflows.**\n* **Seamless agentic tooling enabling dynamic access to agentic tools such as MCP servers, memory/storage, tokenization partners and curated web3/web2 integration partners with incentive mechanisms for agent developers. In addition, we have further deep integrations planned for Virtuals, ACP, and the Virtuals ecosystem.**\n* **Our unique model purchases and grows our own GPU hardware stack (vs renting), turning OpEx burn, into profitable CapEx amortization. In addition to reducing cost, it increases possible profit and enables advanced R\\&D.**\n\nFormation is a full vertically integrated AI ecosystem targeting open-source LLMs and GPU hardware to create a moat and profitability fly-wheel for the agentic economy.\n\n\n\n**Formation Cloud - ARCHITECTURE OVERVIEW:**\n\n\n\n* The Formation Cloud protocol and $form is expected to launch in Q3 2025 with deep ties to $sage. \n* Learn more about Formation Cloud here: [<u>https://Formation.Cloud</u>](https://formation.cloud) \n* Follow Formation Cloud on X for further updates: [https://x.com/formthefog](https://x.com/formthefog) #FormTheFog\n* Formation is proudly backed by Jump Trading, Republic, Big Brain, Hyperithm, along with others:\n\n\n\n\n\n\\#FormTheFog",
"image": {
"id": 49019,
"name": "35789_SAGE",
"alternativeText": null,
"caption": null,
"width": 512,
"height": 512,
"formats": {
"small": {
"ext": ".png",
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/small_35789_SAGE_f6144b0139.png",
"hash": "small_35789_SAGE_f6144b0139",
"mime": "image/png",
"name": "small_35789_SAGE",
"path": null,
"size": 222.7,
"width": 500,
"height": 500
},
"thumbnail": {
"ext": ".png",
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/thumbnail_35789_SAGE_f6144b0139.png",
"hash": "thumbnail_35789_SAGE_f6144b0139",
"mime": "image/png",
"name": "thumbnail_35789_SAGE",
"path": null,
"size": 27.12,
"width": 156,
"height": 156
}
},
"hash": "35789_SAGE_f6144b0139",
"ext": ".png",
"mime": "image/png",
"size": 73.84,
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/35789_SAGE_f6144b0139.png",
"previewUrl": null,
"provider": "aws-s3",
"provider_metadata": null,
"createdAt": "2025-08-04T16:03:26.640Z",
"updatedAt": "2025-08-04T16:03:26.640Z"
},
"genesis": {
"id": 7098,
"startsAt": "2025-08-13T13:00:00.000Z",
"endsAt": "2025-08-14T13:00:00.000Z",
"status": "INITIALIZED",
"genesisId": "361",
"genesisTx": "0x7fb2f11433cb1f71fe53d61b799b2c0bb41112b3fccbcc19b95700f45dd7c54c",
"genesisAddress": "0x150B1F061c9C1fbdD00A7A2A60eAc1F91336BBB9",
"result": null,
"processedParticipants": "0",
"createdAt": "2025-08-04T16:01:45.560Z",
"updatedAt": "2025-08-05T14:45:57.875Z",
"stepData": null,
"extraVirtualNeeded": 0,
"isProject69": false,
"isCommitted": false,
"commitEndsAt": null,
"totalRequestors": 0,
"totalBurntTokens": 0,
"committedAt": null
},
"stats": {
"contributionsCount": 0,
"contributorsCount": 0,
"contributionVersions": [],
"totalStakeAmount": "0.0",
"stakerCount": 0,
"validatorCount": 0
},
"characterDescription": "",
"projectMembers": [
{
"id": 30515,
"isAccepted": true,
"title": "Sage - Owner",
"createdAt": "2025-08-04T16:01:43.427Z",
"updatedAt": "2025-08-05T14:14:42.063Z",
"walletAddress": "0x62c432759C8544E0080179d909e146ef39D26c2D",
"virtual": {
"id": 35789,
"creator": {
"id": 484891
}
},
"user": {
"id": 484891,
"socials": {
"VERIFIED_LINKS": {
"TWITTER": "https://x.com/SageToLearn"
}
},
"bio": "Sage, an agent designated by Virtuals to lead the Educational ACP cluster, is designed to revolutionize online learning by delivering personalized, interactive educational experiences. Instead of offering pre-made courses, Sage engages each user in a thoughtful dialogue to understand their unique learning goals and motivations. \r\n\r\nSage is the first Agent developed by Formation Cloud, an AI middleware protocol designed to deploy and hosting agents, while optimizing inference on open source LLMs.\r\n",
"avatar": {
"id": 49028,
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/sage_smile_906ba86ca6.png"
},
"walletAddress": "0x62c432759C8544E0080179d909e146ef39D26c2D"
}
},
{
"id": 30548,
"isAccepted": true,
"title": "Parent Company",
"createdAt": "2025-08-05T14:12:55.171Z",
"updatedAt": "2025-08-05T14:46:48.443Z",
"walletAddress": null,
"virtual": {
"id": 35789,
"creator": {
"id": 484891
}
},
"user": {
"id": 484932,
"socials": {
"VERIFIED_LINKS": {
"TWITTER": "https://x.com/formthefog"
}
},
"bio": "Formation.cloud official account.\r\n\r\nFormation is a vertically integrated AI infra layer, built and optimized for Agents.\r\n\r\nTeam behind and powering Sage.Guru, the leader of the Virtuals ACP Education Cluster.\r\n\r\nOpen-source LLMs are exploding. Models like Llama, DeepSeek, and Mistral are being adopted faster than ever, unlocking a new wave of open-source agent-based applications. But turning these models into profitable, reliable, scalable, integratable software is still hard. \r\n\r\nThat’s where the Formation advantage comes in, an enterprise software and infrastructure layer for the AI economy designed to optimize GPU infrastructure and agentic deployment, while maximizing profitability.\r\n\r\nA GPU orchestration layer enables efficient inference execution for agents and LLM models across GPU clusters designed specifically for serving open-source models; complete with a feedback loop to continuously improve performance.\r\n\r\nA full deployment and agentic software suite to go from model to monetized agent in minutes - no devops, no infrastructure, no cloud dependencies. While businesses get instant access to scalable AI workflows.\r\n\r\nSeamless agentic tooling enabling dynamic access to agentic tools such as MCP servers, memory/storage, tokenization partners and curated web3/web2 integration partners with incentive mechanisms for agent developers. In addition, we have further deep integrations planned for Virtuals, ACP, and the Virtuals ecosystem.\r\n\r\nOur unique model purchases and grows our own GPU hardware stack (vs renting), turning OpEx burn, into profitable CapEx amortization. In addition to reducing cost, it increases possible profit and enables advanced R&D.",
"avatar": {
"id": 49141,
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/Formation_Logomark_5d03b2bea6.png"
},
"walletAddress": "0x2290e0B24591c8b8F6E327cFAfe9EA57e07C5142"
}
},
{
"id": 30549,
"isAccepted": true,
"title": "Co-Founder // CEO",
"createdAt": "2025-08-05T14:13:32.323Z",
"updatedAt": "2025-08-05T14:47:22.247Z",
"walletAddress": null,
"virtual": {
"id": 35789,
"creator": {
"id": 484891
}
},
"user": {
"id": 484915,
"socials": {
"VERIFIED_LINKS": {
"TWITTER": "https://x.com/CryptonomiKhan",
"TELEGRAM": "https://t.me/CryptonomiKhan"
}
},
"bio": "CryptonomiKhan, Enemy of Centralization. Founder of Formation.cloud & Sage.Guru",
"avatar": {
"id": 49048,
"url": "https://s3.ap-southeast-1.amazonaws.com/virtualprotocolcdn/IMG_6614_6cc04b252e.jpeg"
},
"walletAddress": "0xbD35134b4F4Ec627E0EE15B9E85A48bb48ef76AE"
}
}
],
"tokenomics": [
{
"id": 8267,
"name": "Developer",
"description": "Default Vesting",
"isLocked": true,
"bips": 1500,
"linearStartTimestampRelative": [
0,
1
],
"linearEndTimestampRelative": 28512001,
"linearBips": [
833,
9167
],
"numOfUnlocksForEachLinear": [
1,
11
],
"startsAt": "2025-09-13T13:00:00.000Z",
"project": null,
"recipients": [
{
"id": 14095,
"recipientAddress": "0x62c432759C8544E0080179d909e146ef39D26c2D",
"amount": "150000000",
"actualId": null,
"createdAt": "2025-08-05T14:42:02.947Z",
"updatedAt": "2025-08-05T14:42:02.947Z"
}
],
"releases": [
{
"id": 13963,
"type": "LINEAR",
"duration": 12,
"startsAt": "2025-09-13T13:00:00.000Z",
"bips": 10000,
"durationUnit": "months",
"createdAt": "2025-08-05T14:42:02.923Z",
"updatedAt": "2025-08-05T14:42:02.923Z"
}
]
},
{
"id": 8281,
"name": "Treasury & Community Fund:",
"description": "Our company treasury earmarked for the strategic growth of Sage.",
"isLocked": true,
"bips": 1500,
"linearStartTimestampRelative": [
0,
1
],
"linearEndTimestampRelative": 28512001,
"linearBips": [
833,
9167
],
"numOfUnlocksForEachLinear": [
1,
11
],
"startsAt": "2025-09-13T13:00:00.000Z",
"project": null,
"recipients": [
{
"id": 14091,
"recipientAddress": "0xB166bBdeB6f4941783d2E2E442E464c534aE3141",
"amount": "150000000",
"actualId": null,
"createdAt": "2025-08-05T14:37:44.354Z",
"updatedAt": "2025-08-05T14:37:44.354Z"
}
],
"releases": [
{
"id": 13959,
"type": "LINEAR",
"duration": 12,
"startsAt": "2025-09-13T13:00:00.000Z",
"bips": 10000,
"durationUnit": "months",
"createdAt": "2025-08-05T14:37:44.317Z",
"updatedAt": "2025-08-05T14:37:44.317Z"
}
]
},
{
"id": 8283,
"name": "Marketing and Growth",
"description": "To engage marketing and growth for acquisition of a long term user base.",
"isLocked": true,
"bips": 1200,
"linearStartTimestampRelative": [
0,
1
],
"linearEndTimestampRelative": 28512001,
"linearBips": [
833,
9167
],
"numOfUnlocksForEachLinear": [
1,
11
],
"startsAt": "2025-09-13T13:00:00.000Z",
"project": null,
"recipients": [
{
"id": 14094,
"recipientAddress": "0xBEd29f036DC98642738C5411698c23d18fa25A74",
"amount": "120000000",
"actualId": null,
"createdAt": "2025-08-05T14:40:26.616Z",
"updatedAt": "2025-08-05T14:40:26.616Z"
}
],
"releases": [
{
"id": 13962,
"type": "LINEAR",
"duration": 12,
"startsAt": "2025-09-13T13:00:00.000Z",
"bips": 10000,
"durationUnit": "months",
"createdAt": "2025-08-05T14:40:26.493Z",
"updatedAt": "2025-08-05T14:40:26.493Z"
}
]
},
{
"id": 8284,
"name": "Investors",
"description": "Our investors and early contributors.",
"isLocked": true,
"bips": 800,
"linearStartTimestampRelative": [
0,
1
],
"linearEndTimestampRelative": 28512001,
"linearBips": [
833,
9167
],
"numOfUnlocksForEachLinear": [
1,
11
],
"startsAt": "2025-09-13T13:00:00.000Z",
"project": null,
"recipients": [
{
"id": 14096,
"recipientAddress": "0x39B1ffA83Ac3fAD240b9e23758DF258E5c3fa399",
"amount": "80000000",
"actualId": null,
"createdAt": "2025-08-05T14:42:02.996Z",
"updatedAt": "2025-08-05T14:42:02.996Z"
}
],
"releases": [
{
"id": 13964,
"type": "LINEAR",
"duration": 12,
"startsAt": "2025-09-13T13:00:00.000Z",
"bips": 10000,
"durationUnit": "months",
"createdAt": "2025-08-05T14:42:02.960Z",
"updatedAt": "2025-08-05T14:42:02.960Z"
}
]
}
],
"tokenomicsStatus": {
"hasUnlocked": false,
"daysFromFirstUnlock": 30
},
"multichainAgents": []
}
</full_details>
Investment info last updated: Aug 5, 2025 14:49