Skip to content

API Reference (auto-generated)

Reference for selected public symbols in the hiveflow package. For tutorials see Getting Started.

Core engine

hiveflow.HiveFlow

start() async

shutdown() async

create_agent(agent_id, skills, read_keys, write_keys, task_handler, max_queue_size=None) async

set_strategy(strategy) async

HiveFlow configuration with all tunable parameters.

Configuration categories: - Scheduler: auction threshold, timeout - Blackboard: type, Redis connection, TTL, encryption, max object size - Circuit Breaker: failure threshold, timeout - Worker: queue size - Features: HITL, checkpoint, RAG

validate()

Validate configuration values.

from_env(prefix='HIVEFLOW') classmethod

Create HiveFlowConfig from environment variables.

Environment variables (with HIVEFLOW_ prefix): BLACKBOARD_TYPE: memory, ttl_memory, redis, encrypted (default: ttl_memory) # 🔄 P0 FIX REDIS_URL: Redis connection URL (default: redis://localhost) REDIS_DB: Redis database number (default: 0) REDIS_MAX_CONNECTIONS: Max connection pool size (default: 20) REDIS_SOCKET_TIMEOUT: Socket timeout in seconds (default: 5.0) REDIS_POLL_INTERVAL: Blackboard poll interval in seconds (default: 0.05) PREFIX: Key prefix (default: hiveflow) MAX_AUDIT_ENTRIES: Max audit log entries (default: 1000) MAX_OBJECT_SIZE: Max object size in bytes (default: 10MB) # 🔧 大对象保护 DEFAULT_TTL: Default TTL in seconds (default: 3600.0) # 🔄 P0 FIX WORKER_MAX_QUEUE_SIZE: Max worker queue size (default: 100) ENCRYPT_COMPRESSION: Enable compression for encrypted blackboard (default: false) LOG_LEVEL: Logging level (default: INFO) ENCRYPTION_KEY_SOURCE: env or file (default: env) ENCRYPTION_KEY_ENV_VAR: Env var name for key (default: HIVEFLOW_ENCRYPTION_KEY) ENCRYPTION_KEY_FILE: Path to key file USE_JSON_SCHEMA: Enable JSON schema validation (default: false) TTL_CLEANUP_INTERVAL: TTL cleanup interval in seconds (default: 120.0) # 🔄 P0 FIX

Messaging

Human-in-the-loop

Manages human-in-the-loop gates in workflows.

Usage

mgr = HITLManager()

Create an approval gate

gate = await mgr.create_gate( workflow_id="wf_001", node_id="review_node", action=HITLAction.APPROVAL, prompt="Review the generated report before publishing", context={"report": report_text}, timeout_seconds=600, on_timeout="approve", )

Check if gate is still pending

if gate.status == HITLStatus.PENDING: # Wait for human response response = await mgr.wait_for_response(gate.gate_id)

Human responds (called from UI/API)

await mgr.respond(gate.gate_id, approved=True, comment="Looks good!")

🔧 Distributed Deployment Note: For multi-Pod deployments, asyncio.Lock only protects within a single process. To prevent "ghost approval" across multiple Pods, consider using a distributed lock:

Recommended: Redlock algorithm (redis-py has built-in support)

Example implementation
from redis import Redis
from redis.lock import Lock

class DistributedHITLManager(HITLManager):
    def __init__(self, redis_client: Redis):
        super().__init__()
        self._redis = redis_client

    async def respond(self, gate_id, approved=True, ...):
        # Acquire distributed lock with short TTL
        lock = self._redis.lock(f"hitl:{gate_id}", timeout=5.0)
        if lock.acquire(blocking=False):
            try:
                result = await super().respond(gate_id, approved, ...)
                return result
            finally:
                lock.release()
        else:
            logger.warning(f"Gate {gate_id} is being processed by another Pod")
            return None

This ensures only one Pod can modify a gate's status at any time.

create_gate(workflow_id, node_id, action, prompt, context=None, timeout_seconds=300.0, on_timeout='fail') async

Create a new HITL gate.

respond(gate_id, approved=True, modified_data=None, comment='', input_data=None) async

Record a human response to a gate.

🔄 Ghost Approval Prevention: - Check gate status BEFORE updating - If already in terminal state, return existing gate without modification - Use lock to prevent concurrent status updates

list_pending_gates(workflow_id=None) async

List all pending HITL gates.

Bases: str, Enum

Action type for HITL gate.

Scheduler

Bases: Scheduler

schedule(ecm) async

Schedule a task to an eligible worker.

🔄 P0 FIX: Idempotency - check if intent_id already running before scheduling. 🔄 Metrics Integration: - task_scheduled_total: Counter for successful scheduling - task_schedule_failed_total: Counter for failed scheduling - task_schedule_latency_seconds: Histogram for scheduling latency

Full manual reference

Legacy hand-written tables remain in api-reference.md until all modules are migrated to mkdocstrings.