{"id":30117394,"url":"https://github.com/longcipher/pocketflow-rs","last_synced_at":"2025-08-10T10:42:25.456Z","repository":{"id":307086743,"uuid":"974043934","full_name":"longcipher/pocketflow-rs","owner":"longcipher","description":"Pocket Flow: A minimalist AI workflow framework.","archived":false,"fork":false,"pushed_at":"2025-08-08T08:37:01.000Z","size":306,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-08T10:24:23.857Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/longcipher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-28T07:09:47.000Z","updated_at":"2025-08-08T08:37:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"992f0dd8-ed5d-4837-9260-0644659a2e06","html_url":"https://github.com/longcipher/pocketflow-rs","commit_stats":null,"previous_names":["longcipher/pocketflow-rs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/longcipher/pocketflow-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fpocketflow-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fpocketflow-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fpocketflow-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fpocketflow-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/longcipher","download_url":"https://codeload.github.com/longcipher/pocketflow-rs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fpocketflow-rs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269712986,"owners_count":24463216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-10T10:42:19.729Z","updated_at":"2025-08-10T10:42:25.393Z","avatar_url":"https://github.com/longcipher.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PocketFlow-RS\n\nA modern workflow framework ecosystem for Rust, providing type-safe, async workflow execution with powerful integrations including AI agents, cognitive capabilities, and tool automation.\n\n## 📦 Workspace Structure\n\nThis is a Cargo workspace containing five specialized crates:\n\n### [`pocketflow-core`](./pocketflow-core/)\n\nThe foundation workflow framework providing:\n\n- Type-safe state management with compile-time guarantees\n- Async/await support built on Tokio and dptree\n- Flexible context system with typed and JSON storage\n- Node-based architecture with dependency injection\n- Advanced flows with middleware and analytics\n- Batch processing and error handling with eyre\n\n### [`pocketflow-mcp`](./pocketflow-mcp/)\n\nModel Context Protocol (MCP) integration for workflows:\n\n- MCP client integration for calling external tools\n- MCP server implementation to expose workflow capabilities\n- Seamless context integration between MCP and workflows\n- Registry management for multiple connections\n- HTTP transport with authentication support\n\n### [`pocketflow-cognitive`](./pocketflow-cognitive/)\n\nCognitive extensions adding AI reasoning capabilities:\n\n- Chain-of-thought and reflection nodes\n- Goal-oriented and hierarchical planning\n- Multi-layered memory systems (working, episodic, semantic)\n- Non-intrusive extension of existing Node types\n- MCP integration for AI service calls\n\n### [`pocketflow-agent`](./pocketflow-agent/)\n\nAI Agent framework with genai integration:\n\n- AgentNode implementation for LLM-powered workflows\n- Multi-step agent execution with history tracking\n- Tool registry integration for agent capabilities\n- Streaming and multi-agent coordination support\n- Support for multiple AI providers (OpenAI, etc.)\n\n### [`pocketflow-tools`](./pocketflow-tools/)\n\nComprehensive tool system for workflow automation:\n\n- Tool abstraction with JSON schema validation\n- Tool registry for discovery and execution\n- Built-in utilities for common operations\n- Parameter validation and retry mechanisms\n- Integration across the entire ecosystem\n- New: Web search (simulate or HTTP GET) and Python execution tools (stdin, JSON stdout parsing)\n\n## 🚀 Quick Start\n\n### Basic Workflow with Core\n\n```toml\n[dependencies]\npocketflow-core = \"0.2.0\"\n```\n\n```rust\nuse pocketflow_core::prelude::*;\n\n#[derive(Clone, Debug, PartialEq, Eq, Hash)]\nenum WorkflowState {\n    Start, Processing, Success, Error\n}\n\nimpl FlowState for WorkflowState {\n    fn is_terminal(\u0026self) -\u003e bool {\n        matches!(self, WorkflowState::Success | WorkflowState::Error)\n    }\n}\n\nstruct ProcessingNode;\n\n#[async_trait]\nimpl Node for ProcessingNode {\n    type State = WorkflowState;\n\n    async fn execute(\u0026self, mut context: Context) -\u003e Result\u003c(Context, Self::State)\u003e {\n        context.set(\"result\", \"processed\")?;\n        Ok((context, WorkflowState::Success))\n    }\n\n    fn name(\u0026self) -\u003e String {\n        \"ProcessingNode\".to_string()\n    }\n}\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c()\u003e {\n    let flow = SimpleFlow::builder()\n        .initial_state(WorkflowState::Start)\n        .node(WorkflowState::Start, ProcessingNode)\n        .build()?;\n\n    let result = flow.execute(Context::new()).await?;\n    println!(\"Final state: {:?}\", result.final_state);\n    Ok(())\n}\n```\n\n### AI Agent Workflow\n\n```toml\n[dependencies]\npocketflow-core = \"0.2.0\"\npocketflow-agent = \"0.2.0\"\npocketflow-tools = \"0.2.0\"\n```\n\n```rust\nuse pocketflow_agent::prelude::*;\nuse pocketflow_core::prelude::*;\nuse pocketflow_tools::prelude::*;\nuse std::sync::Arc;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c()\u003e {\n    // Create agent configuration\n    let agent_config = AgentConfig {\n        name: \"task_processor\".to_string(),\n        model_config: ModelConfig {\n            provider: ModelProvider::OpenAI,\n            model_name: \"gpt-4o-mini\".to_string(),\n            ..Default::default()\n        },\n        system_prompt: \"You are a helpful task processing agent\".to_string(),\n        ..Default::default()\n    };\n\n    // Create tool registry\n    let mut tool_registry = ToolRegistry::new();\n    let text_tool = pocketflow_tools::custom::helpers::uppercase_tool();\n    tool_registry.register_tool(Box::new(text_tool)).await?;\n\n    // Create agent node with tools\n    let agent_node = AgentNode::new(agent_config)\n        .with_tools(Arc::new(tool_registry));\n\n    // Use in workflow\n    let mut context = Context::new();\n    context.set(\"input\", \"Process this text with AI\")?;\n    \n    let (result_context, _state) = agent_node.execute(context).await?;\n    if let Ok(Some(result)) = result_context.get_json::\u003cAgentResult\u003e(\"agent_result\") {\n        println!(\"Agent response: {:?}\", result.final_answer);\n    }\n    \n    Ok(())\n}\n```\n\n### Cognitive Workflow with Planning\n\n```toml\n[dependencies]\npocketflow-core = \"0.2.0\"\npocketflow-cognitive = \"0.2.0\"\npocketflow-mcp = \"0.2.0\"\n```\n\n```rust\nuse pocketflow_cognitive::prelude::*;\nuse pocketflow_core::prelude::*;\nuse std::sync::Arc;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c()\u003e {\n    // Mock MCP client for cognitive services\n    let mcp_client = Arc::new(MockMcpClient::new());\n    \n    // Create planning node\n    let planner = GoalOrientedPlanningNode::builder()\n        .name(\"task_planner\")\n        .with_mcp_client(mcp_client)\n        .with_goal(Goal {\n            id: \"optimize_workflow\".to_string(),\n            description: \"Optimize data processing workflow\".to_string(),\n            success_criteria: vec![\"Reduce latency by 30%\".to_string()],\n            constraints: vec![\"Budget under $5k\".to_string()],\n            priority: 8,\n        })\n        .on_success(WorkflowState::Success)\n        .on_error(WorkflowState::Error)\n        .build()?;\n\n    let flow = SimpleFlow::builder()\n        .initial_state(WorkflowState::Start)\n        .node(WorkflowState::Start, planner)\n        .build()?;\n\n    let result = flow.execute(Context::new()).await?;\n    println!(\"Planning completed: {:?}\", result.final_state);\n    Ok(())\n}\n```\n\n### Cognitive Agent and Plan Execution (think → plan → execute)\n\nThe cognitive crate includes ready-made nodes to chain reasoning, planning, and execution:\n\n- CognitiveAgentNode: performs thinking then planning and stores results in context.\n- IterativeCognitiveAgentNode: think → plan → reflect loop with optional simulated progress.\n- PlanExecutionNode: executes plan steps via an MCP tool with robust success criteria.\n\nHighlights:\n\n- Success criteria enforcement per step: substring, regex, and JSON Pointer equals/exists/contains.\n- Per-step overrides: enforce_success_criteria, max_retries, initial_backoff_ms, stop_on_error.\n- Retries with exponential backoff and optional early stop-on-error.\n\nExamples to try:\n\n```bash\ncargo run --example iterative_agent_demo --package pocketflow-cognitive\ncargo run --example think_plan_execute --package pocketflow-cognitive\n```\n\n### Web Search + Python Tools Example\n\n`pocketflow-tools` ships with two practical tools:\n\n- WebSearchTool: perform simulated or HTTP GET-based search/fetch (JSON output)\n- PythonExecutionTool: run Python code/files with timeout, stdin (string/JSON), and auto-parse stdout JSON into stdout_json\n\nRun the end-to-end example:\n\n```bash\ncargo run --example search_and_python_flow --package pocketflow-tools\n```\n\n## 🏗️ Architecture\n\n```text\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐\n│ pocketflow-core │    │ pocketflow-mcp   │    │ pocketflow-cognitive│\n├─────────────────┤    ├──────────────────┤    ├─────────────────────┤\n│ • Node trait    │    │ • MCP Client     │    │ • ThinkingNode      │\n│ • Context       │    │ • MCP Server     │    │ • PlanningNode      │\n│ • FlowState     │    │ • Registry       │    │ • Memory Systems    │\n│ • SimpleFlow    │    │ • Context Ext    │    │ • Cognitive Traits  │\n│ • AdvancedFlow  │    │ • MCP Nodes      │    │ • Goal-Oriented     │\n└─────────────────┘    └──────────────────┘    └─────────────────────┘\n         │                        │                          │\n         └───────┬────────────────┼─────────────────────────┘\n                 │                │\n    ┌─────────────────────────┐   │    ┌─────────────────────┐\n    │  pocketflow-agent       │   │    │  pocketflow-tools   │\n    ├─────────────────────────┤   │    ├─────────────────────┤\n    │ • AgentNode             │   │    │ • Tool trait        │\n    │ • GenAI Integration     │   │    │ • ToolRegistry      │\n    │ • Multi-Agent Support   │   │    │ • Parameter Schema  │\n    │ • Execution History     │   │    │ • Validation        │\n    │ • Streaming             │   │    │ • Built-in Tools    │\n    └─────────────────────────┘   │    └─────────────────────┘\n                 │                │              │\n                 └────────────────┼──────────────┘\n                                  │\n                ┌─────────────────────────┐\n                │    Your Application     │\n                │                         │\n                │ • Custom Nodes          │\n                │ • Workflow Logic        │\n                │ • AI Agents             │\n                │ • Cognitive Planning    │\n                │ • Tool Integration      │\n                │ • MCP Services          │\n                └─────────────────────────┘\n```\n\n## 🔧 Development\n\nThe workspace is configured with shared dependencies and development tools:\n\n```bash\n# Format all code\njust format\n\n# Run all lints\njust lint\n\n# Test all crates\njust test\n\n# Run examples from specific crates\ncargo run --example basic --package pocketflow-core\ncargo run --example simple_agent_demo --package pocketflow-agent\ncargo run --example thinking_workflow --package pocketflow-cognitive\ncargo run --example simple_mcp_demo --package pocketflow-mcp\ncargo run --example iterative_agent_demo --package pocketflow-cognitive\ncargo run --example think_plan_execute --package pocketflow-cognitive\ncargo run --example search_and_python_flow --package pocketflow-tools\n```\n\n## 📋 Features by Crate\n\n### Core Framework Features\n\n- ✅ Type-safe state machines\n- ✅ Async workflow execution  \n- ✅ Context management (typed + JSON)\n- ✅ Node composition patterns\n- ✅ Middleware system\n- ✅ Analytics and monitoring\n- ✅ Batch processing\n- ✅ Error handling with eyre\n\n### MCP Integration Features\n\n- ✅ MCP client for tool calling\n- ✅ MCP server implementation\n- ✅ Workflow context extensions\n- ✅ Registry management\n- ✅ HTTP transport with authentication\n- ⏳ WebSocket transport (planned)\n- ⏳ Prompt templates (planned)\n\n### Cognitive Extensions Features\n\n- ✅ Chain-of-thought reasoning\n- ✅ Goal-oriented planning\n- ✅ Hierarchical planning\n- ✅ Multi-layered memory systems\n- ✅ Reflection and explanation nodes\n- ✅ MCP integration for AI services\n- ✅ Adaptive planning (node included; configurable)\n- ✅ Plan execution with success criteria enforcement (substring/regex/JSON Pointer)\n- ✅ Per-step overrides for enforcement and retry/backoff/stop-on-error\n- ⏳ Learning capabilities (planned)\n\n### AI Agent Features\n\n- ✅ GenAI integration (OpenAI, etc.)\n- ✅ AgentNode for workflow integration\n- ✅ Multi-step execution with history\n- ✅ Tool registry integration\n- ✅ Streaming support\n- ✅ Multiple agent coordination\n- ⏳ Custom model providers (planned)\n- ⏳ Advanced agent orchestration (planned)\n\n### Tool System Features\n\n- ✅ Tool abstraction with JSON schema\n- ✅ Parameter validation\n- ✅ Tool registry and discovery\n- ✅ Built-in utility tools\n- ✅ Retry and timeout mechanisms\n- ✅ Custom tool development\n- ✅ Web search tool (simulate/HTTP GET, header/limit support)\n- ✅ Python execution tool (stdin string/JSON, stdout JSON auto-parse)\n- ⏳ Tool composition (planned)\n- ⏳ Advanced caching (planned)\n\n## 🎯 Use Cases\n\n### Data Processing Pipelines\n\nUse `pocketflow-core` for structured data transformations with state tracking and error handling.\n\n### AI-Powered Workflows  \n\nCombine `pocketflow-agent` with `pocketflow-tools` to build intelligent workflows that can reason, plan, and execute complex tasks using LLMs.\n\n### Cognitive Task Planning\n\nUse `pocketflow-cognitive` for workflows that need planning, reasoning, and memory capabilities for complex problem-solving.\n\n### API Orchestration\n\nChain multiple service calls with error handling, retry logic, and state management using the core framework.\n\n### Tool Automation\n\nUse `pocketflow-tools` to create standardized, validated tool interfaces for workflow automation.\n\n### AI Agent Ecosystems\n\nBuild multi-agent systems using `pocketflow-agent` with coordination, communication, and task delegation.\n\n### MCP Service Integration\n\nUse `pocketflow-mcp` as a protocol for service-to-service communication and external tool integration within workflows.\n\n## 📚 Documentation\n\n- [Core Framework Documentation](./pocketflow-core/README.md)\n- [MCP Integration Documentation](./pocketflow-mcp/README.md)\n- [Cognitive Extensions Documentation](./pocketflow-cognitive/README.md)\n- [AI Agent Framework Documentation](./pocketflow-agent/README.md)\n- [Tool System Documentation](./pocketflow-tools/README.md)\n- [API Documentation](https://docs.rs/pocketflow-core)\n- [Examples Directory](./pocketflow-core/examples/)\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Check existing issues and PRs\n2. Follow the coding conventions\n3. Add tests for new features\n4. Update documentation as needed\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongcipher%2Fpocketflow-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flongcipher%2Fpocketflow-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongcipher%2Fpocketflow-rs/lists"}