22 Commits

Author	SHA1	Message	Date
CoreRasurae	a8f68b8262	fix(graph): enforce USD budget at each agent invocation with pre-flight gate ... Enforces the USD budget (max_cost_usd) as a hard pre-flight gate before every node execution and at each main-agent ainvoke round inside the multi-turn tool loop, with pruning passes silently skipped when the budget is exhausted. Pre-flight gate (pure_graph.py): _check_budget_pre_flight() raises ExecutionError(kind='cost', reason='budget_exhausted') immediately before node execution in both _execute_from_node and all three branches of _stream_from_node. In-node budget gating (llm.py): _check_budget_before_invoke() gates every _retry_ainvoke() call inside _execute_tool_loop, process_message, and stream_message. _should_skip_pruning() skips pruning passes when budget exhausted. _accumulate_cost_after_invoke() computes USD cost from token counts using the pricing table and advances current_accumulated_cost so subsequent budget checks see the updated cost. ContextVar plumbing (retry.py, pure_graph.py): current_accumulated_cost, current_max_cost_usd, and current_pricing ContextVars carry per-node budget state from PureLangGraph into LLMAgent. Set before node.execute() via _set_budget_context_for_node, reset in finally blocks via _reset_budget_context. Reviewer fixes (rui.hu #80): - Move cost accumulation inside try block in terminal streaming branch to prevent ContextVar leak (was set after finally reset). - Standardize log precision to $%.6f across all budget messages. - Remove orphaned 'already exhausted' step (criterion unreachable). - Add dedicated streaming budget enforcement scenario. - Remove redundant = None default on _reset_budget_context pricing_token. ISSUES CLOSED: #76	2026-07-12 19:51:39 +01:00
CoreRasurae	964e87cc0f	feat(tool-loop): add token-budget awareness and tool output pruning ... Implement token-budget awareness (§4.4.7) and tool output pruning (§4.4.8-9) for the multi-turn tool-call loop to prevent context-window exhaustion. Token budget: tracks estimated token count before each ainvoke(), emits warning at 75% budget, injects synthesis prompt at exhaustion with one final tool-call round. Estimation via chat_model.get_num_tokens() with len(content)//4 heuristic fallback. Config key: token_budget_percent. Tool output pruning: implicit LLM extraction pass scoped to file_read calls. Schema augmentation injects output_prune (bool) and output_prune_context (string) meta-arguments. Pruning model responds with [PRUNE_INFO_START/END] and [PRUNE_OUTPUT_START/END] markers. Config keys: allow_tool_output_pruning, pruning_model. - Capture output_prune value in budget synthesis flow with proper guard - Fix ADR D-4: synthesis prompt is HumanMessage not SystemMessage - Fix Robot tests: replace /dev/null with temp file path ADR-2031 documents all specification extensions. 21 new BDD scenarios, 5 Robot integration tests, 16 ASV benchmarks. ISSUES CLOSED: #61	2026-06-26 18:21:14 +01:00
CoreRasurae	517dfb4cce	feat(registry): implement local namespace reference resolution ... Implements the local:<path> reference scheme per Package Registry Standard v1.0.0 §5.3. Closes #46	2026-06-12 17:11:35 +01:00
CoreRasurae	054b432197	feat(registry): implement RegistryCache with LRU eviction and TTL ... - Add RegistryCache with LRU eviction, TTL expiry, SHA-1 content validation - Add CacheFactory for centralised cache configuration (Factory Method pattern) - Add CacheStats dataclass for hit/miss/eviction observability - Implement singleflight coalescing for concurrent-miss protection - Use tuple keys for resolve store to prevent separator collision - Fix cancellation-safe singleflight via plain Future + asyncio.shield - Independent max_size budgets per store (content + resolve) - Concurrent test assertions strengthened - All test imports moved to module level per CONTRIBUTING.md - Unused dead code removed from tests ISSUES CLOSED: #28	2026-06-11 19:26:04 +01:00
hurui200320	2664ebfd75	feat(ActorResult): implement ActorResult and NodeUsage types; capture per-node token counts from LangChain responses ... AC1: Move NodeUsage and ActorResult from runtime.py into the spec-mandated cleveractors/result.py module. runtime.py now imports and re-exports both types for backward compatibility. result.py defines __all__, uses dict[str, Any] | None (PEP 585) for the state field, and makes nodes a required positional field (no default) so the contract that nodes is always non-empty is statically enforced. AC2: LLMAgent.process_message() extracts real token usage from response.usage_metadata (primary) with isinstance(dict) guard, falling back to response.response_metadata['token_usage'] with its own isinstance(dict) guard. If neither is available, logs a WARNING with a cause parameter that distinguishes the three failure conditions (empty usage_metadata, missing response_metadata, or missing token_usage key) so operators can triage billing discrepancies. Non-numeric token values are coerced via _safe_int() with fallback to 0 and a warning log. AC3: Token counts are available alongside the response string via the side-channel attribute LLMAgent._last_token_usage, keeping process_message() return type as str (preserving the Agent base-class contract unchanged). AC4: Node._execute_agent() reads _last_token_usage, provider, and model from any LLMAgent after execution and includes a _node_token_usage dict in the state-updates return. PureLangGraph._node_usages accumulates one (node_id, provider, model, prompt_tokens, completion_tokens) 5-tuple per LLM node invocation during _execute_from_node(). PureLangGraph.execute() now returns a 3-tuple: (response, final_state, node_usages). process_message() unpacks and discards the extra elements. AC5: Executor._execute_graph() uses the node_usages list from execute() to build NodeUsage objects. Executor._execute_llm() reads _last_token_usage directly from the LLMAgent instance instead of calling _estimate_tokens(). State isolation verified by a new test that calls execute() twice on the same Executor with different mocked token counts and asserts independent results. AC6: Aggregation invariant enforced in both _execute_llm() and _execute_graph() via sum() over nodes list. AC7: ActorResult and NodeUsage re-exported from cleveractors/__init__.py via cleveractors.result (path updated from cleveractors.runtime). Cleanup: Delete runtime_tokens.py (estimate_tokens, estimate_graph_tokens) and the private _estimate_tokens() function in runtime.py — both are superseded by real LangChain usage_metadata extraction. Remove unused import logging and logger = logging.getLogger(__name__) from runtime.py (dead code after dispatch logic was moved to runtime_dispatch.py). Move NodeUsageTuple type alias in pure_graph.py to after the import blocks. Use tuple unpacking for last_usage in runtime_dispatch._execute_llm(). New/updated BDD tests (actor_result_token_counting.feature, 25 scenarios): - AC2: usage_metadata primary path (input_tokens/output_tokens) - AC2: truthy non-dict usage_metadata treated as absent (isinstance guard) - AC2: truthy non-dict response_metadata treated as absent (isinstance guard) - AC2: response_metadata={} (empty dict) logs warning, counts 0 - AC2: response_metadata fallback path (prompt_tokens/completion_tokens) - AC2: no usage data -> warning logged, counts 0 - AC2: response_metadata attribute present but None - AC2: stale token reset before each call - AC5: state isolation — execute() twice produces independent results - AC6: aggregation invariant for single-node and multi-node actors - AC6: placeholder node_id exact format assertion for _execute_graph - AC6: placeholder node_id exact format assertion for _execute_multi_actor - AC7: import correctness from cleveractors and cleveractors.result CHANGELOG.md updated with Changed (real token extraction, result module move) and Removed (runtime_tokens.py) entries under [Unreleased]. Quality gates: lint pass, typecheck 0 errors, unit_tests 2157/2157, integration_tests 86/86, coverage 97.2% (threshold 97%). ISSUES CLOSED: #14	2026-06-11 03:05:20 +00:00
hurui200320	76c4c74201	feat(create_executor): implement create_executor() factory and Executor.execute() returning ActorResult ... - **`src/cleveractors/runtime_types.py`** — `ActorResult` and `NodeUsage` dataclasses extracted to break circular imports (CONTRIBUTING.md §Import Guidelines). 100% coverage. - **`src/cleveractors/runtime.py`** — `create_executor()` factory, `Executor` class with `execute()` dispatching to module-level functions in `runtime_dispatch`. Imports `_execute_*` at module level (no function-local imports). 100% coverage. - **`src/cleveractors/runtime_dispatch.py`** — Four dispatch functions: `_execute_llm`, `_execute_graph`, `_execute_tool`, `_execute_multi_actor`. All imports at module level except `from cleveractors.runtime import Executor` inside `_execute_multi_actor` (the only remaining circular dep — Executor calls _execute_multi_actor which creates a new Executor; cannot be resolved without further restructuring). 99.69% coverage (only the `if TYPE_CHECKING:` guard line is uncovered — not a real gap). - **`src/cleveractors/runtime_tokens.py`** — Token estimation via tiktoken with heuristic fallback. 100% coverage. Key design decisions and fixes: - **Circular import resolution**: `ActorResult`/`NodeUsage` moved to `runtime_types.py`; both `runtime.py` and `runtime_dispatch.py` import from it at module level. - **`messages` forwarded to `_execute_llm`**: builds `context={"conversation_history":[...]}` passed to `LLMAgent.process_message` for multi-turn support. - **`parallel_execution` aligned with `PureGraphConfig` default (True)**: reads from legacy `route` dict or v2.0 `routes.main` dict; defaults to True. - **Factory normalization**: always merges `actors` into `agents` (actors take precedence) so configs using both keys work correctly. - **Generic exception in agent creation re-raised as `ConfigurationError`**: no double-logging; exception message preserved in `ConfigurationError`. - **`cleveragents_block` guarded against `None`**: uses `or {}` coercion. - **Type annotations added**: `top_provider`, `top_model`, `top_sp`, `temperature_raw`, `max_tokens_raw`, `config_block`, `tools` in dispatch functions. - **No `finally` in `_execute_tool`**: documented with comment (ToolAgent has no cleanup). - **Dead step removed**: `step_rxe_invalid_node_type` was unreferenced and incorrect. - **BDD coverage**: `parallel_execution=False` override verified via `PureGraphConfig` constructor args; conversation history forwarding verified; AC7 immutability for multi-actor path verified. - ✅ `nox -e lint` — passes - ✅ `nox -e format` — passes - ✅ `nox -e typecheck` — passes (0 errors, 1 expected warning) - ✅ `nox -e unit_tests` — 2113 scenarios pass, 0 failures, 0 skipped - ✅ `nox -e integration_tests` — 76 tests pass - ✅ `nox -e coverage_report` — 97.21% (9870 covered, 283 missing, 10153 total) PR-modified files: `runtime_types.py` 100%, `runtime.py` 100%, `runtime_dispatch.py` 99.69% (1 uncoverable TYPE_CHECKING guard), `runtime_tokens.py` 100% ISSUES CLOSED: #13	2026-06-10 09:41:39 +00:00
hurui200320	f281fa3b24	feat(credentials): refactor LLMAgent/AgentFactory for per-request credential injection and extended provider routing ... Implements Wave 3 of the cleveractors-core integration (ADR-2026, ADR-2028). ## AgentFactory - Added optional credentials: dict[str, dict[str, str]] | None parameter to __init__. Stored as self.credentials. - When creating LLMAgent instances, the full credentials dict is forwarded via a new credentials constructor kwarg, threading per-request API keys without touching the stored actor config_dict. - Added explicit type annotation ReactiveAgentFactory: type[AgentFactory]. - _create_agent_instance raises ConfigurationError when credentials is not None but does not contain an entry for the requested provider (AC4 compliance). ## LLMAgent - Added optional credentials: dict[str, str] | None parameter to __init__. Stored as self._credentials; config_dict is never modified. - LangChain client construction deferred to first access (lazy init) via a chat_model property backed by _ensure_chat_model(). The property setter allows test-injection of mock models without going through the lazy-init path. - _create_chat_model() dispatches to credential-injection / standalone paths. - Extracted to llm_client.py and llm_providers.py for modularity. - Defined shared module-level constants DEFAULT_MODEL, DEFAULT_TEMPERATURE, DEFAULT_MAX_TOKENS to eliminate duplicated magic numbers across llm.py, runtime.py, and factory.py. - Added public credentials property exposing self._credentials. - Added type narrowing guard in chat_model property to satisfy static analysis. - Added temperature_override type validation in process_message. - Guarded cleanup() null-assignment with _chat_model_lock (TOCTOU fix). ## SSRF Prevention (ADR-2028) - _validate_base_url(): https-only, userinfo rejection, localhost rejection, raw IP literal rejection, numeric-hostname (dotted-hex/octal/compact) rejection, percent-decode loop with iteration cap (10), trailing-dot FQDN strip. - DNS resolution intentionally omitted (blocking call in async path). - Canonical URL reconstruction uses lowercased scheme. ## Credential Leak Prevention - All logger.exception(...) replaced with logger.debug(..., exc_info=True). - Error messages use type(e).__name__ instead of str(e). - process_message exception chains broken with from None to prevent LangChain authentication errors from leaking via __cause__. ## Runtime fixes - Executor._execute_llm: shallow copy for setdefault mutations. - Executor._execute_graph: restructured try/finally for resource cleanup. - Uses DEFAULT_MODEL, DEFAULT_TEMPERATURE, DEFAULT_MAX_TOKENS from llm.py. - Defensive copy of credentials dict in Executor.__init__ to prevent caller mutation after construction. ## Test improvements - Added BDD scenarios for llm_imports.py ImportError fallback branches using sys.modules manipulation with a custom import hook, exercised via subprocess. - Added BDD scenario for AgentFactory.create_agents_from_config() credential threading to all created agents. - Removed tautological dataclass test scenarios (NodeUsage, ActorResult) from runtime_coverage.feature. - Fixed misleading scenario title in runtime_coverage.feature (exception chain suppressed, not chained) and updated step to assert __cause__ is None. - Added CHANGELOG entry for ReactiveAgentFactory backward-compatibility alias. - Removed duplicate log emission in _check_known_provider_domain. ISSUES CLOSED: #12	2026-06-08 11:10:46 +00:00
hurui200320	149feae15f	feat(validate_dict): expose public validate_dict(config_dict, platform_limits) API ... Implement validate_dict() in cleveractors/validation.py and export it from cleveractors/__init__.py as the first router-facing API (ADR-2024, Wave 1). validate_dict(config_dict, platform_limits) -> dict[str, Any]: - Validates that both 'agents' and 'routes' top-level keys are present. - Validates each agent's type against the spec-defined vocabulary: {llm, tool, composite, chain, template_instance}. - Validates LLM agent 'provider' values against platform_limits['allowed_providers'] when present, or the default allowlist {openai, anthropic, google} when absent. - Validates route/edge field names: 'from'/'to' are rejected in favour of 'source'/'target' as required by the spec-conformant format (ADR-2025). - Validates graph node types against the spec vocabulary: {start, end, agent, function, tool, conditional, subgraph, message_router}. - Validates stream operator types against the spec vocabulary (all defined types). - Enforces structural platform limits from platform_limits when present: max_graph_depth (DFS longest-path check), max_subgraph_depth (recursive subgraph-reference depth), max_total_nodes (total nodes across all graph routes). - Returns config_dict unchanged when all checks pass (identity contract). - Pure static validator: no file I/O, no env-var reads, no app construction. Review fixes (Cycle 1): - M3: Added isinstance(node_name, str) guard for graph node keys in _validate_graph_route, with BDD scenario for non-string node key. - m1: Added # pragma: no branch to _count_total_nodes defensive guard in _limits.py (matching the identical guards in _subgraph_children). - m2: Added # pragma: no branch to dead defensive continue branches in _validate_graph_route edge validation loop. - m3: Added dedicated BDD scenario and step for dangling source node (src not in nodes_raw branch), plus renamed existing scenario from "source node" to "target node" for accuracy. - m4: Deleted 4 lines of commented-out InlineYAMLJinja setup code in features/environment.py. - n1: Added depth <= 0 ValueError guard in build_subgraph_chain helper. - n2: Renamed scenario "Edge referencing a non-existent source node" to "Edge referencing a non-existent target node" (the step tested a target). - n3: Changed > to >= in both _MAX_DFS_STEPS and _MAX_SUBGRAPH_STEPS guards to prevent off-by-one allowing one extra iteration beyond documented ceiling. - n4: Added adjacency target deduplication in _compute_graph_depth to avoid wasting DFS step budget on parallel edges. - Spec review: M1 (entry_point optional) and M2 (start/end implicit injection) were verified against the authoritative spec at docs/specification.md in the cleveragents-webapp repo (develop branch). The spec does NOT support either claim; entry_point is required and start/end must be explicitly declared. No changes needed for M1/M2. Review fixes (Cycle 2): - M1: Deduplicated _subgraph_children yields with a seen set to prevent duplicate subgraph references from consuming DFS steps redundantly and causing false "too complex" errors. - M2: Changed adjacency value type from list[str] to set[str] in _compute_graph_depth for O(1) deduplication, reducing worst case from O(N^3) to O(N^2) for dense graphs. - m1: Added BDD scenario for LLM agent without provider field failing when default "openai" is not in custom allowlist. - m2: Added positive BDD scenarios for valid node types start, tool, conditional, message_router, function. - m3: Added positive BDD scenarios for additional stream operator types filter, transform, reduce. - m5: Added depth_cache memoization to _compute_subgraph_depth to avoid recomputing depths across graph routes sharing subgraph trees. - m6: Moved cleveractors.validation._limits import from module level into after_scenario, guarded by hasattr. - n1: Split validate_dict_routes_steps.py (was 473 lines) into validate_dict_routes_steps.py (generic route steps) and validate_dict_graph_route_steps.py (graph-specific steps). - n2: Updated _MAX_DFS_STEPS module comment to accurately state O(N+E) complexity and that dense graphs can exhaust the ceiling quickly. BDD Behave scenarios cover all requirements. Robot Framework integration tests (robot/validate_dict.robot) cover API usage. ISSUES CLOSED: #10	2026-06-05 09:23:44 +00:00
CoreRasurae	9753b31c7e	test: add coverage gap tests improving coverage from 81.4% to 96.90% ... Add 13 BDD scenarios covering previously uncovered code paths: - SAFE_BUILTINS validation (sandbox.py: 0% → 100%) - ConfigurationError re-raise path (config.py: 99.3% → 100%) - CLI hello/main functions (cli.py: 72.7% → 90.9%) - GraphState message truncation (state.py: 98.7% → 100%) - ProgressBarManager update/context rendering (progress.py: 0% → 87.7%) - MessageRouter regex/exact/contains routing (message_router.py: 0% → 59.4%) - RoutingAdapter parse_routing_command (routing_adapter.py) - DynamicRouterNode pattern-based routing (dynamic_router.py) - EnhancedTemplateRegistry unknown template type (enhanced_registry.py: 99.2%) - CompositeAgent null-graph error path (composite.py: 97.8% → 98.6%) Cover routing_adapter.py (17% → 100%): all GOTO/ROUTE patterns, create_routing_node, create_conditional_router, dynamic config conversion. Cover dynamic_router.py (21% → 87%): execute with empty/dict/string messages, extract_message with colon parsing, config creation, graph extension with edge generation. Cover message_router.py (59% → 78%): regex, exact, contains, prefix, suffix match types, invalid regex handling, non-string message, set_state. Exercise Node._prepare_conversation_history with invalid configs, _runtime error paths, _execute_message_router with rules, _execute_agent with current_message and metadata propagation, _execute_function with dynamic_router, and _execute_conditional with content_contains/content_not_contains/content_starts_with and custom condition types. Improves nodes.py from 71.3% to 72.5%. Exercise PureGraphConfig, PureLangGraph init with dict/config, RxPyLangGraphBridge registration/connection/lookup, ReactiveStreamRouter operator creation and condition functions, ReactiveConfigParser config/route/graph parsing, ToolAgent tool execution with JSON, space-separated, single, file_read, progress_bar invocations, and ReactiveCleverAgentsApp init/dispose/visualization.	2026-06-02 20:02:01 +01:00
CleverThis Engineering	5bbda89386	style: fix all lint errors across source and test files ... - Fix bare excepts (replace with except Exception:) - Remove wildcard star imports from test step files - Add explicit imports for ConfigurationError, AgentCreationError - Add 'from err' to raise statements in except blocks - Fix loop variable binding with default arguments (B023) - Organize imports, fix trailing whitespace and blank line whitespace - Bump Python to 3.13 and update tool configurations	2026-05-26 22:21:50 +00:00
CleverThis Engineering	2223a16d48	feat: Minor code changes and linting and formatting issues fixes	2026-05-26 21:53:20 +00:00
CleverThis Engineering	9a9aa04745	Fixed linting and typechecking, tox fully works now	2026-05-26 21:53:19 +00:00
CleverThis Engineering	57254f57e5	fix: Fixed many of the remaining issues and got a mostly working integration test for scientific paper writer	2026-05-26 21:53:19 +00:00
CleverThis Engineering	82ea476c5f	feat: Added context tracking when using via run, and added context command for managing it	2026-05-26 21:53:18 +00:00
CleverThis Engineering	4d51ad1c3b	test: update bdd test cases; docs: update readme and yaml syntax docs	2026-05-26 21:53:18 +00:00
CleverThis Engineering	c44ef374de	Fixed error thrown after unit tests complete	2026-05-26 21:53:17 +00:00
CleverThis Engineering	32b3c7f9ce	Fixed all unit tests and static checks, tox now passes fully.	2026-05-26 21:53:17 +00:00
CleverThis Engineering	fb921f64d5	perf: Speeding uo tests	2026-05-26 21:53:17 +00:00
CleverThis Engineering	c5c5765677	test: added new tests to improve coverage.	2026-05-26 21:53:17 +00:00
CleverThis Engineering	f79ab8223e	Converted code to use RxPy for its routes	2026-05-26 21:53:16 +00:00
CleverThis Engineering	6a88e7e24a	feat: add support for custom code tools and enhance error handling	2026-05-26 21:53:16 +00:00
CleverThis Engineering	7e6e5dc001	refactor: improve config management and add comprehensive tests	2026-05-26 21:53:16 +00:00