graphloom 0.1.0__py3-none-any.whl

graphloom/__init__.py

@@ -0,0 +1,30 @@
+"""graphloom — a minimal generic agent-loop framework on top of LangGraph.
+
+`build_agent_graph` assembles a standard ReAct loop
+(ai / tool / history / compaction / finish) with dependency-injected
+llm, checkpointer, tools, and runtime_context. Everything transport- or
+business-specific (HITL, subagent dispatch, artifact delivery over a wire)
+is a tool the caller supplies; the framework wires only the loop.
+
+Quick start::
+
+    from graphloom import build_agent_graph, build_initial_agent_state
+    graph = build_agent_graph(custom_system_prompt=..., tools=[...], llm=...)
+    await graph.ainvoke(build_initial_agent_state(input_query=...))
+"""
+from graphloom.graph_builder import build_agent_graph
+from graphloom.model.state import AgentState, build_initial_agent_state
+from graphloom.model.subagents import SubAgentSpec, SubAgentRunContext
+from graphloom.model.base_tool_input import StandardThoughtInput, PlannerThoughtInput
+
+__all__ = [
+    "build_agent_graph",
+    "AgentState",
+    "build_initial_agent_state",
+    "SubAgentSpec",
+    "SubAgentRunContext",
+    "StandardThoughtInput",
+    "PlannerThoughtInput",
+]
+
+__version__ = "0.1.0"

graphloom/config.py

@@ -0,0 +1,56 @@
+"""
+Constants controlling the context-compaction node inserted after `history`.
+
+All values can be overridden via environment variables (GRAPHLOOM_* prefix) to
+make tuning possible without a redeploy. Keep this file free of any runtime
+dependency beyond `os`.
+"""
+import os
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.environ.get(name, default))
+    except (TypeError, ValueError):
+        return default
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(os.environ.get(name, default))
+    except (TypeError, ValueError):
+        return default
+
+
+# Effective model context window in tokens. Used as the denominator for the
+# trigger ratio. Should roughly match the smallest model you run.
+MODEL_CONTEXT_WINDOW: int = _env_int("GRAPHLOOM_MODEL_CONTEXT_WINDOW", 830_000)
+
+# Soft trigger: when estimated context tokens reach this fraction of the
+# window, the compaction node kicks in synchronously.
+COMPACT_TRIGGER_RATIO: float = _env_float("GRAPHLOOM_COMPACT_TRIGGER_RATIO", 0.75)
+
+# Target size after compaction (fraction of the window). Used as a soft
+# character budget for the summarizing LLM's action_results field.
+COMPACT_TARGET_RATIO: float = _env_float("GRAPHLOOM_COMPACT_TARGET_RATIO", 0.12)
+
+# How many trailing past_steps are kept verbatim (never compacted).
+COMPACT_KEEP_RECENT_STEPS: int = _env_int("GRAPHLOOM_COMPACT_KEEP_RECENT", 5)
+
+# Anti-thrashing: hard cap on recursive compaction attempts per node call.
+COMPACT_MAX_RETRY: int = _env_int("GRAPHLOOM_COMPACT_MAX_RETRY", 2)
+
+# Emergency truncation: when retries exhaust, trim the longest action_results
+# among the recent (kept) steps down to this char budget.
+COMPACT_EMERGENCY_TRUNC_CHARS: int = _env_int("GRAPHLOOM_COMPACT_EMERGENCY_TRUNC_CHARS", 500)
+
+# tiktoken encoding to use for estimation. cl100k_base is OpenAI-compatible
+# and a reasonable proxy for other providers exposed via an OpenAI API shim.
+COMPACT_TOKENIZER_ENCODING: str = os.environ.get("GRAPHLOOM_COMPACT_TOKENIZER", "cl100k_base")
+
+# Sentinel key inside past_steps[0] that signals the reducer to REPLACE the
+# channel instead of appending. See `add_past_steps` in state.py.
+COMPACT_SENTINEL_KEY: str = "__compact_replace__"
+
+# Concurrency ceiling for parallel subagent dispatch.
+SUBAGENT_MAX_CONCURRENCY = int(os.getenv("SUBAGENT_MAX_CONCURRENCY", "10"))

graphloom/graph_builder.py

@@ -0,0 +1,149 @@
+"""graph_builder.py — the generic agent-loop factory.
+
+`build_agent_graph` assembles a standard ReAct-style loop:
+    observer? → ai → tool → route → history → compaction → ai  (+ finish)
+
+Everything transport- or business-specific (HITL, subagent dispatch, artifact
+delivery over a wire) is a tool the caller supplies; the framework wires only
+the loop and the structural nodes.
+"""
+from typing import Any, Callable, List, Optional
+
+from langchain_core.language_models import BaseChatModel
+from langgraph.graph import END, StateGraph
+
+from graphloom.nodes.ai import create_ai_node
+from graphloom.nodes.compaction import create_context_compaction_node
+from graphloom.nodes.finish import create_finish_node
+from graphloom.nodes.history import create_history_node
+from graphloom.nodes.tool import create_tool_node
+from graphloom.model.state import AgentState
+from graphloom.model.subagents import SubAgentSpec
+from graphloom.prompt.stack import create_prompt_stack
+from graphloom.tools.artifact import (
+    write_artifact, read_artifact, patch_artifact, deliver_artifact,
+)
+
+_BUILTIN_ARTIFACT_TOOLS = [write_artifact, read_artifact, patch_artifact, deliver_artifact]
+
+
+def build_agent_graph(
+    *,
+    custom_system_prompt: str,
+    tools: List[Any],
+    llm: BaseChatModel,
+    find_fault: Optional[Any] = None,
+    custom_find_fault: Optional[Callable] = None,
+    observer: Optional[Callable] = None,
+    subagents: Optional[List[SubAgentSpec]] = None,
+    checkpointer=None,
+    tool_filter: Optional[Callable] = None,
+    allow_direct_reply: bool = False,
+    available_skills: Optional[List[str]] = None,
+    skills_dir: Optional[str] = None,
+):
+    # Deduplicate user tools while preserving the FIRST occurrence (highest priority)
+    unique_tools = []
+    seen_names = set()
+    for t in tools:
+        t_name = getattr(t, "name", None)
+        if t_name not in seen_names:
+            unique_tools.append(t)
+            if t_name:
+                seen_names.add(t_name)
+
+    # Auto-inject builtin artifact tools (deduplicated)
+    builtin = [t for t in _BUILTIN_ARTIFACT_TOOLS if t.name not in seen_names]
+    compiled_tools = unique_tools + builtin
+    compiled_prompt = str(custom_system_prompt or "").strip()
+    if not compiled_prompt:
+        raise ValueError("custom_system_prompt must be provided.")
+    compiled_subagents = list(subagents or [])
+    if compiled_subagents:
+        # Lazy import: dispatch_subagents is an optional builtin, only needed
+        # when subagents are actually wired in.
+        from graphloom.tools.dispatch import compose_system_prompt, create_dispatch_subagents_tool
+        compiled_prompt = compose_system_prompt(compiled_prompt, compiled_subagents)
+        compiled_tools.append(create_dispatch_subagents_tool(compiled_subagents, checkpointer))
+
+    # Lazy import: find_fault is an optional review node.
+    find_fault_node = None
+    if isinstance(find_fault, str):
+        from graphloom.nodes.find_fault import create_find_fault_node
+        find_fault_node = create_find_fault_node(find_fault, llm)
+    elif find_fault is not None:
+        find_fault_node = find_fault
+
+    prompt_stack = create_prompt_stack(
+        custom_system_prompt=compiled_prompt,
+        available_skills=available_skills,
+        skills_dir=skills_dir,
+    )
+    ai_node = create_ai_node(prompt_stack=prompt_stack, tools=compiled_tools, llm=llm, tool_filter=tool_filter)
+    workflow = StateGraph(AgentState)
+
+    if observer:
+        workflow.add_node("observer", observer)
+    workflow.add_node("ai", ai_node)
+    workflow.add_node("tool", create_tool_node(compiled_tools, allow_direct_reply=allow_direct_reply))
+    if custom_find_fault:
+        workflow.add_node("custom_find_fault", custom_find_fault)
+    if find_fault_node:
+        workflow.add_node("find_fault", find_fault_node)
+    workflow.add_node("history", create_history_node())
+    workflow.add_node("compaction", create_context_compaction_node(prompt_stack, llm))
+    workflow.add_node("finish", create_finish_node())
+
+    workflow.set_entry_point("observer" if observer else "ai")
+    if observer:
+        workflow.add_edge("observer", "ai")
+
+    def route_after_tool(state: AgentState) -> str:
+        # Once deliver_artifact has marked the run as ended (end_tag=True), we
+        # always want to exit the loop — even if the manifest is empty (e.g.
+        # pure-text answer with no artifacts). Find-fault nodes are still
+        # consulted when a custom reviewer is wired in; empty manifests are
+        # treated as a no-op by those reviewers.
+        if state.get("end_tag"):
+            if custom_find_fault:
+                return "custom_find_fault"
+            if find_fault_node:
+                return "find_fault"
+            return "finish"
+        return "history"
+
+    def route_after_custom_find_fault(state: AgentState) -> str:
+        if list(state.get("current_delivery_manifest", []) or []):
+            if find_fault_node:
+                return "find_fault"
+            return "finish"
+        return "history"
+
+    def route_after_find_fault(state: AgentState) -> str:
+        if list(state.get("current_delivery_manifest", []) or []):
+            return "finish"
+        return "history"
+
+    workflow.add_edge("ai", "tool")
+
+    tool_targets = {"history": "history", "finish": "finish"}
+    if custom_find_fault:
+        tool_targets["custom_find_fault"] = "custom_find_fault"
+    if find_fault_node:
+        tool_targets["find_fault"] = "find_fault"
+    workflow.add_conditional_edges("tool", route_after_tool, tool_targets)
+
+    if custom_find_fault:
+        custom_targets = {"history": "history", "finish": "finish"}
+        if find_fault_node:
+            custom_targets["find_fault"] = "find_fault"
+        workflow.add_conditional_edges("custom_find_fault", route_after_custom_find_fault, custom_targets)
+
+    if find_fault_node:
+        workflow.add_conditional_edges("find_fault", route_after_find_fault, {"history": "history", "finish": "finish"})
+
+    workflow.add_edge("history", "compaction")
+    workflow.add_edge("compaction", "observer" if observer else "ai")
+    workflow.add_edge("finish", END)
+
+    return workflow.compile(checkpointer=checkpointer)

graphloom/model/__init__.py

@@ -0,0 +1,23 @@
+"""Data types: state, reducers, schemas, subagent specs."""
+from graphloom.model.state import AgentState, build_initial_agent_state
+from graphloom.model.subagents import SubAgentSpec, SubAgentRunContext
+from graphloom.model.base_tool_input import StandardThoughtInput, PlannerThoughtInput
+from graphloom.model.artifact_manifest import (
+    ArtifactManifestEntry,
+    merge_artifact_manifest,
+    replace_artifact_manifest,
+    normalize_artifact_manifest_entry,
+)
+
+__all__ = [
+    "AgentState",
+    "build_initial_agent_state",
+    "SubAgentSpec",
+    "SubAgentRunContext",
+    "StandardThoughtInput",
+    "PlannerThoughtInput",
+    "ArtifactManifestEntry",
+    "merge_artifact_manifest",
+    "replace_artifact_manifest",
+    "normalize_artifact_manifest_entry",
+]

graphloom/model/artifact_manifest.py

@@ -0,0 +1,131 @@
+import os
+from datetime import datetime
+from typing import Any, Dict, List
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactManifestEntry(BaseModel):
+    path: str = Field(default="", description="Absolute artifact path.")
+    filename: str = Field(default="", description="Basename of the artifact path.")
+    type: str = Field(default="unknown", description="Artifact type such as py, js, wasm, md, txt, json, or bin.")
+    role: str = Field(default="supporting", description="Artifact role, for example crawler_entry, signature_runtime, or readme.")
+    producer: str = Field(default="", description="Producer name for traceability.")
+    size_bytes: int = Field(default=0, description="Artifact file size.")
+    created_at: str = Field(default="", description="ISO timestamp from filesystem metadata.")
+    updated_at: str = Field(default="", description="ISO timestamp from filesystem metadata.")
+    is_binary: bool = Field(default=False, description="Whether the artifact is binary.")
+    summary: str = Field(default="")
+    tags: List[str] = Field(default_factory=list)
+
+
+_TEXT_LIKE_EXTENSIONS = {"py", "js", "ts", "json", "md", "txt", "yaml", "yml", "html", "css", "xml", "csv", "sh"}
+
+
+def _iso_from_ts(timestamp: float) -> str:
+    try:
+        return datetime.fromtimestamp(timestamp).astimezone().isoformat(timespec="seconds")
+    except Exception:
+        return ""
+
+
+def _artifact_type(path: str) -> str:
+    ext = os.path.splitext(path)[1].lower().lstrip(".")
+    return ext or "unknown"
+
+
+def _is_binary(path: str, artifact_type: str) -> bool:
+    if artifact_type in _TEXT_LIKE_EXTENSIONS:
+        return False
+    if artifact_type in {"wasm", "png", "jpg", "jpeg", "gif", "ico", "pdf", "zip", "bin"}:
+        return True
+    try:
+        with open(path, "rb") as handle:
+            sample = handle.read(2048)
+    except OSError:
+        return False
+    return b"\x00" in sample
+
+
+def normalize_artifact_manifest_entry(entry: Dict[str, Any]) -> Dict[str, Any]:
+    data = dict(entry or {})
+    path = str(data.get("path") or "").strip()
+    filename = str(data.get("filename") or "").strip()
+
+    if path:
+        resolved_path = os.path.abspath(path)
+        data["path"] = resolved_path
+        if not filename:
+            data["filename"] = os.path.basename(resolved_path)
+        if not data.get("type"):
+            data["type"] = _artifact_type(resolved_path)
+        if os.path.exists(resolved_path):
+            try:
+                stat_result = os.stat(resolved_path)
+                data.setdefault("size_bytes", int(stat_result.st_size))
+                data.setdefault("created_at", _iso_from_ts(stat_result.st_ctime))
+                data.setdefault("updated_at", _iso_from_ts(stat_result.st_mtime))
+            except OSError:
+                pass
+            data.setdefault("is_binary", _is_binary(resolved_path, str(data.get("type") or "unknown")))
+
+    return ArtifactManifestEntry(**data).model_dump()
+
+
+def merge_artifact_manifest(left: List[Dict[str, Any]], right: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    left = list(left or [])
+    right = list(right or [])
+
+    merged: Dict[str, Dict[str, Any]] = {}
+    for raw_item in left + right:
+        if not isinstance(raw_item, dict):
+            continue
+        item = normalize_artifact_manifest_entry(raw_item)
+        path_value = str(item.get("path") or "").strip()
+        if not path_value:
+            continue
+
+        previous = merged.get(path_value)
+        if previous is None:
+            merged[path_value] = item
+            continue
+
+        prev_updated = str(previous.get("updated_at") or "")
+        curr_updated = str(item.get("updated_at") or "")
+        prev_created = str(previous.get("created_at") or "")
+        curr_created = str(item.get("created_at") or "")
+        if (curr_updated, curr_created, path_value) >= (prev_updated, prev_created, path_value):
+            merged[path_value] = item
+
+    return sorted(
+        merged.values(),
+        key=lambda item: (
+            str(item.get("updated_at") or ""),
+            str(item.get("created_at") or ""),
+            str(item.get("path") or ""),
+        ),
+        reverse=True,
+    )
+
+
+def replace_artifact_manifest(left: List[Dict[str, Any]], right: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    right = list(right or [])
+
+    replaced: List[Dict[str, Any]] = []
+    for raw_item in right:
+        if not isinstance(raw_item, dict):
+            continue
+        path_value = str(raw_item.get("path") or "").strip()
+        if not path_value:
+            continue
+        replaced.append(normalize_artifact_manifest_entry(raw_item))
+
+    return sorted(
+        replaced,
+        key=lambda item: (
+            str(item.get("updated_at") or ""),
+            str(item.get("created_at") or ""),
+            str(item.get("path") or ""),
+        ),
+        reverse=True,
+    )

graphloom/model/base_tool_input.py

@@ -0,0 +1,53 @@
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class PlannerSummary(BaseModel):
+    """High-level planner reasoning."""
+    task_analysis: str = Field(
+        description="What the user wants, task type, and likely difficulty.",
+    )
+    progress_review: str = Field(
+        description="What has already been accomplished and what is still missing.",
+    )
+    strategy: str = Field(
+        description="What to do in the current phase only.",
+    )
+    concise_assessment: str = Field(
+        description="Short user-facing summary of why this plan makes sense now.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Base thought inputs
+# ---------------------------------------------------------------------------
+
+class StandardThoughtInput(BaseModel):
+    """Unified chain-of-thought parameters for all agent tools."""
+    model_config = {"extra": "allow"}
+
+    last_step_review: str = Field(
+        description="Concise one-sentence analysis of your last action. Clearly state success, failure, or uncertain."
+    )
+    working_notes: str = Field(
+        description="1-3 sentences of specific notes on this step and overall progress. Put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc."
+    )
+    next_action: str = Field(
+        description="State the next immediate goal and action to achieve it, in one clear sentence."
+    )
+
+# ---------------------------------------------------------------------------
+# Planner-level thought input (for main orchestrator tools)
+# ---------------------------------------------------------------------------
+
+class PlannerThoughtInput(StandardThoughtInput):
+    """Extends standard chain-of-thought with planner-specific structured fields.
+
+    Used by dispatch_subagents and request_user_interaction in the main orchestrator.
+    Forces the LLM to produce structured planning outputs with every tool call.
+    """
+    planner_summary: PlannerSummary = Field(
+        description="High-level planner reasoning for the user. "
+                    "Covers only the current phase.",
+    )

graphloom/model/state.py

@@ -0,0 +1,110 @@
+from typing import Annotated, Any, Dict, List, Optional, Sequence, TypedDict
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+from langgraph.graph.message import add_messages
+
+from graphloom.config import COMPACT_SENTINEL_KEY
+from graphloom.model.artifact_manifest import merge_artifact_manifest, replace_artifact_manifest
+
+
+def add_past_steps(left: List[Dict[str, Any]], right: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    if left is None:
+        left = []
+    if right is None:
+        right = []
+    # Sentinel-aware replace: when the compaction node wants to swap the whole
+    # channel, it returns [{"__compact_replace__": True}, compacted, *recent].
+    # All other callers keep append semantics.
+    if right and isinstance(right[0], dict) and right[0].get(COMPACT_SENTINEL_KEY) is True:
+        return list(right[1:])
+
+    combined = list(left)
+    step_index = {
+        str(step.get("step_id")): idx
+        for idx, step in enumerate(combined)
+        if isinstance(step, dict) and step.get("step_id")
+    }
+    for step in right:
+        if isinstance(step, dict) and step.get("step_id"):
+            step_id = str(step.get("step_id"))
+            if step_id in step_index:
+                combined[step_index[step_id]] = step
+                continue
+            step_index[step_id] = len(combined)
+        combined.append(step)
+    return combined
+
+
+def keep_max_step_counter(left: Any, right: Any) -> int:
+    """Reducer for `step_counter`. Always keep the highest value seen so the
+    counter is strictly monotonic across the graph — including across
+    compaction runs that shrink `past_steps`. Using a dedicated counter
+    (instead of `len(past_steps)`) is what prevents step_id collisions when
+    compaction folds earlier steps into a summary."""
+    try:
+        left_int = int(left or 0)
+    except (TypeError, ValueError):
+        left_int = 0
+    try:
+        right_int = int(right or 0)
+    except (TypeError, ValueError):
+        right_int = 0
+    return max(left_int, right_int)
+
+
+_TOOL_HISTORY_MAX = 8
+
+
+def add_tool_results(left: List[Dict[str, Any]], right: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    if left is None:
+        left = []
+    if right is None:
+        right = []
+    combined = left + right
+    return combined[-_TOOL_HISTORY_MAX:]
+
+
+class AgentState(TypedDict):
+    current_agent_name: str
+    messages: Annotated[Sequence[BaseMessage], add_messages]
+    input_query: str
+    attach_message_parts: Optional[List[Dict[str, Any]]]
+    session_id: Optional[str]
+    latest_ai_message: Optional[AIMessage]
+
+    past_steps: Annotated[List[Dict[str, Any]], add_past_steps]
+    step_counter: Annotated[int, keep_max_step_counter]
+    tool_result_history: List[Dict[str, Any]]
+    observer_message_parts: Optional[List[HumanMessage]]
+
+    input_artifact_manifest: Annotated[List[Dict[str, Any]], replace_artifact_manifest]
+    current_delivery_manifest: Annotated[List[Dict[str, Any]], replace_artifact_manifest]
+    approved_artifact_manifest: Annotated[List[Dict[str, Any]], merge_artifact_manifest]
+
+    final_reply: Optional[str]
+    agent_status: Optional[str]
+
+    end_tag: bool
+
+
+def build_initial_agent_state(**overrides: Any) -> AgentState:
+    state: AgentState = {
+        "current_agent_name": "main",
+        "messages": [],
+        "input_query": "",
+        "attach_message_parts": None,
+        "session_id": None,
+        "latest_ai_message": None,
+        "past_steps": [],
+        "step_counter": 0,
+        "tool_result_history": [],
+        "observer_message_parts": None,
+        "input_artifact_manifest": [],
+        "current_delivery_manifest": [],
+        "approved_artifact_manifest": [],
+        "final_reply": "",
+        "agent_status": "running",
+        "end_tag": False,
+    }
+    state.update(overrides)
+    return state

graphloom/model/subagents.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+
+@dataclass(frozen=True)
+class SubAgentRunContext:
+    parent_session_id: str
+    child_session_id: str
+    step: Any
+    result: Any = None
+    error: Optional[BaseException] = None
+    user_id: str = ""
+
+
+@dataclass(frozen=True)
+class SubAgentSpec:
+    agent_name: str
+    description: str
+    factory: Callable[[], Any]
+    cleanup_hook: Optional[Callable[[SubAgentRunContext], Any]] = None

graphloom/nodes/__init__.py

@@ -0,0 +1 @@
+"""Structural graph nodes (internal)."""