PyPI - specmodule - Versions diffs - 0.1.0__py3-none-any.whl - Mend

specmodule 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

llm/__init__.py +21 -0
llm/client.py +654 -0
llm/config.py +213 -0
module_harness/__init__.py +201 -0
module_harness/align.py +39 -0
module_harness/builtins.py +29 -0
module_harness/checkpoint.py +336 -0
module_harness/cli.py +1492 -0
module_harness/command.py +115 -0
module_harness/config.py +95 -0
module_harness/consistency.py +123 -0
module_harness/entry.py +74 -0
module_harness/events.py +149 -0
module_harness/feed.py +197 -0
module_harness/graph_builder.py +334 -0
module_harness/harness.py +181 -0
module_harness/loader.py +215 -0
module_harness/module.py +452 -0
module_harness/outputfmt.py +139 -0
module_harness/prompt.py +84 -0
module_harness/query.py +216 -0
module_harness/registry.py +180 -0
module_harness/scaffold.py +404 -0
module_harness/spec.py +209 -0
module_harness/status.py +96 -0
module_harness/store.py +482 -0
module_harness/submodule.py +268 -0
module_harness/templates/builtin/codereview.json +32 -0
module_harness/templates/builtin/docwrite.json +30 -0
module_harness/templates/builtin/summarize.json +24 -0
module_harness/templates/builtin/translate.json +27 -0
module_harness/translator.py +314 -0
specmodule-0.1.0.dist-info/METADATA +321 -0
specmodule-0.1.0.dist-info/RECORD +38 -0
specmodule-0.1.0.dist-info/WHEEL +5 -0
specmodule-0.1.0.dist-info/entry_points.txt +2 -0
specmodule-0.1.0.dist-info/licenses/LICENSE +21 -0
specmodule-0.1.0.dist-info/top_level.txt +2 -0

module_harness/feed.py ADDED Viewed

@@ -0,0 +1,197 @@
+"""stdlib 可视化开关：零第三方依赖的极简运行 feed（roadmap 独立线）。
+用 ``http.server`` 起一个只读 HTTP 服务，把已落盘的运行数据以 JSON feed
+暴露给浏览器/脚本轮询查看——运行中即可看（每 tick 落盘 run.sqlite），
+运行后完整看。数据组合全部走共享查询层（``module_harness.query`` /
+``status.query_run_status``），本文件只做 HTTP 适配，不重实现查询逻辑。
+富交互编辑器/完整 Web UX 属于生态项目 ``SpecModule_webview``；本开关只
+提供"极简可见"的最低形态，供库使用者零依赖快速查看。
+用法（CLI 接线见 cli.py ``feed`` 子命令）::
+    specmodule feed [--host 127.0.0.1] [--port 8000] [--run-id <id>]
+端点：
+    GET /                      极简 HTML 页面（原生 JS 每 2s 轮询 feed）
+    GET /feed.json?run_id=...  组合 JSON：status / timeline / checkpoints
+                               （缺省 run_id = 最新修改的运行）
+"""
+from __future__ import annotations
+import json
+import logging
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+from .query import (
+    build_checkpoints,
+    build_timeline,
+    checkpoints_to_dict,
+    timeline_to_dict,
+)
+from .status import query_run_status
+log = logging.getLogger(__name__)
+_HTML = """<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<title>SpecModule 运行 feed</title>
+<style>
+  body { font-family: ui-monospace, Consolas, monospace; margin: 2em; }
+  h1 { font-size: 1.2em; }
+  .phase { font-weight: bold; }
+  table { border-collapse: collapse; width: 100%; }
+  td, th { border: 1px solid #ccc; padding: 4px 8px; text-align: left; font-size: 0.9em; }
+  .err { color: #c00; }
+  .ok { color: #080; }
+</style>
+</head>
+<body>
+<h1>SpecModule 运行 feed</h1>
+<p>run_id: <span id="run-id">?</span> · 阶段: <span id="phase" class="phase">?</span>
+   · tick: <span id="tick">?</span> · 刷新: <span id="stamp">?</span></p>
+<div id="outputs"></div>
+<h2>时间线</h2>
+<table id="timeline"><tr><th>tick</th><th>节点</th><th>状态</th><th>输出/错误</th></tr></table>
+<h2>检查点</h2>
+<table id="checkpoints"><tr><th>tick</th><th>类型</th><th>fired 节点</th></tr></table>
+<script>
+async function refresh() {
+  try {
+    const r = await fetch("feed.json" + location.search);
+    const d = await r.json();
+    const st = d.status;
+    document.getElementById("run-id").textContent = d.run_id;
+    document.getElementById("phase").textContent = st ? st.phase : "无运行";
+    document.getElementById("tick").textContent = st ? (st.tick ?? "—") : "—";
+    document.getElementById("stamp").textContent = new Date().toLocaleTimeString();
+    let oh = "";
+    if (st && st.outputs) {
+      for (const [node, out] of Object.entries(st.outputs)) {
+        oh += "<p><b>" + node + "</b>: "
+            + (typeof out === "string" ? out : JSON.stringify(out)) + "</p>";
+      }
+    }
+    document.getElementById("outputs").innerHTML = oh;
+    const tl = document.getElementById("timeline");
+    while (tl.rows.length > 1) tl.deleteRow(1);
+    for (const e of (d.timeline ? d.timeline.entries : [])) {
+      const row = tl.insertRow();
+      row.insertCell().textContent = e.tick;
+      row.insertCell().textContent = e.node;
+      row.insertCell().textContent = e.status || (e.error ? "✗" : "✓");
+      row.insertCell().textContent = e.error || (e.output ? JSON.stringify(e.output) : "");
+    }
+    const cp = document.getElementById("checkpoints");
+    while (cp.rows.length > 1) cp.deleteRow(1);
+    for (const e of (d.checkpoints ? d.checkpoints.checkpoints : [])) {
+      const row = cp.insertRow();
+      row.insertCell().textContent = e.tick;
+      row.insertCell().textContent = e.label ? e.label : "tick";
+      row.insertCell().textContent = (e.fired || []).join(", ");
+    }
+  } catch (err) {
+    document.getElementById("phase").textContent = "feed 读取失败: " + err;
+  }
+}
+setInterval(refresh, 2000);
+refresh();
+</script>
+</body>
+</html>
+"""
+class RunFeedHandler(BaseHTTPRequestHandler):
+    """只读 feed：/ 为页面，/feed.json 为 JSON 组合。"""
+    server: "RunFeedServer"  # type: ignore[misc]  # ThreadingHTTPServer 实例
+    def do_GET(self) -> None:  # noqa: N802（http.server 命名约定）
+        parsed = urlparse(self.path)
+        if parsed.path == "/feed.json":
+            self._serve_feed(parsed)
+        elif parsed.path in ("/", "/index.html"):
+            self._serve_html()
+        else:
+            self.send_error(404, "not found")
+    # -- feed -----------------------------------------------------------
+    def _serve_feed(self, parsed) -> None:
+        qs = parse_qs(parsed.query)
+        run_id = (qs.get("run_id") or [None])[0] or self.server.latest_run_id()
+        base = self.server.base_dir
+        if run_id is None:
+            self._send_json({"run_id": None, "error": "无运行记录"}, 404)
+            return
+        status = query_run_status(run_id, base_dir=base)
+        timeline = build_timeline(run_id, base_dir=base)
+        checkpoints = build_checkpoints(run_id, base_dir=base)
+        if status is None and timeline is None:
+            self._send_json({"run_id": run_id, "error": "无运行记录"}, 404)
+            return
+        self._send_json({
+            "run_id": run_id,
+            "status": status and {
+                "phase": status.phase,
+                "tick": status.tick,
+                "fired": status.fired,
+                "outputs": status.outputs,
+                "error": status.error,
+            },
+            "timeline": timeline_to_dict(timeline) if timeline else None,
+            "checkpoints": checkpoints_to_dict(checkpoints) if checkpoints else None,
+        })
+    def _serve_html(self) -> None:
+        body = _HTML.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+    def _send_json(self, data: dict, code: int = 200) -> None:
+        body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+    def log_message(self, fmt: str, *args) -> None:  # noqa: A003
+        log.info("%s - %s", self.address_string(), fmt % args)
+class RunFeedServer(ThreadingHTTPServer):
+    """极简运行 feed 服务（零第三方依赖，stdlib http.server）。"""
+    daemon_threads = True
+    def __init__(
+        self,
+        server_address: tuple[str, int],
+        base_dir: Path | None = None,
+    ) -> None:
+        self.base_dir = base_dir
+        super().__init__(server_address, RunFeedHandler)
+    def latest_run_id(self) -> str | None:
+        """与 CLI ``_latest_run_id`` 同语义：扫描 runs/ 取最新修改子目录。"""
+        runs = (self.base_dir or Path.cwd()) / ".specmodule" / "runs"
+        if not runs.is_dir():
+            return None
+        candidates = [
+            p for p in runs.iterdir()
+            if p.is_dir() and (p / "status.json").exists()
+        ]
+        if not candidates:
+            return None
+        return max(candidates, key=lambda p: p.stat().st_mtime).name

module_harness/graph_builder.py ADDED Viewed

@@ -0,0 +1,334 @@
+# module_harness/graph_builder.py
+"""Tasklist -> tickflow Graph translator.
+Translates a :class:`Tasklist` into a :class:`Graph` with namespace-isolated
+body registrations.  Each Task's body is registered as ``{module_id}:{key}``
+so modules with overlapping task keys do not collide.
+"""
+from __future__ import annotations
+import json
+from typing import Any
+from tickflow import Failure, Graph, parse as parse_graph
+from tickflow.ir import InputPolicy
+from .config import HarnessConfig
+from .outputfmt import OutputFormat
+from .registry import HarnessRegistry
+from .spec import SpecValidationError, TaskDefinition, Tasklist
+from .translator import prepare_flow, _suppress_parse_noise
+_CONSTANT_TOKENS = frozenset({"{spec}", "{tasklist}", "{node}"})
+def _is_constant_ref(producer: Any) -> bool:
+    """是否为注册时解析的常量引用（{spec}/{tasklist}/{node} 或 {spec.xxx}）。"""
+    return (
+        isinstance(producer, str)
+        and (producer in _CONSTANT_TOKENS or producer.startswith("{spec."))
+    )
+class TasklistTranslator:
+    """Translates a :class:`Tasklist` into a parsed :class:`Graph` paired with
+    a :class:`HarnessRegistry` that contains all required bodies.
+    Usage::
+        builder = TasklistTranslator(registry, module_id="my_mod")
+        graph, out_reg = builder.build(tasklist)
+    """
+    def __init__(
+        self,
+        registry: HarnessRegistry,
+        module_id: str,
+        *,
+        modules: dict[str, Any] | None = None,
+        llm_client: Any = None,
+    ) -> None:
+        self.reg = registry
+        self.module_id = module_id
+        self.modules = dict(modules or {})
+        self._llm_client = llm_client
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def build(self, tasklist: Tasklist, spec: Any | None = None) -> tuple[Graph, HarnessRegistry]:
+        """Iterate tasks, register bodies, parse flow, attach body names.
+        ``spec``：可选，用于解析 task 中 ``{spec.xxx}`` 字段引用。
+        Returns (graph, registry) where *registry* is ``self.reg`` (the same
+        object that was passed to the constructor, now populated with the
+        isolated body entries).
+        """
+        spec_dict = spec.to_dict() if spec is not None else {}
+        tasklist_dict = tasklist.to_dict()
+        # 1.  Register every task's body under an isolated name.
+        for key, task in tasklist.tasks.items():
+            self._register_body(key, task, spec_dict, tasklist_dict)
+        # 2.  Prepare the flow text for tickflow's parser (no body/input
+        #     declarations -- those are attached programmatically below
+        #     because tickflow's DSL does not support ``:`` in body names).
+        flow_text = prepare_flow(tasklist.flow)
+        # 3.  Parse into a Graph.  The parser validates that guard names
+        #     and default placeholder bodies exist in the registry.
+        with _suppress_parse_noise():
+            graph = parse_graph(flow_text, registry=self.reg)
+        # 4.  Assign the real (colon-scoped) body name to each graph node.
+        for key, task in tasklist.tasks.items():
+            isolated_name = self._isolated(key)
+            graph.nodes[key].body = isolated_name
+        # 5.  Wire task inputs to graph node inputs.
+        #     ``task.inputs = {field_name: producer}`` — 同时注册 field 名与
+        #     producer 名两个 key：body 用 ``view.<producer>.value``（有值），
+        #     ``view.<field_name>.value`` 为 Missing（不崩溃，脚本旧写法兼容）。
+        #     harness 的 prompt 占位符 ``{field}`` 经 _register_harness 传入的
+        #     input_aliases 在运行时解析 producer 输出值。
+        #     常量引用（{spec}/{tasklist}/{node}、{spec.xxx}）已由
+        #     _register_harness 解析为 spec_inputs，此处跳过。
+        for key, task in tasklist.tasks.items():
+            if task.inputs:
+                for field_name, producer in task.inputs.items():
+                    if _is_constant_ref(producer):
+                        continue
+                    graph.nodes[key].inputs[field_name] = InputPolicy.latest()
+                    if producer != field_name:
+                        graph.nodes[key].inputs[producer] = InputPolicy.latest()
+        return graph, self.reg
+    # ------------------------------------------------------------------
+    # Body registration
+    # ------------------------------------------------------------------
+    def _isolated(self, key: str) -> str:
+        """Return the namespace-isolated body name for *key*."""
+        return f"{self.module_id}:{key}"
+    def _register_body(self, key: str, task: TaskDefinition,
+                       spec_dict: dict[str, Any],
+                       tasklist_dict: dict[str, Any]) -> None:
+        """Register one task's body in *self.reg* under an isolated name.
+        Delegates to the appropriate helper based on ``task.type``.
+        """
+        if task.type == "harness":
+            self._register_harness(key, task, spec_dict, tasklist_dict)
+        elif task.type == "script":
+            self._register_script(key, task)
+        elif task.type == "command":
+            self._register_command(key, task)
+        elif task.type == "submodule":
+            self._register_submodule(key, task, spec_dict, tasklist_dict)
+        else:
+            raise ValueError(f"Task '{key}': unknown type {task.type!r}")
+    @staticmethod
+    def _resolve_spec_ref(value: str, spec_dict: dict[str, Any]) -> Any:
+        """解析 "{spec.xxx}" 引用。非引用原样返回。"""
+        if isinstance(value, str) and value.startswith("{spec.") and value.endswith("}"):
+            return spec_dict.get(value[len("{spec."):-1])
+        return value
+    @staticmethod
+    def _resolve_constant(token: str, node_key: str,
+                          spec_dict: dict[str, Any],
+                          tasklist_dict: dict[str, Any]) -> Any:
+        """解析常量 token：{spec} → spec JSON，{tasklist} → tasklist JSON，
+        {node} → 当前节点 key。未知 token 抛 ValueError。"""
+        try:
+            if token == "{spec}":
+                return json.dumps(spec_dict, ensure_ascii=False)
+            if token == "{tasklist}":
+                return json.dumps(tasklist_dict, ensure_ascii=False)
+        except TypeError as e:
+            raise ValueError(
+                f"Task '{node_key}': token {token} 含不可 JSON 序列化的值: {e}"
+            ) from e
+        if token == "{node}":
+            return node_key
+        raise ValueError(f"未知常量 token: {token}")
+    def _register_harness(self, key: str, task: TaskDefinition,
+                          spec_dict: dict[str, Any],
+                          tasklist_dict: dict[str, Any]) -> None:
+        """Copy an existing harness config, apply task-level overrides, and
+        register under the isolated name."""
+        assert task.harness is not None  # validated by spec
+        existing = self.reg.harness_config(task.harness)
+        if existing is None:
+            raise ValueError(
+                f"Task '{key}': harness '{task.harness}' not found.  "
+                f"Make sure it was registered via reg.harness()."
+            )
+        # Build a new config with task-level overrides.
+        output_format: OutputFormat | None
+        if task.outputformat is not None:
+            output_format = OutputFormat(**task.outputformat)
+        else:
+            output_format = existing.output_format
+        api_params = dict(existing.api_params)
+        if task.api_params:
+            api_params.update(task.api_params)
+        cfg = HarnessConfig(
+            prompt_core=existing.prompt_core,
+            prompt_modes=dict(existing.prompt_modes),
+            output_format=output_format,
+            notdo=list(task.notdo) if task.notdo is not None else list(existing.notdo),
+            model=task.model if task.model is not None else existing.model,
+            temperature=(
+                task.temperature
+                if task.temperature is not None
+                else existing.temperature
+            ),
+            think=task.think if task.think is not None else existing.think,
+            api_params=api_params,
+        )
+        # 解析常量引用：promptmode 的 "{spec.xxx}" 与 inputs 的常量 token
+        # （{spec}/{tasklist}/{node} 与 {spec.xxx}）均在注册时解析为字面值
+        promptmode = task.promptmode
+        if promptmode is not None:
+            promptmode = self._resolve_spec_ref(promptmode, spec_dict)
+        spec_inputs: dict[str, Any] = {}
+        if task.inputs:
+            for field_name, producer in task.inputs.items():
+                if isinstance(producer, str) and producer in _CONSTANT_TOKENS:
+                    spec_inputs[field_name] = self._resolve_constant(
+                        producer, key, spec_dict, tasklist_dict
+                    )
+                elif isinstance(producer, str) and producer.startswith("{spec."):
+                    resolved = self._resolve_spec_ref(producer, spec_dict)
+                    spec_inputs[field_name] = resolved
+        # 跨节点输入别名：非常量引用的 inputs 把 field 名映射到 producer 节点，
+        # harness body 运行时据此把 producer 输出渲染进 prompt 的 {field} 占位符。
+        input_aliases: dict[str, str] = {}
+        if task.inputs:
+            for field_name, producer in task.inputs.items():
+                if _is_constant_ref(producer):
+                    continue
+                input_aliases[field_name] = producer
+        self.reg.harness(
+            self._isolated(key),
+            cfg,
+            promptmode=promptmode,
+            prompt_extra=task.prompt,
+            spec_inputs=spec_inputs,
+            input_aliases=input_aliases,
+        )
+    def _register_script(self, key: str, task: TaskDefinition) -> None:
+        """Copy an existing script body and register under the isolated name."""
+        assert task.script is not None  # validated by spec
+        if not self.reg.has_body(task.script):
+            raise ValueError(
+                f"Task '{key}': script '{task.script}' not found.  "
+                f"Make sure it was registered via @reg.script()."
+            )
+        orig_body = self.reg.get_body(task.script)
+        self.reg.body(self._isolated(key), orig_body)
+    def _register_command(self, key: str, task: TaskDefinition) -> None:
+        """Copy an existing command config, apply task overrides, register under
+        the isolated name."""
+        assert task.command is not None  # validated by spec
+        existing = self.reg.command_config(task.command)
+        if existing is None:
+            raise ValueError(
+                f"Task '{key}': command '{task.command}' not found.  "
+                f"Make sure it was registered via reg.command()."
+            )
+        self.reg.command(
+            self._isolated(key),
+            existing,
+            timeout=task.timeout,
+            cwd=task.cwd,
+        )
+    def _register_submodule(self, key: str, task: TaskDefinition,
+                            spec_dict: dict[str, Any],
+                            tasklist_dict: dict[str, Any]) -> None:
+        """注册 submodule 节点 body：黑盒嵌入运行子模块（audit=False +
+        persist=False，不进审计/落盘），返回子流程终点输出。"""
+        assert task.submodule is not None  # validated by spec
+        child_ref = self.modules.get(task.submodule)
+        if child_ref is None:
+            raise ValueError(
+                f"Task '{key}': submodule '{task.submodule}' not found.  "
+                f"Make sure it was declared in modules."
+            )
+        if task.outputs:
+            for out_field, child_field in task.outputs.items():
+                if child_field not in child_ref.spec_schema.output:
+                    raise ValueError(
+                        f"Task '{key}': outputs 字段 '{child_field}' 不在 "
+                        f"submodule '{task.submodule}' 的 spec_schema.output 中"
+                    )
+        # 子模块实例：类 → 懒实例化（注入父 client）；实例（loader 加载）→ 复用
+        if isinstance(child_ref, type):
+            child = child_ref(llm_client=self._llm_client)
+        else:
+            child = child_ref
+        # 节点级 LLM 覆盖 → 传播到子模块内部全部 harness
+        overrides: dict[str, Any] = {}
+        for k in ("model", "temperature", "think", "api_params"):
+            v = getattr(task, k)
+            if v is not None:
+                overrides[k] = v
+        # 常量引用（{spec.xxx} / {spec}/{tasklist}/{node}）构建期解析
+        const_inputs: dict[str, Any] = {}
+        if task.inputs:
+            for field_name, producer in task.inputs.items():
+                if isinstance(producer, str) and producer in _CONSTANT_TOKENS:
+                    const_inputs[field_name] = self._resolve_constant(
+                        producer, key, spec_dict, tasklist_dict
+                    )
+                elif isinstance(producer, str) and producer.startswith("{spec."):
+                    const_inputs[field_name] = self._resolve_spec_ref(
+                        producer, spec_dict
+                    )
+        async def body(view: Any) -> Any:
+            spec_input = dict(const_inputs)
+            if task.inputs:
+                for field_name, producer in task.inputs.items():
+                    if _is_constant_ref(producer):
+                        continue
+                    spec_input[field_name] = view[producer].value
+            try:
+                firings = await child.run(
+                    spec_input, audit=False, persist=False,
+                    harness_overrides=overrides,
+                )
+            except SpecValidationError as e:
+                return Failure(
+                    f"submodule '{task.submodule}' spec 校验失败: {e}",
+                    type="infrastructure",
+                )
+            out = firings[-1].output if firings else {}
+            if task.outputs and isinstance(out, dict) and not isinstance(out, Failure):
+                out = {k: out.get(v) for k, v in task.outputs.items()}
+            return out
+        self.reg.body(self._isolated(key), body)