semora 0.1.0__tar.gz

semora-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+
+
+# Local tool/editor state — machine-specific, never pushed.
+.claude/
+.codecanvas/
+.vscode/
+
+
+# Superpowers design/spec scratch — working notes, not project documentation.
+docs/superpowers/
+
+# 로컬 자격증명 — 절대 커밋 금지.
+a.txt
+*.token

semora-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: semora
+Version: 0.1.0
+Summary: Durable multi-agent runtime for Python.
+Project-URL: Homepage, https://github.com/donggyun112/semora
+Project-URL: Source, https://github.com/donggyun112/semora
+Project-URL: Changelog, https://github.com/donggyun112/semora/blob/main/CHANGELOG.md
+Author: donggyun112
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: langchain-core<2,>=1
+Requires-Dist: loguru<1,>=0.7
+Requires-Dist: semora-llm==0.1.0
+Requires-Dist: semora-store==0.1.0
+Provides-Extra: anthropic
+Requires-Dist: langchain-anthropic<2,>=1; extra == 'anthropic'
+Provides-Extra: fork
+Requires-Dist: semora-fork==0.1.0; extra == 'fork'
+Provides-Extra: google
+Requires-Dist: langchain-google-genai<5,>=4; extra == 'google'
+Provides-Extra: openai
+Requires-Dist: langchain-openai<2,>=1; extra == 'openai'
+Provides-Extra: openrouter
+Requires-Dist: langchain-openai<2,>=1; extra == 'openrouter'
+Provides-Extra: permissions
+Requires-Dist: semora-permissions==0.1.0; extra == 'permissions'
+Provides-Extra: postgres
+Requires-Dist: semora-store-pg==0.1.0; extra == 'postgres'
+Provides-Extra: ui
+Requires-Dist: semora-ui==0.1.0; extra == 'ui'
+Provides-Extra: xai
+Requires-Dist: langchain-xai<2,>=1; extra == 'xai'
+Description-Content-Type: text/markdown
+
+# semora
+
+Durable agent runtime for Python. This is the core: contracts, control points, tool
+execution, the orchestrator, the plain `async while` planner, and `AgentRuntime`.
+
+By default `AgentRuntime` drives the planner directly — no orchestrator, no ledger:
+
+```python
+from semora import Agent, AgentRuntime, ChatModel
+
+model = ChatModel(model="gpt-4.1")
+agent = Agent("reviewer", "Reviews repositories", model, tools, system_prompt)
+outcome = await AgentRuntime().run("attempt-42", agent, "inspect this repository")
+```
+
+This path cannot suspend or recover a crashed round. Attach a ledger when those
+guarantees are required:
+
+```python
+from semora import AgentRuntime, MemorySteps
+
+runtime = AgentRuntime(store=MemorySteps())
+outcome = await runtime.run("attempt-42", agent, "inspect this repository")
+```
+
+Policy lives on `Controls` / `ControlPlane` (`on_inputs`, `before_model`, `pre_tool_use`,
+`after_tool_call`, `before_finish`, `on_resume`, `on_suspend`). `before_finish` can refuse
+an ending and send the loop around again.
+
+`semora.builtins.builtin_tools()` supplies `read`, `write`, `edit`, `grep`, `glob`, `Bash`,
+and `web_fetch`. `web_search` is not included. `Bash` stays disabled until
+`ExecToolOptions.allow_list` is set. File and process effects use the `WorkspaceProvider`
+injected by `AgentRuntime` (`semora.workspace`).
+
+Install extras beside it:
+
+| | |
+|---|---|
+| `semora` | the runtime, with in-memory `MemorySteps` |
+| `semora[openai]` | `langchain-openai` |
+| `semora[anthropic]` | `langchain-anthropic` |
+| `semora[google]` | `langchain-google-genai` |
+| `semora[xai]` | `langchain-xai` |
+| `semora[openrouter]` | OpenAI adapter for OpenRouter |
+| `semora[postgres]` | Postgres ledger (`semora_store_pg`) |
+| `semora[permissions]` | permission rule table (`semora_permissions`) |
+| `semora[ui]` | local console (`semora_ui`) |
+
+See the [repository README](../../README.md) for examples.

semora-0.1.0/README.md

@@ -0,0 +1,49 @@
+# semora
+
+Durable agent runtime for Python. This is the core: contracts, control points, tool
+execution, the orchestrator, the plain `async while` planner, and `AgentRuntime`.
+
+By default `AgentRuntime` drives the planner directly — no orchestrator, no ledger:
+
+```python
+from semora import Agent, AgentRuntime, ChatModel
+
+model = ChatModel(model="gpt-4.1")
+agent = Agent("reviewer", "Reviews repositories", model, tools, system_prompt)
+outcome = await AgentRuntime().run("attempt-42", agent, "inspect this repository")
+```
+
+This path cannot suspend or recover a crashed round. Attach a ledger when those
+guarantees are required:
+
+```python
+from semora import AgentRuntime, MemorySteps
+
+runtime = AgentRuntime(store=MemorySteps())
+outcome = await runtime.run("attempt-42", agent, "inspect this repository")
+```
+
+Policy lives on `Controls` / `ControlPlane` (`on_inputs`, `before_model`, `pre_tool_use`,
+`after_tool_call`, `before_finish`, `on_resume`, `on_suspend`). `before_finish` can refuse
+an ending and send the loop around again.
+
+`semora.builtins.builtin_tools()` supplies `read`, `write`, `edit`, `grep`, `glob`, `Bash`,
+and `web_fetch`. `web_search` is not included. `Bash` stays disabled until
+`ExecToolOptions.allow_list` is set. File and process effects use the `WorkspaceProvider`
+injected by `AgentRuntime` (`semora.workspace`).
+
+Install extras beside it:
+
+| | |
+|---|---|
+| `semora` | the runtime, with in-memory `MemorySteps` |
+| `semora[openai]` | `langchain-openai` |
+| `semora[anthropic]` | `langchain-anthropic` |
+| `semora[google]` | `langchain-google-genai` |
+| `semora[xai]` | `langchain-xai` |
+| `semora[openrouter]` | OpenAI adapter for OpenRouter |
+| `semora[postgres]` | Postgres ledger (`semora_store_pg`) |
+| `semora[permissions]` | permission rule table (`semora_permissions`) |
+| `semora[ui]` | local console (`semora_ui`) |
+
+See the [repository README](../../README.md) for examples.

semora-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "semora"
+version = "0.1.0"
+description = "Durable multi-agent runtime for Python."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "donggyun112" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+urls = { Homepage = "https://github.com/donggyun112/semora", Source = "https://github.com/donggyun112/semora", Changelog = "https://github.com/donggyun112/semora/blob/main/CHANGELOG.md" }
+dependencies = [
+  "langchain-core>=1,<2",
+  "loguru>=0.7,<1",
+  "semora-llm==0.1.0",
+  "semora-store==0.1.0",
+]
+# The core: contracts, controls, tool execution, the orchestrator, the engine, and the facade over
+# them. Those are layers of one thing rather than separate products — they share a dependency
+# footprint and nobody installs them apart — so they are subpackages here.
+# `tests/test_packaging.py` keeps them layered, which is the job separate manifests used to do.
+
+[project.optional-dependencies]
+postgres = ["semora-store-pg==0.1.0"]
+permissions = ["semora-permissions==0.1.0"]
+ui = ["semora-ui==0.1.0"]
+fork = ["semora-fork==0.1.0"]
+# Chat models stay LangChain's. These extras only install the provider adapter;
+# `from langchain_openai import ChatOpenAI` is still how a caller constructs one.
+openai = ["langchain-openai>=1,<2"]
+anthropic = ["langchain-anthropic>=1,<2"]
+google = ["langchain-google-genai>=4,<5"]
+xai = ["langchain-xai>=1,<2"]
+# OpenRouter speaks the OpenAI wire. Same adapter, different base URL.
+openrouter = ["langchain-openai>=1,<2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/semora"]
+
+[tool.uv.sources]
+semora-fork = { workspace = true }
+semora-llm = { workspace = true }
+semora-permissions = { workspace = true }
+semora-store = { workspace = true }
+semora-store-pg = { workspace = true }
+semora-ui = { workspace = true }

semora-0.1.0/src/semora/__init__.py

@@ -0,0 +1,60 @@
+"""Semora's public Python package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from semora_llm import ChatModel
+from semora_store import ExecutionContext, MemorySteps
+
+from .contracts import Agent, AgentDefinition, PendingInput, ToolCall, Tools
+from .controls import (
+    Continue,
+    ControlPlane,
+    Controls,
+    Ctx,
+    Deny,
+    FinishPolicy,
+    Halt,
+    Ingress,
+    Permissions,
+    Proceed,
+    ResumeInput,
+    Suspend,
+    gate,
+)
+from .ids import new_run_id
+from .runtime import AgentRuntime, run
+from .workspace import HostWorkspaceProvider
+
+try:
+    __version__ = version("semora")
+except PackageNotFoundError:  # pragma: no cover - source tree without installation
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Agent",
+    "AgentDefinition",
+    "AgentRuntime",
+    "ChatModel",
+    "Continue",
+    "ControlPlane",
+    "Controls",
+    "Ctx",
+    "Deny",
+    "ExecutionContext",
+    "FinishPolicy",
+    "Halt",
+    "HostWorkspaceProvider",
+    "Ingress",
+    "MemorySteps",
+    "PendingInput",
+    "Permissions",
+    "Proceed",
+    "ResumeInput",
+    "Suspend",
+    "ToolCall",
+    "Tools",
+    "__version__",
+    "gate",
+    "new_run_id",
+    "run",
+]

semora-0.1.0/src/semora/background.py

@@ -0,0 +1,156 @@
+"""Process-local registry and result types for agent-launched background work."""
+
+import asyncio
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+__all__ = [
+    "BackgroundResult",
+    "BackgroundTask",
+    "BackgroundTasks",
+    "TaskStatus",
+]
+
+TaskStatus = Literal["running", "done", "error", "cancelled"]
+
+
+@dataclass(frozen=True, slots=True)
+class BackgroundResult:
+    """Result delivered when managed background work settles."""
+
+    task_id: str
+    kind: str
+    label: str
+    content: str
+    is_error: bool = False
+
+    def as_message(self) -> str:
+        """Render the result as a model-visible background notification."""
+        state = "failed" if self.is_error else "completed"
+        header = f'[background {self.kind} "{self.label}" {state}] (task {self.task_id})'
+        return f"{header}\n{self.content}"
+
+
+@dataclass(slots=True)
+class BackgroundTask:
+    """Registered background task and its observable lifecycle state."""
+
+    task_id: str
+    kind: str
+    label: str
+    started_at: float
+    task: asyncio.Task[Any]
+    status: TaskStatus = "running"
+    settled_at: float | None = None
+    read_output: Callable[[], str] | None = None
+
+    def snapshot(self) -> dict[str, Any]:
+        """Return a serializable task status snapshot."""
+        return {
+            "task_id": self.task_id,
+            "kind": self.kind,
+            "label": self.label,
+            "status": self.status,
+            "started_at": self.started_at,
+            **({"settled_at": self.settled_at} if self.settled_at is not None else {}),
+        }
+
+
+@dataclass
+class BackgroundTasks:
+    """Manage process-local background tasks launched by one parent run."""
+
+    max_settled_retained: int = 50
+
+    _tasks: dict[str, BackgroundTask] = field(default_factory=dict, repr=False)
+    _listeners: list[Callable[[str, TaskStatus], None]] = field(default_factory=list, repr=False)
+
+    def register(
+        self,
+        task_id: str,
+        kind: str,
+        label: str,
+        task: asyncio.Task[Any],
+        *,
+        read_output: Callable[[], str] | None = None,
+    ) -> BackgroundTask:
+        """Register a launched task without notifying settlement listeners."""
+        entry = BackgroundTask(
+            task_id=task_id,
+            kind=kind,
+            label=label,
+            started_at=time.time(),
+            task=task,
+            read_output=read_output,
+        )
+        self._tasks[task_id] = entry
+        return entry
+
+    def settle(self, task_id: str, status: TaskStatus) -> None:
+        """Record the first terminal status for a task."""
+        entry = self._tasks.get(task_id)
+        if entry is None or entry.status != "running":
+            return
+        entry.status = status
+        entry.settled_at = time.time()
+        self._prune()
+        self._notify(task_id, status)
+
+    def cancel(self, task_id: str) -> bool:
+        """Cancel a running task and report whether cancellation was applied."""
+        entry = self._tasks.get(task_id)
+        if entry is None or entry.status != "running":
+            return False
+        entry.status = "cancelled"
+        entry.settled_at = time.time()
+        entry.task.cancel()
+        self._prune()
+        self._notify(task_id, "cancelled")
+        return True
+
+    def cancel_all(self) -> int:
+        """Cancel all running tasks and return the number cancelled."""
+        return sum(self.cancel(task_id) for task_id in list(self._tasks))
+
+    def get(self, task_id: str) -> BackgroundTask | None:
+        """Return a task record by identifier."""
+        return self._tasks.get(task_id)
+
+    def status(self, task_id: str) -> TaskStatus | None:
+        """Return a task status by identifier."""
+        entry = self._tasks.get(task_id)
+        return entry.status if entry is not None else None
+
+    def list(self) -> list[dict[str, Any]]:
+        """Return task snapshots in launch order."""
+        return [
+            entry.snapshot()
+            for entry in sorted(self._tasks.values(), key=lambda item: item.started_at)
+        ]
+
+    def subscribe(self, listener: Callable[[str, TaskStatus], None]) -> Callable[[], None]:
+        """Subscribe to task settlements and return an unsubscribe callback."""
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+
+        return unsubscribe
+
+    def _notify(self, task_id: str, status: TaskStatus) -> None:
+        for listener in list(self._listeners):
+            try:
+                listener(task_id, status)
+            except Exception:  # one bad listener must not break settling
+                continue
+
+    def _prune(self) -> None:
+        settled = sorted(
+            (item for item in self._tasks.values() if item.status != "running"),
+            key=lambda item: item.settled_at or 0.0,
+        )
+        for entry in settled[: max(0, len(settled) - self.max_settled_retained)]:
+            del self._tasks[entry.task_id]

semora-0.1.0/src/semora/builtins/__init__.py

@@ -0,0 +1,248 @@
+"""TS-compatible core built-in tool bundle.
+
+The bundle intentionally contains file/process tools plus ``web_fetch``. It does not include
+``web_search``; applications can add their own search provider when they need one.
+"""
+
+from __future__ import annotations
+
+from functools import partial
+from typing import Any
+
+from ..workspace import ToolContext
+from ._exec import exec_is_read_only, exec_tool
+from ._files import edit_tool, read_tool, write_tool
+from ._search import glob_tool, grep_tool
+from ._types import (
+    BuiltinToolState,
+    ExecToolOptions,
+    Handler,
+    WebFetchResponse,
+    WebFetchSummarizer,
+    WebFetchToolOptions,
+    WebFetchTransport,
+    error_result,
+)
+from ._web import UrllibWebFetchTransport, web_fetch_tool
+
+__all__ = [
+    "BuiltinTools",
+    "ExecToolOptions",
+    "UrllibWebFetchTransport",
+    "WebFetchResponse",
+    "WebFetchSummarizer",
+    "WebFetchToolOptions",
+    "WebFetchTransport",
+    "builtin_tools",
+]
+
+
+class BuiltinTools:
+    """Context-aware implementation of the TS sandbox bundle plus ``web_fetch``."""
+
+    def __init__(
+        self,
+        *,
+        context: ToolContext | None = None,
+        exec_options: ExecToolOptions | None = None,
+        web_fetch_options: WebFetchToolOptions | None = None,
+        _state: BuiltinToolState | None = None,
+    ) -> None:
+        """Configure tool policy independently from a turn's workspace session."""
+        self._context = context or ToolContext(workdir=".")
+        self._exec_options = exec_options or ExecToolOptions()
+        self._web_fetch_options = web_fetch_options or WebFetchToolOptions()
+        self._state = _state or BuiltinToolState()
+        self._handlers: dict[str, Handler] = {
+            "read": read_tool,
+            "write": write_tool,
+            "edit": edit_tool,
+            "glob": glob_tool,
+            "grep": grep_tool,
+            "Bash": partial(exec_tool, options=self._exec_options),
+            "web_fetch": partial(web_fetch_tool, options=self._web_fetch_options),
+        }
+        self._definitions = _definitions(self._exec_options.allow_shell)
+
+    async def execute(self, name: str, call_id: str, arguments: Any) -> dict[str, Any]:
+        """Execute a named built-in against the currently bound context."""
+        handler = self._handlers.get(name)
+        if handler is None:
+            return error_result(f"Unknown tool: {name}")
+        return dict(await handler(call_id, arguments, self._context, self._state))
+
+    def get(self, name: str) -> dict[str, Any] | None:
+        """Return one model-visible tool definition."""
+        definition = self._definitions.get(name)
+        return dict(definition) if definition is not None else None
+
+    def list(self) -> list[dict[str, Any]]:
+        """Return the stable core set, deliberately excluding ``web_search``."""
+        return [dict(definition) for definition in self._definitions.values()]
+
+    def get_context(self) -> ToolContext:
+        """Return the immutable execution context currently bound to the tools."""
+        return self._context
+
+    def with_context(self, context: ToolContext) -> BuiltinTools:
+        """Bind a runtime workspace while retaining locks and fetch cache across turns."""
+        return BuiltinTools(
+            context=context,
+            exec_options=self._exec_options,
+            web_fetch_options=self._web_fetch_options,
+            _state=self._state,
+        )
+
+
+def builtin_tools(
+    *,
+    context: ToolContext | None = None,
+    exec_options: ExecToolOptions | None = None,
+    web_fetch_options: WebFetchToolOptions | None = None,
+) -> BuiltinTools:
+    """Create the standard bundle, optionally bound to a caller-managed workspace context."""
+    return BuiltinTools(
+        context=context,
+        exec_options=exec_options,
+        web_fetch_options=web_fetch_options,
+    )
+
+
+def _definitions(allow_shell: bool) -> dict[str, dict[str, Any]]:
+    return {
+        "read": {
+            "name": "read",
+            "description": (
+                "Read a file or directory from the workspace. Text is line-numbered and paged; "
+                "images return inline and Jupyter notebooks return readable cell text."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "offset": {"type": "number"},
+                    "limit": {"type": "number"},
+                    "pages": {"type": "string"},
+                },
+                "required": ["path"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+        "write": {
+            "name": "write",
+            "description": "Create or replace a UTF-8 file inside the workspace.",
+            "parameters": {
+                "type": "object",
+                "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
+                "required": ["path", "content"],
+            },
+            "is_read_only": False,
+            "is_concurrency_safe": False,
+        },
+        "edit": {
+            "name": "edit",
+            "description": "Replace an exact string in a UTF-8 workspace file.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "old_string": {"type": "string"},
+                    "new_string": {"type": "string"},
+                    "replace_all": {"type": "boolean"},
+                },
+                "required": ["path", "old_string", "new_string"],
+            },
+            "is_read_only": False,
+            "is_concurrency_safe": False,
+        },
+        "grep": {
+            "name": "grep",
+            "description": (
+                "Search workspace file contents with ripgrep, falling back to system grep. "
+                "Supports content, files_with_matches, and count output modes."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string"},
+                    "path": {"type": "string"},
+                    "glob": {"type": "string"},
+                    "type": {"type": "string"},
+                    "output_mode": {
+                        "type": "string",
+                        "enum": ["content", "files_with_matches", "count"],
+                    },
+                    "-A": {"type": "number"},
+                    "-B": {"type": "number"},
+                    "-C": {"type": "number"},
+                    "context": {"type": "number"},
+                    "-n": {"type": "boolean"},
+                    "-i": {"type": "boolean"},
+                    "head_limit": {"type": "number"},
+                    "offset": {"type": "number"},
+                    "multiline": {"type": "boolean"},
+                },
+                "required": ["pattern"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+        "glob": {
+            "name": "glob",
+            "description": "Find workspace files by glob pattern with ripgrep.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string"},
+                    "path": {"type": "string"},
+                    "head_limit": {"type": "number"},
+                    "offset": {"type": "number"},
+                },
+                "required": ["pattern"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+        "Bash": {
+            "name": "Bash",
+            "description": (
+                "Execute an allow-listed command in the workspace. "
+                + (
+                    "argv is preferred; shell strings are enabled for pipes and globs."
+                    if allow_shell
+                    else "Shell-string mode is disabled; use argv."
+                )
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "argv": {"type": "array", "items": {"type": "string"}},
+                    "command": {"type": "string"},
+                    "timeoutMs": {"type": "number"},
+                    "cwd": {"type": "string"},
+                    "run_in_background": {"type": "boolean"},
+                },
+            },
+            "is_read_only": exec_is_read_only,
+            "is_concurrency_safe": exec_is_read_only,
+        },
+        "web_fetch": {
+            "name": "web_fetch",
+            "description": (
+                "Fetch an HTTPS URL and return readable content. HTTP is upgraded to HTTPS; "
+                "results are cached by URL and prompt."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "url": {"type": "string"},
+                    "prompt": {"type": "string"},
+                    "max_chars": {"type": "number"},
+                },
+                "required": ["url"],
+            },
+            "is_read_only": True,
+            "is_concurrency_safe": True,
+        },
+    }