<p align="center">
<img src="./assets/logo/logo-1.png" alt="Portal" width="100" height="100">
</p>
<h1 align="center">
HippoX
</h1>
<h4 align="center">
An reliable AI runtime and skills orchestration engine with autonomous decision-making.<br>
A skill-driven AI runtime with autonomous decision-making that automatically loads and executes skills simply by writing a SKILL.md file.
</h4>
<p align="center">
<a href="https://github.com/0xhappyboy/hippo/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache2.0-d1d1f6.svg?style=flat&labelColor=1C2C2E&color=BEC5C9&logo=googledocs&label=license&logoColor=BEC5C9" alt="License"></a>
<a href="https://crates.io/crates/hippox">
<img src="https://img.shields.io/badge/crates-hippox-20B2AA.svg?style=flat&labelColor=0F1F2D&color=FFD700&logo=rust&logoColor=FFD700">
</a><a href="https://crates.io/crates/hippox">
<img src="https://img.shields.io/crates/d/hippox?style=flat&labelColor=0F1F2D&color=20B2AA&logo=rust&logoColor=white&label=downloads" alt="Crates.io Downloads">
</a>
</p>
<p align="center">
<a href="./README_zh-CN.md">็ฎไฝไธญๆ</a> | <a href="./README.md">English</a>
</p>
## ๐ Quick Links
| ๐ **Website** | [https://hippox.vercel.app/](https://hippox.vercel.app/) |
| ๐ **Documentation** | [https://hippox-docs-en.vercel.app/](https://hippox-docs-en.vercel.app/) |
| ๐ฆ **Crates.io** | [https://crates.io/crates/hippox](https://crates.io/crates/hippox) |
| ๐ป **GitHub** | [https://github.com/0xhappyboy/hippo](https://github.com/0xhappyboy/hippo) |
## Basic Usage
```rust
use hippox::{Hippox, tasks, TaskStatus};
use langhub::types::ModelProvider;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Initialize Hippox
let hippox = Hippox::new(ModelProvider::OpenAI, Some("sk-xxx".into()), None, ConfigInitMethod::ParamsJsonStr("{}".into())).await?;
// Submit task, get task_id immediately
let task_id = hippox.handle_natural_language("Calculate 15 * 3 and save to result.txt", None);
// Query task status from global task manager
loop {
if let Some(task) = tasks::get_task(&task_id).await {
println!("Status: {:?}, Progress: {}%", task.status, task.progress());
if matches!(task.status, TaskStatus::Completed | TaskStatus::Failed) {
println!("Result: {:?}", task.final_output);
break;
}
}
tokio::time::sleep(tokio::time::Duration::from_secs(1)).await;
}
Ok(())
}
```
## 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
<img src="./assets/architecture/skill_load_and_schedul_en.png" width="100%">
## 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 |
<table>
<tr>
<td align="left">
<h4>Chain</h4>
</td>
<td align="left">
<h4>Batch</h4>
</td>
</tr>
<tr>
<td align="center"><img src="./assets/architecture/chain_en.png" width="100%" ></td>
<td align="center"><img src="./assets/architecture/batch_en.png" width="100%"></td>
</tr>
<tr>
<td align="left">
<h4>ReAct</h4>
</td>
<td align="left">
<h4>PlanAndExecute</h4>
</td>
</tr>
<tr>
<td align="center"><img src="./assets/architecture/re-act_en.png" width="100%"></td>
<td align="center"><img src="./assets/architecture/plan-and-execute_en.png" width="100%"></td>
</tr>
</table>
## 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 |