docs.rs failed to build hippox-0.5.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build:
hippox-0.3.9
🔗 Quick Links
| Resource | Link |
|---|---|
| 🌐 Website | https://hippox.vercel.app/ |
| 📖 Documentation | https://hippox-docs-en.vercel.app/ |
| 📦 Crates.io | https://crates.io/crates/hippox |
| 💻 GitHub | https://github.com/0xhappyboy/hippo |
Basic Usage
use ;
use ModelProvider;
async
Hippox Core Working Principle
Natural Language
═══════════════════════════════════════════════════════════════════════════════════
HIPPOX NATURAL LANGUAGE ARCHITECTURE (English)
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ INPUT LAYER │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ User Input: "Calculate 2+3 and save the result to result.txt" │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Hippox::handle_natural_language(input, callback) │ │
│ │ → Returns task_id immediately, executes async in background │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SCHEDULER LAYER: Skill Selection │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SkillScheduler::select_skill(user_input) │ │
│ │ │ │
│ │ Method 1: Trigger Matching (keywords) │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ "calculate" → math_calculator │ "save" → file_write │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ ↓ if no match │ │
│ │ Method 2: LLM Intelligent Selection │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Prompt: Skills Registry + User Input → LLM → {"action": "calc"} │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ EXECUTION LAYER: Workflow Modes │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │
│ │ ReAct │ │ Batch │ │ Chain │ │ PlanAndExecute │ │
│ │ (default) │ │ Parallel │ │ Variable │ │ DAG + Cond │ │
│ │ Use for: │ │ Use for: │ │ Use for: │ │ Use for: │ │
│ │ Open-ended│ │ Independent│ │ Pipeline │ │ Complex Deps │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────────┘ │
│ │
│ This example uses ReAct mode: │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Iteration 1: Think → {"action": "math_calculator", "params": {...}} │ │
│ │ Act → Execute → Returns "5" │ │
│ │ Observe → Result: 5, still need to save │ │
│ │ │ │
│ │ Iteration 2: Think → {"action": "file_write", "params": {...}} │ │
│ │ Act → Execute → Returns "Saved" │ │
│ │ Observe → Task complete │ │
│ │ │ │
│ │ Iteration 3: Think → {"action": "done", "message": "2+3=5, saved"} │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ATOMIC SKILLS LAYER │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ SKILL REGISTRY │ │
│ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │ │
│ │ │math_ │ │file_ │ │ net_ │ │ time_ │ │system_│ │ db_ │ │ │
│ │ │calc │ │write │ │http │ │now │ │info │ │query │ │ │
│ │ │power │ │read │ │ping │ │format │ │exec │ │redis │ │ │
│ │ │stats │ │delete │ │dns │ │parse │ │port │ │k8s │ │ │
│ │ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Execute: registry::get_skill("math_calculator") → execute(params) → "5" │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ OUTPUT LAYER │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Final Output: "2+3=5, saved to result.txt" │ │
│ │ │ │
│ │ Callbacks triggered: │ │
│ │ • on_step_start() → Step started │ │
│ │ • on_step_success() → Step succeeded, took XXms │ │
│ │ • on_workflow_complete() → Workflow done, total XXms │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════════════════
Features: Async Task Pool │ Priority Queue │ Timeout │ Pause/Resume │ Retry │ I18n
═══════════════════════════════════════════════════════════════════════════════════
SKILL.md
═══════════════════════════════════════════════════════════════════════════════════
HIPPOX SKILL.md WORKFLOW ARCHITECTURE (English)
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ INPUT LAYER: SKILL.md File │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ ./skills/web-search/SKILL.md │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐│ │
│ │ │ --- ││ │
│ │ │ name: web-search ││ │
│ │ │ description: Search the web using a search engine ││ │
│ │ │ version: 1.0.0 ││ │
│ │ │ author: lobster-team ││ │
│ │ │ triggers: ││ │
│ │ │ patterns: ["search for", "find online", "google"] ││ │
│ │ │ case_sensitive: false ││ │
│ │ │ allowed_tools: ["net_httprequest", "json"] ││ │
│ │ │ parameters: ││ │
│ │ │ - name: query ││ │
│ │ │ type: string ││ │
│ │ │ description: Search keywords ││ │
│ │ │ required: true ││ │
│ │ │ - name: limit ││ │
│ │ │ type: integer ││ │
│ │ │ default: 10 ││ │
│ │ │ metadata: ││ │
│ │ │ emoji: 🔍 ││ │
│ │ │ os: [linux, macos, windows] ││ │
│ │ │ --- ││ │
│ │ │ # Search Execution Workflow ││ │
│ │ │ ││ │
│ │ │ 1. Parse user's search query ││ │
│ │ │ 2. Call search API: net_httprequest ││ │
│ │ │ 3. Parse JSON response ││ │
│ │ │ 4. Format and return results ││ │
│ │ └─────────────────────────────────────────────────────────────────────┘│ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ Hippox::handle_skill_md(path, params, callback) │ │
│ │ → SkillLoader::load_from_path() parses YAML frontmatter + Markdown │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ PARSING LAYER: SkillFile Structure │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ pub struct SkillFile { │ │
│ │ name: String, // "web-search" │ │
│ │ description: String, // "Search the web..." │ │
│ │ triggers: Option<SkillTrigger>, // Trigger configuration │ │
│ │ allowed_tools: Vec<String>, // ["net_httprequest", "json"] │ │
│ │ parameters: Vec<SkillParameter>, // Parameter definitions │ │
│ │ instructions: String, // Markdown execution instructions │ │
│ │ metadata: Option<SkillFrontmatterMetadata>, // Extended metadata │ │
│ │ path: PathBuf, // Original file path │ │
│ │ } │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ EXECUTION LAYER: WorkflowExecutor executes SKILL.md │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ WorkflowExecutor::execute_skill_md(skill_file, params) │ │
│ │ │ │
│ │ Step 1: Parameter Substitution │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ params = {"query": "Rust programming", "limit": 5} │ │ │
│ │ │ {{query}} in instructions → "Rust programming" │ │ │
│ │ │ {{limit}} in instructions → "5" │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Step 2: Build Enhanced Prompt │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ instructions + atomic skills list + instances list → full prompt│ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Step 3: Execute based on configured workflow mode │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ match workflow_mode { │ │ │
│ │ │ ReAct → execute_react() // Complex reasoning │ │ │
│ │ │ Batch → execute_batch() // Parallel independent tasks │ │ │
│ │ │ Chain → execute_chain() // Pipeline processing │ │ │
│ │ │ PlanAndExecute → execute_plan_and_execute() // Complex deps│ │ │
│ │ │ } │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
═══════════════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ATOMIC SKILLS INVOCATION LAYER │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ LLM generates calls based on instructions: │ │
│ │ │ │
│ │ {"action": "net_httprequest", "parameters": { │ │
│ │ "url": "https://api.search.com?q=Rust+programming", │ │
│ │ "method": "GET" │ │
│ │ }} │ │
│ │ │ │
│ │ Executor executes → returns search results JSON │ │
│ │ │ │
│ │ LLM continues → formats results │ │
│ │ │ │
│ │ {"action": "done", "message": "Found these results about Rust:\n1. "} │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
═══════════════════════════════════════════════════════════════════════════════════
SKILL.md Benefits: Community Contribution │ Versioning │ Auto-triggers │ Permissions
═══════════════════════════════════════════════════════════════════════════════════
How skill loaders and schedulers work
Task Pool
State Machine
Pending ──► Running ──► Completed
│ │
│ ├──► Paused ──► Running (resume)
│ │
│ └──► Cancelled
│
└──► Cancelled
│
└──► Failed ──► Pending (retry)
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Global Static (Auto-Start) │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ GLOBAL_TASK_POOL │ │
│ │ (Initialized at program load) │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Hippox Instance │
├─────────────────────────────────────────────────────────────────┤
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ TaskPool (Global) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │Task A │ │Task B │ │Task C │ │ │
│ │ │Pending │ │Running │ │Pending │ │ │
│ │ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ │ └────────────┼────────────┘ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────┐ │ │
│ │ │ Priority Queue │ │ │
│ │ │ [Task A, Task C] │ │ │
│ │ └──────────┬──────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────┐ │ │
│ │ │ Execution Engine │ (max: 10 workers) │ │
│ │ │ ┌────┐ ┌────┐ ┌────┐ │ │
│ │ │ │ W1 │ │ W2 │ │ W3 │ ... │ │
│ │ │ └──┬─┘ └──┬─┘ └──┬─┘ │ │
│ │ │ └──────┼──────┘ │ │
│ │ │ ▼ │ │
│ │ │ ┌─────────────────┐ │ │
│ │ │ │ ExecutableTask │ │ │
│ │ │ │ .execute() │ │ │
│ │ │ └─────────────────┘ │ │
│ │ └─────────────────────┘ │ │
│ │ ▲ │ │
│ │ ┌──────────┴──────────┐ │ │
│ │ │ Notifier (wakeup) │ │ │
│ │ └─────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ ExecutableTask Implementations │ │
│ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │
│ │ │ NaturalLanguageTask │ │ SkillMdTask │ │ │
│ │ │ • input │ │ • path │ │ │
│ │ │ • workflow_executor │ │ • params │ │ │
│ │ │ • scheduler │ │ • workflow_executor │ │ │
│ │ │ • skills_registry │ │ • scheduler │ │ │
│ │ │ • instances_registry│ │ • skills_registry │ │ │
│ │ └─────────────────────┘ └─────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ External APIs │
├─────────────────────────────────────────────────────────────────┤
│ handle_natural_language() → task_id (non-blocking) │
│ handle_skill_md() → task_id (non-blocking) │
│ get_task_status() / cancel() / pause() / resume() / retry() │
└─────────────────────────────────────────────────────────────────┘
Architectural Layering
┌─────────────────────────────────────────────────────────────┐
│ User Layer │
│ handle_natural_language() │
│ handle_skill_md() │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Workflow Layer │
│ WorkflowExecutor (ReAct / Batch / Chain / PlanAndExecute) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Scheduling Layer │
│ SkillScheduler (LLM Interaction, Skill Selection, Fallback)│
└──────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Execution Layer │
│ Executor (Parse LLM Response, Route to Skills) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Registry Layer │
│ Registry (Skill Registration, Instance Configs) │
└─────────────────────────────────────────────────────────────┘
Data Stream
1. Initialize Hippox
├── Load configuration (instance configs)
├── Generate skills_registry (cached)
├── Generate instances_registry (cached)
└── Generate welcome_message (cached)
2. First Conversation
├── is_first_message = false → true
├── Send welcome_message (includes both registries)
└── LLM knows all skills and instances
3. Subsequent Conversations
├── is_first_message = true → no longer sent
└── Reuse cached registries
Workflow Model
| Mode | Enum Value | Core Features | LLM Calls | Use Cases |
|---|---|---|---|---|
| ReAct | WorkflowMode::ReAct | Think → Act → Observe loop, LLM decides next step after each execution | 1 per skill + 1 final response | Open-ended tasks, dynamic decision making, error recovery |
| Batch | WorkflowMode::Batch | Execute multiple independent skills in parallel | 1 (generates batch plan) | Independent operations, bulk processing |
| Chain | WorkflowMode::Chain | Sequential execution with variable passing ({{variable}} syntax) | 1 (generates chain) | Linear pipelines, data transformation chains |
| PlanAndExecute | WorkflowMode::PlanAndExecute | One-time planning with conditional branching, variable references ({"$ref":"var"}), error handling (retry/skip/fail) | 1 plan + optional dynamic decisions | Complex workflows, conditional logic, deterministic tasks |
Atomic Skill Unit List
| Category | Skills | Description |
|---|---|---|
| File System | 5 skills | Read, write, delete, list, copy files |
| Archive | 5 skills | Create/extract ZIP/TAR archives, compress files |
| Math | 4 skills | Expression calculator, power/root, statistics, unit conversion |
| Crypto/Random | 10 skills | MD5, SHA256, SHA512, file hash, Base64 encode/decode, random number/string/uuid/password |
| Time | 1 skill | Get current date/time |
| Network | 20 skills | HTTP requests, URL fetch, ICMP/TCP/batch ping, DNS lookup/reverse/batch/test, IP info/validate/range/local, TCP/UDP send/receive/broadcast, FTP upload/download/list/delete |
| OS Management | 18 skills | Reboot, shutdown, sleep, lock, logout, hibernate, uptime, load average, hostname, time, user info, disk/memory/CPU/network/battery info, desktop notification |
| Process | 6 skills | List, kill (by PID/name), check running, get PID, detailed process info |
| System | 7 skills | System info, exec command, port scan/lookup/test, clipboard get/set/clear |
| Document | 11 skills | Markdown, CSV, XML, Excel, PDF read/write/parse |
| Messaging | 5 skills | Email, Telegram, DingTalk, Feishu, WeCom |
| Database | 12 skills | PostgreSQL, MySQL, Redis, SQLite query/execute/list |
| Text Processing | 4 skills | Diff, sort, deduplicate, filter |
| Regex | 4 skills | Match, find, replace, extract |
| K8s | 18 skills | Pod/deployment/service/node/namespace/event/configmap/secret/ingress/statefulset management, logs, exec, scale, restart, port-forward, apply YAML, delete |
| Docker | 5 skills | List, start/stop, logs, inspect, exec |
| GitHub | 7 skills | Get repo, create/list issues, star, search, get user, list PRs |
| Task Scheduler | 3 skills | Schedule, unschedule, list tasks |
| Image Processing | 6 skills | Resize, convert, info, rotate, crop, compress |