cleveractors-core/README.md

CleverActors

CleverActors is the reactive agent framework used by CleverAgents and CleverRouter.

It provides a Python library that lets a host application:

• Parse CleverAgents v2 YAML configuration files (with Jinja2 templates and ${ENV_VAR} interpolation).
• Validate configuration against the built-in schema validator.
• Create reactive agent networks with RxPy streams, LangGraph graphs, or hybrid pipelines of both.
• Run single-shot prompts, interactive CLI sessions, or stream-based processing via the ReactiveCleverAgentsApp orchestrator.

Install

pip install "cleveractors @ git+https://git.cleverthis.com/cleverlibre/cleveractors@master"

Quick start

from cleveractors import ReactiveCleverAgentsApp

app = ReactiveCleverAgentsApp(config_files=["config.yaml"])
result = await app.run_single_shot("Hello, agents!")
print(result)

Using agents directly

from cleveractors import Agent
from cleveractors.agents.llm import LLMAgent

agent = LLMAgent(
    name="assistant",
    config={"provider": "openai", "model": "gpt-4o", "system_prompt": "Be helpful."},
)
response = await agent.process_message("What is 2+2?")
print(response)

LangGraph workflows

from cleveractors.langgraph import LangGraph, Node, NodeType, GraphState

graph = LangGraph(name="my_workflow", config={})
graph.add_node(Node(name="start", node_type=NodeType.AGENT, agent="assistant"))
graph.add_node(Node(name="end", node_type=NodeType.END))
graph.add_edge("start", "end")
result = await graph.execute({"message": "Hello"})

Reactive stream routing

from cleveractors.reactive.stream_router import ReactiveStreamRouter, StreamType

router = ReactiveStreamRouter()
stream = router.create_stream({"name": "pipeline", "type": StreamType.HOT})
router.send_message("pipeline", "Process this message")

Package structure

Module	Purpose
cleveractors	Top-level exports: Agent, ContextManager, ReactiveCleverAgentsApp, CleverAgentsException
cleveractors.agents	Agent implementations: LLMAgent, ToolAgent, CompositeAgent, ChainAgent, AgentFactory
cleveractors.core	Core framework: ReactiveCleverAgentsApp, ConfigurationManager, ProgressBarManager, exceptions
cleveractors.langgraph	LangGraph integration: LangGraph, PureLangGraph, Node, GraphState, StateManager, RxPyLangGraphBridge
cleveractors.reactive	RxPy streams: ReactiveStreamRouter, StreamMessage, RouteConfig, ReactiveConfigParser
cleveractors.templates	Jinja2+YAML template system: BaseTemplate, TemplateRegistry, AgentTemplate, GraphTemplate, StreamTemplate

Key exports

from cleveractors import Agent, ContextManager, ReactiveCleverAgentsApp, CleverAgentsException
from cleveractors.core.exceptions import ConfigurationError, TemplateError, RoutingError, ExecutionError
from cleveractors.core.config import ConfigurationManager
from cleveractors.agents.factory import AgentFactory
from cleveractors.langgraph import LangGraph, Node, NodeType, GraphState, StateManager
from cleveractors.langgraph.pure_graph import PureLangGraph, create_pure_langgraph
from cleveractors.reactive.stream_router import ReactiveStreamRouter, StreamType, StreamMessage
from cleveractors.templates import BaseTemplate, TemplateType, TemplateParameter, TemplateRegistry

License

MIT — see LICENSE.

See also CleverAgents Operations Code (CONTRIBUTING) for commit, PR, and testing conventions.