scienceflow 0.2.0b3__py3-none-any.whl

scienceflow/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (C) 2026. Huawei Technologies Co., Ltd. All rights reserved.
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the MIT license.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE. See the MIT License for more details.
+#
+# The name of Huawei and the contributors may not be used to endorse or promote
+# products derived from this software without specific prior written permission.
+
+"""ScienceFlow scientific-agent package."""

scienceflow/agent/__init__.py

@@ -0,0 +1,120 @@
+"""Lazy public surface for ScienceFlow's domain-specific agent extensions."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_EXPORTS = {
+    "AgentCallbackPorts": ("scienceflow.agent.core.ports.callback_ports", "AgentCallbackPorts"),
+    "ScienceAgent": ("scienceflow.agent.core.runtime.agent", "ScienceAgent"),
+    "_DEFAULT_SYSTEM": ("scienceflow.agent.prompts.system_prompt", "_DEFAULT_SYSTEM"),
+    "_default_system_prompt": (
+        "scienceflow.agent.prompts.system_prompt",
+        "_default_system_prompt",
+    ),
+    "_extract_python_code_from_assistant_text": (
+        "scienceflow.agent.prompts.write_coaching",
+        "_extract_python_code_from_assistant_text",
+    ),
+    "_bash_command_parallel_safe": (
+        "scienceflow.runtime.safety.policy.agent_policies.bash_utils",
+        "_bash_command_parallel_safe",
+    ),
+    "_embedded_failure_user_message": (
+        "scienceflow.runtime.safety.policy.agent_policies.bash_utils",
+        "_embedded_failure_user_message",
+    ),
+    "_looks_like_quick_test_solution_run": (
+        "scienceflow.runtime.safety.policy.agent_policies.bash_utils",
+        "_looks_like_quick_test_solution_run",
+    ),
+    "_looks_like_write_placeholder_mimicry": (
+        "scienceflow.runtime.safety.policy.agent_policies.bash_utils",
+        "_looks_like_write_placeholder_mimicry",
+    ),
+    "_WS_LOG_RECOVERY_CAP": (
+        "scienceflow.foundation.config.runtime.agent_constants",
+        "_WS_LOG_RECOVERY_CAP",
+    ),
+    "_WS_LOG_USER_CAP": ("scienceflow.foundation.config.runtime.agent_constants", "_WS_LOG_USER_CAP"),
+    "_WS_LOG_BODY_CAP": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "_WS_LOG_BODY_CAP",
+    ),
+    "_WS_LOG_MAX_LINES": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "_WS_LOG_MAX_LINES",
+    ),
+    "_WS_LOG_TOOL_CALL_SINGLE_CAP": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "_WS_LOG_TOOL_CALL_SINGLE_CAP",
+    ),
+    "_WS_LOG_TOOL_RESULT_CAP": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "_WS_LOG_TOOL_RESULT_CAP",
+    ),
+    "format_tool_call_lines_for_interaction_log": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "format_tool_call_lines_for_interaction_log",
+    ),
+    "format_tool_result_for_interaction_log": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "format_tool_result_for_interaction_log",
+    ),
+    "tool_result_text_for_interaction_log": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "tool_result_text_for_interaction_log",
+    ),
+    "truncate_for_interaction_log": (
+        "scienceflow.runtime.observability.agent_io.interaction_log",
+        "truncate_for_interaction_log",
+    ),
+    "InteractionLogPolicy": (
+        "scienceflow.runtime.observability.agent_io.interaction_log_policy",
+        "InteractionLogPolicy",
+    ),
+    "resolve_interaction_log_policy": (
+        "scienceflow.runtime.observability.agent_io.interaction_log_policy",
+        "resolve_interaction_log_policy",
+    ),
+    "_compress_tool_call_for_memory": (
+        "scienceflow.research.state.knowledge.memory.agent.memory_utils",
+        "_compress_tool_call_for_memory",
+    ),
+    "_tool_call_args_from_tc": (
+        "scienceflow.research.state.knowledge.memory.agent.memory_utils",
+        "_tool_call_args_from_tc",
+    ),
+    "inject_thought_into_tool_params": (
+        "scienceflow.research.state.knowledge.memory.agent.memory_utils",
+        "inject_thought_into_tool_params",
+    ),
+    "create_tool_collection": (
+        "scienceflow.runtime.safety.execution.agent_runtime.tool_composition",
+        "create_tool_collection",
+    ),
+    "clear_embedded_full_run_result": (
+        "scienceflow.runtime.safety.policy.execution_policy",
+        "clear_embedded_full_run_result",
+    ),
+    "ensure_full_execution": (
+        "scienceflow.runtime.safety.policy.execution_policy",
+        "ensure_full_execution",
+    ),
+    "write_embedded_full_run_result": (
+        "scienceflow.runtime.safety.policy.execution_policy",
+        "write_embedded_full_run_result",
+    ),
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _EXPORTS:
+        raise AttributeError(name)
+    module_name, attribute = _EXPORTS[name]
+    value = getattr(import_module(module_name), attribute)
+    globals()[name] = value
+    return value

scienceflow/agent/core/__init__.py

@@ -0,0 +1 @@
+"""Core agent runtime and port contracts."""

scienceflow/agent/core/ports/__init__.py

@@ -0,0 +1 @@
+"""Agent host and callback ports."""

scienceflow/agent/core/ports/callback_ports.py

@@ -0,0 +1,129 @@
+# Copyright (C) 2026. Huawei Technologies Co., Ltd. All rights reserved.
+
+"""Typed callback capabilities injected at the ScienceAgent composition edge."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any, Protocol
+
+
+class CandidateArchivePort(Protocol):
+    def __call__(
+        self,
+        *,
+        agent: Any,
+        tool_name: str,
+        args: dict[str, Any],
+        tool_result: Any,
+    ) -> Any: ...
+
+
+class StageCapturePort(Protocol):
+    def __call__(
+        self,
+        *,
+        agent: Any,
+        args: dict[str, Any],
+        tool_result: Any,
+    ) -> Any: ...
+
+
+class MetricInterpretationPort(Protocol):
+    def __call__(
+        self,
+        *,
+        agent: Any,
+        stdout: str,
+        script_label: str,
+    ) -> Any: ...
+
+
+class TextOnlyDecisionPort(Protocol):
+    def __call__(
+        self,
+        *,
+        agent: Any,
+        assistant_text: str,
+        round_idx: int,
+        max_steps: int,
+    ) -> Any: ...
+
+
+class ContextLimitEstraPort(Protocol):
+    def __call__(
+        self,
+        *,
+        agent: Any,
+        round_idx: int,
+        max_steps: int,
+        omitted: int,
+    ) -> Any: ...
+
+
+class ContextCompactObserver(Protocol):
+    def __call__(self, *, phase: str, **payload: Any) -> Any: ...
+
+
+@dataclass(frozen=True, slots=True)
+class AgentCallbackPorts:
+    """Narrow callback capabilities; absent capabilities are explicitly ``None``."""
+
+    candidate_archive: CandidateArchivePort | None = None
+    stage_capture: StageCapturePort | None = None
+    metric_interpretation: MetricInterpretationPort | None = None
+    text_only_decision: TextOnlyDecisionPort | None = None
+    context_limit_estra: ContextLimitEstraPort | None = None
+    context_compact_observer: ContextCompactObserver | None = None
+
+    def with_overrides(self, **updates: Any) -> AgentCallbackPorts:
+        return replace(self, **updates)
+
+
+_LEGACY_CALLBACK_ATTRIBUTES = {
+    "candidate_archive": "_lnr_candidate_archive_callback",
+    "stage_capture": "_lnr_stage_capture_callback",
+    "metric_interpretation": "_lnr_metric_output_interpretation_callback",
+    "text_only_decision": "_lnr_text_only_callback",
+    "context_limit_estra": "_context_limit_estra_callback",
+    "context_compact_observer": "_context_compact_event_callback",
+}
+
+
+def callback_ports_for(agent: Any) -> AgentCallbackPorts:
+    ports = getattr(agent, "callback_ports", None)
+    return ports if isinstance(ports, AgentCallbackPorts) else AgentCallbackPorts()
+
+
+def install_callback_ports(agent: Any, ports: AgentCallbackPorts) -> None:
+    installer = getattr(agent, "configure_callback_ports", None)
+    if callable(installer):
+        installer(ports)
+        return
+    agent.callback_ports = ports
+
+
+def resolve_agent_callback(agent: Any, capability: str) -> Any | None:
+    """Resolve a typed port, with a read-only legacy fallback during migration."""
+
+    ports = callback_ports_for(agent)
+    callback = getattr(ports, capability)
+    if callable(callback):
+        return callback
+    legacy_name = _LEGACY_CALLBACK_ATTRIBUTES[capability]
+    legacy_callback = getattr(agent, legacy_name, None)
+    return legacy_callback if callable(legacy_callback) else None
+
+
+__all__ = [
+    "AgentCallbackPorts",
+    "CandidateArchivePort",
+    "ContextCompactObserver",
+    "ContextLimitEstraPort",
+    "MetricInterpretationPort",
+    "StageCapturePort",
+    "TextOnlyDecisionPort",
+    "callback_ports_for",
+    "install_callback_ports",
+    "resolve_agent_callback",
+]

scienceflow/agent/core/ports/host_ports.py

@@ -0,0 +1,126 @@
+"""Typed capabilities consumed by the ScienceFlow agent session."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import partial
+from typing import Any, Awaitable, Callable, Protocol
+
+from inquirycraft.tools import ToolResult
+
+from scienceflow.agent.policies import routing
+from scienceflow.agent.prompts import system_prompt
+from scienceflow.research.control import agent_runtime_state
+from scienceflow.runtime.observability import agent_tool_feedback
+from scienceflow.research.quality import embedded_fullrun
+from scienceflow.runtime.safety.execution.agent_runtime import edit_guard
+from scienceflow.runtime.safety.execution.agent_runtime.tool_bundle_policy import (
+    normalize_tool_calls_for_execution,
+)
+from scienceflow.research.solver.lnr.orchestration import agent_hooks
+from scienceflow.research.state.workspace.adapters import path_hygiene
+
+
+class PrepareToolFeedbackPort(Protocol):
+    def __call__(
+        self,
+        tool_name: str,
+        args: dict[str, Any],
+        tool_result: ToolResult,
+        *,
+        guard_coaching: str = "",
+    ) -> str: ...
+
+
+WorkspaceCheckpointPort = Callable[[str, ToolResult], None]
+NormalizeToolInputPort = Callable[[str, dict[str, Any]], dict[str, Any]]
+RewriteToolResultPort = Callable[[ToolResult], ToolResult]
+ExecuteToolPort = Callable[[str, dict[str, Any]], Awaitable[ToolResult]]
+RecordReadPort = Callable[[str], None]
+RoundIndexPort = Callable[[int], None]
+RoundCompletePort = Callable[[list[str] | None], None]
+NoArgumentPort = Callable[[], None]
+BuildSystemMessagesPort = Callable[[], list[Any]]
+ToolChoicePort = Callable[[int, str | None], str]
+NormalizeCallsPort = Callable[[list[Any]], Any]
+EmbeddedToolResultPort = Callable[[dict[str, Any], ToolResult], Awaitable[Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentHostPorts:
+    """Narrow, explicit host capabilities used by the IQ runtime adapter."""
+
+    workspace_checkpoint: WorkspaceCheckpointPort
+    normalize_tool_input_paths: NormalizeToolInputPort
+    rewrite_tool_result_paths: RewriteToolResultPort
+    execute_tool_with_edit_guard: ExecuteToolPort
+    record_read_for_edit_guard: RecordReadPort
+    prepare_tool_feedback_for_memory: PrepareToolFeedbackPort
+    log_iteration_header: RoundIndexPort
+    pop_and_log_thought: Callable[[dict[str, Any]], None]
+    fresh_workspace_hint: RoundIndexPort
+    periodic_round_injection: RoundIndexPort
+    round_complete: RoundCompletePort
+    sync_resource_state_summary: NoArgumentPort
+    write_productivity_snapshot: NoArgumentPort
+    build_system_messages: BuildSystemMessagesPort
+    tool_choice_for_main_loop: ToolChoicePort
+    normalize_repl_file_change_calls: NormalizeCallsPort
+    normalize_tool_calls: NormalizeCallsPort
+    maybe_write_bare_run_tail_snapshot: EmbeddedToolResultPort
+    maybe_embedded_full_run_after_quick_test: EmbeddedToolResultPort
+
+
+def compose_agent_host_ports(host: Any) -> AgentHostPorts:
+    """Bind real domain owners once at the ScienceAgent composition boundary."""
+
+    return AgentHostPorts(
+        workspace_checkpoint=partial(
+            path_hygiene._maybe_workspace_git_auto_checkpoint, host
+        ),
+        normalize_tool_input_paths=partial(
+            path_hygiene._maybe_normalize_tool_input_paths, host
+        ),
+        rewrite_tool_result_paths=partial(
+            path_hygiene._maybe_rewrite_tool_result_paths, host
+        ),
+        execute_tool_with_edit_guard=partial(
+            edit_guard._execute_tool_maybe_edit_guard, host
+        ),
+        record_read_for_edit_guard=partial(
+            edit_guard._record_read_for_edit_guard, host
+        ),
+        prepare_tool_feedback_for_memory=partial(
+            agent_tool_feedback._prepare_tool_feedback_for_memory, host
+        ),
+        log_iteration_header=partial(agent_tool_feedback._log_iteration_header, host),
+        pop_and_log_thought=partial(agent_tool_feedback._pop_and_log_thought, host),
+        fresh_workspace_hint=partial(
+            agent_hooks._lnr_maybe_fresh_workspace_hint_first_round, host
+        ),
+        periodic_round_injection=partial(
+            agent_hooks._lnr_maybe_periodic_inject_at_round_start, host
+        ),
+        round_complete=partial(agent_hooks._lnr_on_round_complete, host),
+        sync_resource_state_summary=partial(
+            routing._sync_resource_state_summary_slot, host
+        ),
+        write_productivity_snapshot=partial(
+            agent_runtime_state._write_productivity_snapshot, host
+        ),
+        build_system_messages=partial(system_prompt._build_system_messages, host),
+        tool_choice_for_main_loop=partial(routing._tool_choice_for_main_loop, host),
+        normalize_repl_file_change_calls=partial(
+            routing._normalize_repl_file_change_tool_calls, host
+        ),
+        normalize_tool_calls=partial(normalize_tool_calls_for_execution, host),
+        maybe_write_bare_run_tail_snapshot=partial(
+            embedded_fullrun._maybe_write_bare_run_tail_snapshot, host
+        ),
+        maybe_embedded_full_run_after_quick_test=partial(
+            embedded_fullrun._maybe_embedded_full_run_after_quick_test, host
+        ),
+    )
+
+
+__all__ = ["AgentHostPorts", "compose_agent_host_ports"]

scienceflow/agent/core/ports/session_callbacks.py

@@ -0,0 +1,173 @@
+"""ScienceFlow policies adapted to InquiryCraft's post-commit lifecycle."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from inquirycraft.runtime import (
+    RuntimeContext,
+    ToolCommitDecision,
+    ToolCommitObservation,
+)
+from inquirycraft.tools import ToolOutputReducerRegistry, ToolResult, coerce_tool_result
+
+from scienceflow.agent.core.ports.callback_ports import resolve_agent_callback
+
+
+def scienceflow_output_reducers(host: Any) -> ToolOutputReducerRegistry:
+    """Make IQ the single projection owner while preserving SF-visible feedback."""
+
+    registry = ToolOutputReducerRegistry()
+
+    def register(tool_name: str) -> None:
+        def reduce(*, args, result, **_):
+            guard = getattr(host, "_guard_manager", None)
+            coaching = (
+                guard.process_tool_result(tool_name, args, result) if guard else ""
+            )
+            visible = host._host_ports.prepare_tool_feedback_for_memory(
+                tool_name, args, result, guard_coaching=coaching
+            )
+            return visible, "scienceflow_feedback_v1"
+
+        registry.register(tool_name, reduce)
+
+    for tool in host.availableTools:
+        register(str(tool.name))
+    return registry
+
+
+class ScienceFlowPostCommitAdapter:
+    """Run domain callbacks from immutable, journaled tool evidence."""
+
+    def __init__(self, host: Any) -> None:
+        self.host = host
+        self._seen: set[tuple[str, str, int]] = set()
+
+    async def __call__(
+        self, observation: ToolCommitObservation, context: RuntimeContext
+    ) -> ToolCommitDecision | None:
+        if observation.recovering and not observation.replayed:
+            return None
+        key = (
+            context.run_id,
+            str(observation.invocation.id),
+            observation.journal_attempt,
+        )
+        if key in self._seen:
+            return None
+        self._seen.add(key)
+        host = self.host
+        name = str(observation.invocation.name)
+        args = host._host_ports.normalize_tool_input_paths(
+            name, dict(observation.invocation.arguments)
+        )
+        args.pop("thought", None)
+        raw_result = coerce_tool_result(observation.raw_result)
+        await self._candidate_archive(name, args, raw_result)
+        if name != "bash":
+            return None
+        early = await host._host_ports.maybe_embedded_full_run_after_quick_test(
+            args, raw_result
+        )
+        if early is not None:
+            return self._terminate(str(early), "embedded_full_run")
+        await host._host_ports.maybe_write_bare_run_tail_snapshot(args, raw_result)
+        stage_callback = resolve_agent_callback(host, "stage_capture")
+        if not self._stage_ready(raw_result, stage_callback):
+            return None
+        stage_output = stage_callback(agent=host, args=args, tool_result=raw_result)
+        if inspect.isawaitable(stage_output):
+            stage_output = await stage_output
+        self._refresh_stage_id(stage_callback, context)
+        if stage_output:
+            return self._terminate(str(stage_output), "stage_capture")
+        return None
+
+    async def _candidate_archive(
+        self, name: str, args: dict[str, Any], result: ToolResult
+    ) -> None:
+        callback = resolve_agent_callback(self.host, "candidate_archive")
+        if not callable(callback):
+            return
+        try:
+            value = callback(
+                agent=self.host,
+                tool_name=name,
+                args=args,
+                tool_result=result,
+            )
+            if inspect.isawaitable(value):
+                await value
+        except Exception as exc:
+            self.host._log_info(
+                "[long-horizon-flow] candidate artifact archive callback failed: %s",
+                exc,
+            )
+
+    def _stage_ready(self, result: ToolResult, callback: Any) -> bool:
+        host = self.host
+        owner = getattr(callback, "__self__", None)
+        if isinstance(getattr(owner, "pending_text_stage_commit", None), dict):
+            return False
+        artifact = str(getattr(host, "_lnr_candidate_artifact_rel", "") or "").strip()
+        artifact_ready = bool(
+            getattr(host, "_lnr_stage_capture_on_candidate_artifact", False)
+            and artifact
+            and (host._workspace_dir / artifact).exists()
+        )
+        return bool(
+            callable(callback)
+            and not host._embedded_full_run_enabled
+            and not result.error
+            and (getattr(host, "_lnr_snapshot_ok", False) or artifact_ready)
+        )
+
+    @staticmethod
+    def _refresh_stage_id(callback: Any, context: RuntimeContext) -> None:
+        owner = getattr(callback, "__self__", None)
+        snapshots = getattr(owner, "stage_snapshots", ())
+        latest = None
+        fallback_stage_id = ""
+        if isinstance(snapshots, dict) and snapshots:
+            fallback_stage_id = str(next(reversed(snapshots)))
+            latest = snapshots[fallback_stage_id]
+        elif snapshots:
+            latest = snapshots[-1]
+        next_stage = getattr(owner, "_next_stage_id_for_logging", None)
+        if callable(next_stage):
+            stage_id = str(next_stage() or "draft")
+        elif latest is not None:
+            stage_id = str(
+                getattr(latest, "stage_id", "") or fallback_stage_id or "draft"
+            )
+        else:
+            return
+        lineage = getattr(owner, "_lineage_uid_prefix", None)
+        lineage_id = str(lineage() or "") if callable(lineage) else ""
+        node = getattr(owner, "_stage_node_uid", None)
+        node_uid = (
+            str(node(stage_id, lineage_id=lineage_id) or "") if callable(node) else ""
+        )
+        context.metadata["stage_id"] = stage_id
+        context.metadata["lineage_id"] = lineage_id
+        context.metadata["node_uid"] = node_uid
+        host = getattr(callback, "__self__", None)
+        agent = getattr(host, "_resource_main_agent_ref", None)
+        if agent is not None:
+            agent._scienceflow_stage_id = stage_id
+            agent._scienceflow_lineage_id = lineage_id
+            agent._scienceflow_node_uid = node_uid
+
+    @staticmethod
+    def _terminate(output: str, route: str) -> ToolCommitDecision:
+        return ToolCommitDecision(
+            action="terminate_session",
+            output=output,
+            reason=f"scienceflow_{route}",
+            route=route,
+        )
+
+
+__all__ = ["ScienceFlowPostCommitAdapter", "scienceflow_output_reducers"]

scienceflow/agent/core/runtime/__init__.py

@@ -0,0 +1 @@
+"""Agent runtime implementation and lifecycle policy."""