API Reference (auto-generated)¶
Reference for selected public symbols in the hiveflow package. For tutorials see Getting Started.
Core engine¶
hiveflow.HiveFlow
¶
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.
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.