CoreRasurae
e9247458cc
`file_read` always read from position 0; `max_chars` (ADR-2030 D-3) only bounded where the returned content stopped, so once a large file was truncated there was no way to retrieve the next chunk short of falling back to the `shell` tool (`tail -c +N`, `sed -n`, `dd skip=...`) — the same class of awkward, error-prone detour ADR-2030 D-4 already eliminated for file paths mistaken for shell commands. Adds an optional `offset` character-position argument (default 0, byte-for-byte identical output when omitted) to both the tool schema (`llm_tools._BUILTIN_TOOL_SCHEMAS["file_read"]`) and the implementation (`ToolAgent._file_read_tool`). Combined with `max_chars` it returns the window `[offset, offset + max_chars)`, and the `[FILE_READ_SUCCESS]` header now signals continuation: `MORE_CONTENT_AT_OFFSET: N` when more content remains (N is the exact next offset, so callers never compute `offset + max_chars` themselves), or `NO_MORE_CONTENT_AT_OFFSET: N` when the requested offset is at or beyond end-of-file — a success response with empty content, not an error, since that is the expected terminal state of a correctly-paginating caller. Negative or non-integer offsets raise `ExecutionError`, mirroring the existing `max_chars` validation pattern. See docs/adr/ADR-2033-file-read-offset-pagination.md for the full set of design decisions, including why directory-listing pagination and byte-level seeking are deferred to a future issue. ISSUES CLOSED: #83
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
ReactiveCleverAgentsApporchestrator.
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.