su-skyclaw

Multi-Agent Collaborative AI Platform.

Overview

su-skyclaw is the orchestration layer for building collaborative AI agent teams backed by the su-skyclaw cognitive memory SDK. It provides token optimization, local model runtime, multi-agent coordination, and a 10+ platform integration layer — all in one Python package.

Core Capabilities

Layer	Modules	Description
Token Engine	`tracker`, `budget`, `calculator`	Real-time token counting, budget enforcement, cost estimation
Model Runtime	`router`, `fallback`, `optimizer`, `circuit_breaker`, `ollama`, `llama_cpp`	Multi-backend routing, fallback chains, quantization, fault-tolerant circuit breaker
Agent Framework	`partition`, `pool`, `planner`, `cleanup`, `roi`, `task_delegator`	Isolated memory partitions, shared pool, ROI tracking, intelligent task delegation
Orchestration	`registry`, `state_machine`, `intent_router`, `tool_registry`, `context_bus`	Agent discovery & health check, task lifecycle state machine, intent routing, universal tool registry, cross-agent Pub/Sub bus
Team Orchestration	`manager`, `orchestrator`, `runtime`	DAG-based task decomposition, agent lifecycle, parallel execution
Context Pipeline	`compressor`, `summarizer`, `truncator`, `window`, `scorer`	Context window management, compression, relevance scoring
Bayesian Reasoning	`cognitive_enhancer`, `pipeline`, `langgraph_adapter`	Dual-path (SDK/fallback) query, confidence calibration, feedback loops
Platform Integration	10+ adapters (WeChat, DingTalk, Feishu, Telegram, Discord, Slack...)	Webhook + async reply message processing, MCP protocol bridge (6000+ apps)
Lifecycle Hooks	`registry`, `notification`, `session`, `pre_tool_use`, `bayesian_hooks`	Non-invasive hook system for tool interception, notifications, feedback
Skill System	`parser`, `loader`, `executor`	SKILL.md parsing, skill discovery, sandboxed execution
Multimodal	`analyzer`, `compressor`	Image/audio token counting and compression

Quick Start

Installation

pip install su-skyclaw

With optional extras:

# Ollama local model support
pip install "su-skyclaw[ollama]"

# Full installation (all extras)
pip install "su-skyclaw[all]"

Basic Usage

from su_memory_agent.agent import AgentMemoryPartition, Memory
from su_memory_agent.team import TeamManager, TeamOrchestrator

# Create an agent team
manager = TeamManager()
orchestrator = TeamOrchestrator(manager)

# Decompose and execute a complex task
results = await orchestrator.execute("分析最近一周的销售数据并生成报告")
print(results)

Bayesian-Enhanced Query

from su_memory_agent.bayesian import BayesianPipeline

pipeline = BayesianPipeline()

result = await pipeline.enhance("agent-1", "What is the ROI of campaign X?")
print(result.bayesian)

# Check pipeline health
print(pipeline.health_report())

Task Delegation

from su_memory_agent.agent import TaskDelegator, DelegationTask
from su_memory_agent.team import TeamManager

manager = TeamManager()
delegator = TaskDelegator(manager)

task = DelegationTask(
    description="分析市场趋势",
    required_role="explorer",
    priority=3,
)
result = await delegator.delegate(task)
print(f"Task assigned to: {result.agent_id}")

Circuit Breaker for Model Calls

from su_memory_agent.model import ModelCircuitBreaker, CircuitBreakerConfig

cb = ModelCircuitBreaker(
    adapter=my_adapter,
    model_name="gpt-4o",
    config=CircuitBreakerConfig(failure_threshold=3, cooldown_seconds=30),
)

try:
    result = await cb.call("Explain quantum mechanics")
except CircuitBreakerOpenError:
    # Circuit is open — use cached response or fallback
    pass

Platform Integration

from su_memory_agent.platforms import PlatformRouter
from su_memory_agent.platforms.telegram import TelegramAdapter

router = PlatformRouter()
router.register(TelegramAdapter(bot_token="YOUR_BOT_TOKEN"))

# Handle incoming webhook
response = await router.handle_webhook("telegram", webhook_data)

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                      su-skyclaw                                  │
│                                                                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐               │
│  │  Token   │  │  Model   │  │  Context Pipeline │               │
│  │  Engine  │  │ Runtime  │  │  (compress/trunc) │               │
│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘               │
│       │              │                 │                          │
│  ┌────▼──────────────▼─────────────────▼─────────┐               │
│  │              Agent Framework                    │               │
│  │  partition · pool · planner · task_delegator   │               │
│  └────────────────────┬──────────────────────────┘               │
│                       │                                           │
│  ┌────────────────────▼──────────────────────────┐               │
│  │           Orchestration Layer                  │               │
│  │  AgentRegistry · TaskStateMachine              │               │
│  │  IntentRouter · ToolRegistry · CrossContextBus │               │
│  └────────────────────┬──────────────────────────┘               │
│                       │                                           │
│  ┌────────────────────▼──────────────────────────┐               │
│  │             Team Orchestration                  │               │
│  │   manager · orchestrator · runtime (DAG)      │               │
│  └────────────────────┬──────────────────────────┘               │
│                       │                                           │
│  ┌────────────────────▼──────────────────────────┐               │
│  │            Platform Integration                 │               │
│  │  WeChat · Telegram · Discord · Slack · MCP    │               │
│  └────────────────────────────────────────────────┘               │
│                                                                   │
│  su-skyclaw SDK (Memory Engine)                                   │
│  Vector Retrieval · Graph Store · Spatiotemporal Index            │
└──────────────────────────────────────────────────────────────────┘

Orchestration Layer Modules

Module	Description
AgentRegistry	Agent 注册/发现/健康检查中心，替代硬编码 agent_capabilities 字典
TaskStateMachine	任务生命周期状态机，7 状态（PENDING→RUNNING→WAITING→COMPLETED/FAILED/SKIPPED），支持超时检测与级联失败传播
IntentRouter	中英文关键词 + 语义意图路由，将用户输入分发到匹配的 Agent
ToolRegistry	通用工具注册中心，支持 register/unregister/get/list_by_category + OpenAI function calling schema 生成
CrossContextBus	跨 Agent Pub/Sub 上下文消息总线，Agent 发布上下文更新，其他 Agent 按主题订阅
BuiltinTools	内置工具集（echo / read_file / write_file / list_dir）
CrewAIToolBridge	CrewAI 工具 → ToolRegistry 桥接适配器
MCPToolBridge	6000+ MCP 工具延迟注册桥接

Requirements

Python >= 3.10
su-skyclaw SDK >= 2.5.0
tiktoken, httpx, pyyaml, pydantic, structlog, rich

Optional:

Ollama (pip install su-skyclaw[ollama])
llama.cpp (pip install su-skyclaw[llama-cpp])
Transformers + Torch (pip install su-skyclaw[multimodal])
LangGraph + CrewAI (pip install su-skyclaw[agent])

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -q

# Lint
ruff check src/su_memory_agent/

# Type check
mypy src/su_memory_agent/

License

Apache-2.0 — see LICENSE for details.

Sandysu737
/

su-skyclaw