Skip to content

00-overview.md

Latest commit

 

History

History
121 lines (75 loc) · 6.31 KB

00-overview.md

File metadata and controls

121 lines (75 loc) · 6.31 KB

00 — What is a QiForge Oracle?

Purpose: Understand what an oracle is, what it can do, and what you'll build in this playbook.

The 30-Second Pitch

A QiForge Oracle is an AI assistant that lives on the internet with its own identity, its own encrypted communication channels, and a growing library of skills it can use to get things done.

Think of it like hiring a team member who:

  • Has a verified identity on the blockchain (so people know it's legit)
  • Talks to every user through a private, encrypted channel (so conversations stay confidential)
  • Can learn new skills from a shared registry (so it gets more capable over time)
  • Runs 24/7 on your server (so it's always available)

You're about to build one.

The Four Pillars

Every QiForge Oracle is built on four pillars:

Blockchain Identity

Your oracle gets a DID (Decentralized Identifier) — like a digital passport registered on the IXO blockchain. This lets anyone verify who your oracle is and what it's authorized to do.

E2E Encrypted Communication

Every conversation between a user and your oracle happens in a private, encrypted room. Nobody else can read those messages — not even you.

AI Reasoning

Your oracle uses a large language model (like GPT or Claude) to understand messages, think step by step, and respond intelligently. It can also use skills and sub-agents to handle complex tasks.

API Layer

A server that ties everything together — receives messages, routes them through the AI, and streams responses back to the user.

Want to add a new tool? Just paste its URL into mcp.ts. That's it. See Chapter 07 — MCP Servers.

Architecture at a Glance

graph LR
    U[User] -->|Portal / Slack / Matrix| API[Oracle API]
    API --> AI[AI Engine]
    AI -->|uses| SK[Skills Registry]
    AI -->|stores| MX[Matrix Rooms]
    API -->|identity| BC[Blockchain]
Loading

Users send messages through the Portal, Slack, or Matrix. The Oracle API receives them and passes them to the AI Engine, which reasons about the message, uses skills if needed, and streams a response back. Behind the scenes, conversations are stored in encrypted Matrix rooms and the oracle's identity lives on the blockchain.

What are Skills?

Skills are like apps on a phone — they give your oracle new abilities.

A skill is just a set of instructions (a SKILL.md file) that tells your oracle how to do something specific. There's a shared registry of skills that your oracle can browse and use on the fly — things like creating presentations, generating PDFs, analyzing data, or searching the web.

You can use skills that already exist, or publish your own for others to use.

Example: A user asks your oracle to "create a slide deck about climate change." Your oracle finds a presentation skill in the registry, reads its instructions, and produces the slides — all without you writing any code.

What You'll Build

This playbook takes you from zero to a fully deployed oracle, step by step:

Chapter What You'll Achieve
01 — Quickstart A running oracle that responds to messages
02 — Project Structure Understand your codebase and know where to find things
03 — Customize Your Oracle Give your oracle a unique personality and purpose
04 — Working with Skills Use existing skills and build your own
05 — Sub-Agents Add specialist agents for complex workflows
06 — Middlewares Add safety checks and billing
07 — MCP Servers Connect external services and tools
08 — Deployment Ship your oracle to production

Guides are standalone — pick any after completing the Quickstart:

Guide What It Covers
Publish Your First Oracle End-to-end: scaffold, customize, deploy, share
Memory Engine Give your oracle persistent memory across conversations
Payments & Claims Set up pricing and billing for your oracle
Building & Publishing Skills Create and publish your own skills

Prerequisites

Before starting, make sure you have:

  • Node.js 22+ — check with node --version
  • pnpm 10+ — install with npm install -g pnpm
  • Docker (optional) — only needed if you enable the credits system (install Docker)
  • IXO Mobile App — for blockchain authentication (iOS / Android)
  • OpenRouter API key — for LLM access (get one here)

How to Read This Playbook

Chapters 00–08 are meant to be read in order. Each builds on the previous.

Guides are standalone — pick whichever you need after completing 01 — Quickstart.

Reference pages are lookup material — environment variables, CLI commands, API endpoints, state schema, skills & sandbox API, troubleshooting.

Ready? Head to 01 — Quickstart to build your first oracle.