pyquipu-application 0.1.0__py3-none-any.whl

pyquipu_application-0.1.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: pyquipu-application
+Version: 0.1.0
+Summary: Core application logic for Quipu, orchestrating engine and runtime.
+Author-email: doucx <doucxldh@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pyquipu-bus~=0.1.0
+Requires-Dist: pyquipu-common~=0.1.0
+Requires-Dist: pyquipu-engine~=0.1.0
+Requires-Dist: pyquipu-interfaces~=0.1.0
+Requires-Dist: pyquipu-runtime~=0.1.0

pyquipu_application-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+quipu/__init__.py,sha256=dyHnnj2etUVMEOCjNbEguf3eMOLeylDaY3b4XcC8kFQ,180
+quipu/application/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quipu/application/controller.py,sha256=Cx2-q0OXy5j8qujw7ER8d-K0FTCeFnN7y56LRVweqtA,7630
+quipu/application/controller.stitcher.yaml,sha256=NH3TehBZEpTmHqULWuRleA9Y3mCyRQbXqDSFUSMHK7o,1641
+quipu/application/factory.py,sha256=qaDiv0GgeZrYMxXulR1S-f6u14bfRd9XAieNhuDpho4,2019
+quipu/application/factory.stitcher.yaml,sha256=pOsTN3wQdZwtlJSQkcamTL60BIgstWIdEt7ul1NgfH0,436
+quipu/application/plugin_manager.py,sha256=tDhjOi8V4e-usllvDcr4m-IAiV_gTkbHeOwN_p3dSmk,1315
+quipu/application/plugin_manager.stitcher.yaml,sha256=1Azs30JFpr8WyGp89l3csiFKGyeGjZHCXJTQg0jv_18,224
+quipu/application/utils.py,sha256=g0Hf5vy3hp3djUgRpBSmcSTu0r2aYKpmM_ftSofuwbo,403
+quipu/application/utils.stitcher.yaml,sha256=me8Ukxc33Vt199rF4eJw99rs8yDtoj92cRA1MMig7rA,94
+pyquipu_application-0.1.0.dist-info/METADATA,sha256=ZaqSrA-T3LqyjxCMhziK37l2k5zf0-9hs1zC0IDdtDI,518
+pyquipu_application-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pyquipu_application-0.1.0.dist-info/RECORD,,

pyquipu_application-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

quipu/__init__.py

@@ -0,0 +1,3 @@
+# This allows this package to coexist with other distribution packages
+# that contribute to the 'quipu' namespace.
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

quipu/application/controller.py

@@ -0,0 +1,214 @@
+import logging
+import re
+from pathlib import Path
+from typing import Callable, Dict, List
+
+from quipu.acts import register_core_acts
+from quipu.engine.state_machine import Engine
+from quipu.interfaces.exceptions import ExecutionError as CoreExecutionError
+from quipu.interfaces.exceptions import OperationCancelledError
+from quipu.interfaces.result import QuipuResult
+from quipu.runtime.executor import Executor
+from quipu.runtime.parser import detect_best_parser, get_parser
+
+from .factory import create_engine
+from .plugin_manager import PluginManager
+
+logger = logging.getLogger(__name__)
+
+
+def get_available_acts(work_dir: Path) -> Dict[str, str]:
+    # A dummy confirmation handler is used as it's not required for listing.
+    # Yolo=True ensures no interactive prompts can be triggered.
+    executor = Executor(
+        root_dir=work_dir,
+        yolo=True,
+        confirmation_handler=lambda diff, prompt: True,
+    )
+    register_core_acts(executor)
+    PluginManager().load_from_sources(executor, work_dir)
+    return executor.get_registered_acts()
+
+
+# 定义 ConfirmationHandler 类型别名: (diff_lines, prompt) -> bool
+# 注意: Executor 期望如果不确认则抛出异常，或者返回 False (取决于 Executor 实现)。
+# 为了保持与 CLI 行为一致，调用方传入的 handler 应该在用户拒绝时抛出 OperationCancelledError。
+ConfirmationHandler = Callable[[List[str], str], bool]
+
+
+class QuipuApplication:
+    def __init__(self, work_dir: Path, confirmation_handler: ConfirmationHandler, yolo: bool = False):
+        self.work_dir = work_dir
+        self.confirmation_handler = confirmation_handler
+        self.yolo = yolo
+        self.engine: Engine = create_engine(work_dir)
+        logger.info(f"Operation boundary set to: {self.work_dir}")
+
+    def _prepare_workspace(self) -> str:
+        current_hash = self.engine.git_db.get_tree_hash()
+
+        # 1. 正常 Clean: current_node 存在且与当前 hash 一致
+        is_node_clean = (self.engine.current_node is not None) and (
+            self.engine.current_node.output_tree == current_hash
+        )
+
+        # 2. 创世 Clean: 历史为空 且 当前是空树 (即没有任何文件被追踪)
+        EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+        is_genesis_clean = (not self.engine.history_graph) and (current_hash == EMPTY_TREE_HASH)
+
+        is_clean = is_node_clean or is_genesis_clean
+
+        if not is_clean:
+            self.engine.capture_drift(current_hash)
+
+        if self.engine.current_node:
+            return self.engine.current_node.output_tree
+        else:
+            return current_hash
+
+    def _setup_executor(self) -> Executor:
+        executor = Executor(
+            root_dir=self.work_dir,
+            yolo=self.yolo,
+            confirmation_handler=self.confirmation_handler,
+        )
+
+        # 加载核心 acts
+        register_core_acts(executor)
+
+        # 加载外部插件
+        plugin_manager = PluginManager()
+        plugin_manager.load_from_sources(executor, self.work_dir)
+
+        return executor
+
+    def run(self, content: str, parser_name: str) -> QuipuResult:
+        # --- Phase 1 & 2: Perception & Decision (Lazy Capture) ---
+        input_tree_hash = self._prepare_workspace()
+
+        # --- Phase 3: Action (Execution) ---
+        # 3.1 Parser
+        final_parser_name = parser_name
+        if parser_name == "auto":
+            final_parser_name = detect_best_parser(content)
+            if final_parser_name != "backtick":
+                logger.info(f"🔍 自动检测到解析器: {final_parser_name}")
+
+        parser = get_parser(final_parser_name)
+        statements = parser.parse(content)
+
+        if not statements:
+            return QuipuResult(
+                success=True,  # No failure, just nothing to do
+                exit_code=0,
+                message="axon.warning.noStatements",
+                msg_kwargs={"parser": final_parser_name},
+            )
+
+        # 3.2 Executor Setup
+        executor = self._setup_executor()
+
+        # 3.3 Execute
+        executor.execute(statements)
+
+        # --- Phase 4: Recording (Plan Crystallization) ---
+        final_summary = None
+        # 优先级 1: 从 Markdown 内容中提取 # 标题
+        title_match = re.search(r"^\s*#{1,6}\s+(.*)", content, re.MULTILINE)
+        if title_match:
+            final_summary = title_match.group(1).strip()
+        # 优先级 2: 从第一个 act 指令生成摘要
+        elif statements:
+            final_summary = executor.summarize_statement(statements[0])
+
+        output_tree_hash = self.engine.git_db.get_tree_hash()
+
+        self.engine.create_plan_node(
+            input_tree=input_tree_hash,
+            output_tree=output_tree_hash,
+            plan_content=content,
+            summary_override=final_summary,
+        )
+
+        return QuipuResult(success=True, exit_code=0, message="run.success")
+
+
+def run_quipu(
+    content: str,
+    work_dir: Path,
+    confirmation_handler: ConfirmationHandler,
+    parser_name: str = "auto",
+    yolo: bool = False,
+) -> QuipuResult:
+    app = None
+    try:
+        app = QuipuApplication(work_dir=work_dir, confirmation_handler=confirmation_handler, yolo=yolo)
+        return app.run(content=content, parser_name=parser_name)
+
+    except OperationCancelledError as e:
+        logger.info(f"🚫 操作已取消: {e}")
+        return QuipuResult(
+            success=False, exit_code=2, message="run.error.cancelled", msg_kwargs={"error": str(e)}, error=e
+        )
+
+    except CoreExecutionError as e:
+        logger.error(f"❌ 操作失败: {e}")
+        return QuipuResult(
+            success=False, exit_code=1, message="run.error.execution", msg_kwargs={"error": str(e)}, error=e
+        )
+
+    except Exception as e:
+        logger.error(f"运行时错误: {e}", exc_info=True)
+        return QuipuResult(
+            success=False, exit_code=1, message="run.error.system", msg_kwargs={"error": str(e)}, error=e
+        )
+    finally:
+        # 确保无论成功或失败，引擎资源都被关闭
+        if app and hasattr(app, "engine") and app.engine:
+            app.engine.close()
+
+
+def run_stateless_plan(
+    content: str,
+    work_dir: Path,
+    confirmation_handler: ConfirmationHandler,
+    parser_name: str = "auto",
+    yolo: bool = False,
+) -> QuipuResult:
+    try:
+        executor = Executor(
+            root_dir=work_dir,
+            yolo=yolo,
+            confirmation_handler=confirmation_handler,
+        )
+        register_core_acts(executor)
+        PluginManager().load_from_sources(executor, work_dir)
+
+        final_parser_name = parser_name
+        if parser_name == "auto":
+            final_parser_name = detect_best_parser(content)
+
+        parser = get_parser(final_parser_name)
+        statements = parser.parse(content)
+
+        if not statements:
+            return QuipuResult(
+                success=True,
+                exit_code=0,
+                message="axon.warning.noStatements",
+                msg_kwargs={"parser": final_parser_name},
+            )
+
+        executor.execute(statements)
+        return QuipuResult(success=True, exit_code=0, message="axon.success")
+
+    except CoreExecutionError as e:
+        logger.error(f"❌ 操作失败: {e}")
+        return QuipuResult(
+            success=False, exit_code=1, message="run.error.execution", msg_kwargs={"error": str(e)}, error=e
+        )
+    except Exception as e:
+        logger.error(f"运行时错误: {e}", exc_info=True)
+        return QuipuResult(
+            success=False, exit_code=1, message="run.error.system", msg_kwargs={"error": str(e)}, error=e
+        )

quipu/application/controller.stitcher.yaml

@@ -0,0 +1,41 @@
+"QuipuApplication": |-
+  封装了 Quipu 核心业务流程的高层应用对象。
+  负责协调 Engine, Parser, Executor。
+"QuipuApplication._prepare_workspace": |-
+  检查并准备工作区，处理状态漂移。
+  返回执行前的 input_tree_hash。
+"QuipuApplication._setup_executor": |-
+  创建、配置并返回一个 Executor 实例，并注入确认处理器。
+"QuipuApplication.run": |-
+  执行一个完整的 Plan。
+"run_quipu": |-
+  Quipu 核心业务逻辑的入口包装器。
+
+  实例化并运行 QuipuApplication，捕获所有异常并转化为 QuipuResult。
+  确保资源被安全释放。
+get_available_acts: |-
+  Statelessly discovers and returns all available acts.
+
+  This function initializes a temporary, stateless executor to discover
+  core acts and acts from plugins found relative to the working directory.
+
+  Args:
+      work_dir: The directory from which to discover project-level plugins.
+
+  Returns:
+      A dictionary mapping act names to their docstrings.
+run_stateless_plan: |-
+  Executes a plan in a stateless manner, bypassing the Quipu engine.
+
+  This function sets up a temporary executor, loads plugins, parses the content,
+  and executes the statements against the specified working directory.
+
+  Args:
+      content: The string content of the plan to execute.
+      work_dir: The root directory for the execution.
+      confirmation_handler: A callable to handle user confirmations.
+      parser_name: The name of the parser to use ('auto' by default).
+      yolo: If True, skips all confirmation prompts.
+
+  Returns:
+      A QuipuResult object indicating the outcome of the execution.

quipu/application/factory.py

@@ -0,0 +1,56 @@
+import logging
+from pathlib import Path
+
+from quipu.engine.config import ConfigManager
+from quipu.engine.git_db import GitDB
+from quipu.engine.git_object_storage import GitObjectHistoryReader, GitObjectHistoryWriter
+from quipu.engine.state_machine import Engine
+
+from .utils import find_git_repository_root
+
+# 迟延导入以避免循环依赖
+try:
+    from quipu.engine.sqlite_db import DatabaseManager
+    from quipu.engine.sqlite_storage import SQLiteHistoryReader, SQLiteHistoryWriter
+except ImportError:
+    DatabaseManager = None
+    SQLiteHistoryWriter = None
+    SQLiteHistoryReader = None
+
+
+logger = logging.getLogger(__name__)
+
+
+def create_engine(work_dir: Path, lazy: bool = False) -> Engine:
+    project_root = find_git_repository_root(work_dir) or work_dir
+    config = ConfigManager(project_root)
+    storage_type = config.get("storage.type", "git_object")
+    logger.debug(f"Engine factory configured with storage type: '{storage_type}'")
+    git_db = GitDB(project_root)
+    db_manager = None
+
+    # 默认和备用后端
+    reader = GitObjectHistoryReader(git_db)
+    writer = GitObjectHistoryWriter(git_db)
+
+    if storage_type == "sqlite":
+        if not DatabaseManager or not SQLiteHistoryWriter or not SQLiteHistoryReader:
+            raise ImportError("SQLite dependencies could not be loaded. Please check your installation.")
+
+        logger.debug("Using SQLite storage format for reads and writes.")
+        db_manager = DatabaseManager(project_root)
+        db_manager.init_schema()
+
+        # 切换到 SQLite 后端
+        reader = SQLiteHistoryReader(db_manager=db_manager, git_db=git_db)
+        writer = SQLiteHistoryWriter(git_writer=writer, db_manager=db_manager)
+
+    elif storage_type != "git_object":
+        raise NotImplementedError(f"Storage type '{storage_type}' is not supported.")
+
+    # 将所有资源注入 Engine
+    engine = Engine(project_root, db=git_db, reader=reader, writer=writer, db_manager=db_manager)
+    if not lazy:
+        engine.align()
+
+    return engine

quipu/application/factory.stitcher.yaml

@@ -0,0 +1,10 @@
+"create_engine": |-
+  实例化完整的 Engine 堆栈。
+
+  会自动向上查找项目根目录 (Git Root) 来初始化 Engine。
+  此工厂由配置驱动，以决定使用何种存储后端。
+
+  Args:
+      work_dir: 操作的工作区目录。
+      lazy: 如果为 True，则不立即加载完整的历史图谱 (不调用 align)。
+            这对于需要快速启动并按需加载数据的场景 (如 UI) 至关重要。

quipu/application/plugin_manager.py

@@ -0,0 +1,40 @@
+import os
+from pathlib import Path
+
+from quipu.runtime.executor import Executor
+from quipu.runtime.plugin_loader import load_plugins
+
+from .utils import find_git_repository_root
+
+
+class PluginManager:
+    def load_from_sources(self, executor: Executor, work_dir: Path):
+        plugin_sources = []
+
+        # 优先级由低到高添加，后面的会覆盖前面的
+        # 1. User Home (Lowest priority)
+        home_acts = Path.home() / ".quipu" / "acts"
+        plugin_sources.append(("🏠 Global", home_acts))
+
+        # 2. Config / Env
+        env_path = os.getenv("AXON_EXTRA_ACTS_DIR")
+        if env_path:
+            plugin_sources.append(("🔧 Env", Path(env_path)))
+
+        # 3. Project Root (Highest priority)
+        project_root_for_plugins = find_git_repository_root(work_dir)
+        if project_root_for_plugins:
+            proj_acts = project_root_for_plugins / ".quipu" / "acts"
+            plugin_sources.append(("📦 Project", proj_acts))
+
+        seen_paths = set()
+        for label, path in plugin_sources:
+            if not path.exists() or not path.is_dir():
+                continue
+
+            resolved_path = path.resolve()
+            if resolved_path in seen_paths:
+                continue
+
+            load_plugins(executor, path)
+            seen_paths.add(resolved_path)

quipu/application/plugin_manager.stitcher.yaml

@@ -0,0 +1,5 @@
+"PluginManager": |-
+  负责发现、加载和注册外部插件。
+"PluginManager.load_from_sources": |-
+  按照层级顺序加载外部插件，高优先级会覆盖低优先级。
+  优先级顺序: Project > Env > Home

quipu/application/utils.py

@@ -0,0 +1,16 @@
+import logging
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+def find_git_repository_root(start_path: Path) -> Optional[Path]:
+    try:
+        current = start_path.resolve()
+        for parent in [current] + list(current.parents):
+            if (parent / ".git").exists():
+                return parent
+    except Exception:
+        pass
+    return None

quipu/application/utils.stitcher.yaml

@@ -0,0 +1,2 @@
+"find_git_repository_root": |-
+  向上递归查找包含 .git 的目录作为项目根目录