rorchestra 0.1.0__tar.gz

rorchestra-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: rorchestra
+Version: 0.1.0
+Summary: Roblox/Luau AI orchestration system for codebase understanding and scoped edit generation
+License: MIT
+Keywords: roblox,luau,ai,orchestration,gemini
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: alembic>=1.12
+Requires-Dist: tiktoken>=0.5
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: rich>=13.0
+Requires-Dist: prompt_toolkit>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# Roblox/Luau AI Orchestration System
+
+A Python orchestration layer that maintains hierarchical memory of a Rojo/Luau codebase, assembles compact context packets, and dispatches Gemini CLI workers for scoped code edits.
+
+## Quick Start
+
+```bash
+cd orchestrator
+pip install -e ".[dev]"
+
+# Ingest a Rojo project
+python -m app.main ingest C:\path\to\your\rojo\project
+
+# Generate memory summaries
+python -m app.main summarize --repo-id 1
+
+# Request an edit
+python -m app.main edit "Add error handling to the data save module" --repo-id 1 --scope DataManager --side server
+
+# Validate a patch
+python -m app.main validate --task-id 1
+
+# Check live Studio state (uncertainty-triggered)
+python -m app.main check ui_existence StarterGui.ScreenGui.MainHUD
+
+# View system status
+python -m app.main status
+
+# Enter the interactive REPL (Rorchestra)
+python -m app.rochester
+# Inside the REPL, you can use:
+# /edit "description"  -> Propose an edit
+# /apply <id>          -> Apply a patch and rebuild memory cascade
+# /mcp                 -> Check connected MCP servers and statuses
+```
+
+## Architecture
+
+| Layer | Purpose |
+|---|---|
+| **Adapters** | Rojo, luau-lsp, Gemini CLI, MCP dispatcher |
+| **Services** | Ingest, graph, memory, summarization, packets, workers, validation, MCP |
+| **Policies** | Safety gates, MCP trigger policy |
+| **Telemetry** | JSONL event log |
+| **Storage** | SQLite (ORM), file-based artifact store |
+
+## MCP Integration
+
+Uses a **canonical capability dispatcher** that routes through:
+- **Primary**: Official Roblox Studio MCP
+- **Fallback**: Community robloxstudio-mcp (filtered toolset)
+
+Raw MCP output is stored out-of-band in `artifacts/mcp_raw/` — never injected into planner context.
+
+## Memory Model
+
+Memory records are **invalidation-driven**, not time-based. A record is only stale when its source files change:
+- Accepted patches trigger `invalidate_by_file()`
+- Stale scopes are re-summarised on demand via `summarize`
+
+## Requirements
+
+- Python 3.11+
+- Rojo (on PATH)
+- luau-lsp (optional, for static validation)
+- Gemini CLI (for worker invocations and summarisation)

rorchestra-0.1.0/README.md

@@ -0,0 +1,66 @@
+# Roblox/Luau AI Orchestration System
+
+A Python orchestration layer that maintains hierarchical memory of a Rojo/Luau codebase, assembles compact context packets, and dispatches Gemini CLI workers for scoped code edits.
+
+## Quick Start
+
+```bash
+cd orchestrator
+pip install -e ".[dev]"
+
+# Ingest a Rojo project
+python -m app.main ingest C:\path\to\your\rojo\project
+
+# Generate memory summaries
+python -m app.main summarize --repo-id 1
+
+# Request an edit
+python -m app.main edit "Add error handling to the data save module" --repo-id 1 --scope DataManager --side server
+
+# Validate a patch
+python -m app.main validate --task-id 1
+
+# Check live Studio state (uncertainty-triggered)
+python -m app.main check ui_existence StarterGui.ScreenGui.MainHUD
+
+# View system status
+python -m app.main status
+
+# Enter the interactive REPL (Rorchestra)
+python -m app.rochester
+# Inside the REPL, you can use:
+# /edit "description"  -> Propose an edit
+# /apply <id>          -> Apply a patch and rebuild memory cascade
+# /mcp                 -> Check connected MCP servers and statuses
+```
+
+## Architecture
+
+| Layer | Purpose |
+|---|---|
+| **Adapters** | Rojo, luau-lsp, Gemini CLI, MCP dispatcher |
+| **Services** | Ingest, graph, memory, summarization, packets, workers, validation, MCP |
+| **Policies** | Safety gates, MCP trigger policy |
+| **Telemetry** | JSONL event log |
+| **Storage** | SQLite (ORM), file-based artifact store |
+
+## MCP Integration
+
+Uses a **canonical capability dispatcher** that routes through:
+- **Primary**: Official Roblox Studio MCP
+- **Fallback**: Community robloxstudio-mcp (filtered toolset)
+
+Raw MCP output is stored out-of-band in `artifacts/mcp_raw/` — never injected into planner context.
+
+## Memory Model
+
+Memory records are **invalidation-driven**, not time-based. A record is only stale when its source files change:
+- Accepted patches trigger `invalidate_by_file()`
+- Stale scopes are re-summarised on demand via `summarize`
+
+## Requirements
+
+- Python 3.11+
+- Rojo (on PATH)
+- luau-lsp (optional, for static validation)
+- Gemini CLI (for worker invocations and summarisation)

rorchestra-0.1.0/app/__init__.py

@@ -0,0 +1 @@
+# Roblox/Luau AI Orchestration System

rorchestra-0.1.0/app/adapters/gemini_cli.py

@@ -0,0 +1,272 @@
+"""
+Gemini CLI adapter — subprocess wrapper for standalone and subagent invocations.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from app.config import settings
+from app.models.schemas import WorkerResult
+from app.storage.artifacts import save_artifact
+
+# On Windows, .cmd wrappers (e.g. gemini.cmd) need shell=True
+_SHELL = sys.platform == "win32"
+
+# Lines of noise that Gemini CLI appends to stdout
+_NOISE_PREFIXES = [
+    "MCP issues detected.",
+    "Run /mcp list for status.",
+    "Loaded cached credentials.",
+    "ClearcutLogger:",
+    "Error flushing log events:",
+    "[MESSAGE_BUS]",
+    "Flushing log events to Clearcut.",
+]
+
+# Patterns that indicate Node.js stack trace lines (from node-pty, etc.)
+_NOISE_PATTERNS = [
+    "at Module._compile",
+    "at Object..js",
+    "at Module.load",
+    "at Function._load",
+    "at TracingChannel.traceSync",
+    "at wrapModuleLoad",
+    "at Function.executeUserEntryPoint",
+    "at node:internal/",
+    "conpty_console_list_agent.js",
+    "Node.js v",
+]
+
+
+import re
+
+
+def _strip_cli_noise(text: str) -> str:
+    """Strip Gemini CLI noise from stdout."""
+    lines = text.split("\n")
+    cleaned = []
+    for line in lines:
+        stripped = line.strip()
+        if any(stripped.startswith(p) for p in _NOISE_PREFIXES):
+            continue
+        if any(p in stripped for p in _NOISE_PATTERNS):
+            continue
+        cleaned.append(line)
+    return "\n".join(cleaned).strip()
+
+
+def _parse_json_output(raw: str) -> tuple[str, int, int]:
+    """
+    Parse Gemini CLI ``--output-format json`` output.
+
+    Handles multiple output formats:
+      1. Single JSON object: {"session_id": ..., "response": "...", "stats": {...}}
+      2. NDJSON (one JSON object per line) with candidates/parts
+      3. Mixed output with JSON embedded in noise lines
+
+    Returns (response_text, input_tokens, output_tokens).
+    """
+    text_parts: list[str] = []
+    input_tokens = 0
+    output_tokens = 0
+
+    # --- Strategy 1: Try parsing the entire output as a single JSON object ---
+    stripped = raw.strip()
+    try:
+        obj = json.loads(stripped)
+        if isinstance(obj, dict):
+            # New format: {"session_id": ..., "response": "text", "stats": {...}}
+            if "response" in obj and isinstance(obj["response"], str):
+                text_parts.append(obj["response"])
+
+                # Extract tokens from stats.models
+                stats = obj.get("stats", {})
+                for model_info in stats.get("models", {}).values():
+                    tokens = model_info.get("tokens", {})
+                    input_tokens += tokens.get("input", 0) or tokens.get("prompt", 0)
+                    output_tokens += tokens.get("candidates", 0)
+
+                return "".join(text_parts), input_tokens, output_tokens
+
+            # Older format: top-level "result" key
+            if "result" in obj and isinstance(obj["result"], str):
+                text_parts.append(obj["result"])
+                return "".join(text_parts), input_tokens, output_tokens
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    # --- Strategy 2: NDJSON (one JSON object per line) ---
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        if not isinstance(obj, dict):
+            continue
+
+        # Extract text from candidates/parts (Gemini API format)
+        for candidate in obj.get("candidates", []):
+            content = candidate.get("content", {})
+            for part in content.get("parts", []):
+                if "text" in part:
+                    text_parts.append(part["text"])
+
+        # Check top-level text keys
+        if "response" in obj and isinstance(obj["response"], str):
+            text_parts.append(obj["response"])
+        elif "result" in obj and isinstance(obj["result"], str):
+            text_parts.append(obj["result"])
+
+        # Extract token counts
+        usage = obj.get("usageMetadata", {})
+        if usage:
+            input_tokens += usage.get("promptTokenCount", 0)
+            output_tokens += usage.get("candidatesTokenCount", 0)
+
+        model_usage = obj.get("modelUsage", {})
+        if model_usage:
+            input_tokens += model_usage.get("inputTokens", 0)
+            output_tokens += model_usage.get("outputTokens", 0)
+
+        # Stats block
+        stats = obj.get("stats", {})
+        for model_info in stats.get("models", {}).values():
+            tokens = model_info.get("tokens", {})
+            input_tokens += tokens.get("input", 0) or tokens.get("prompt", 0)
+            output_tokens += tokens.get("candidates", 0)
+
+    response_text = "".join(text_parts) if text_parts else raw
+    return response_text, input_tokens, output_tokens
+
+
+def invoke_standalone(
+    prompt: str,
+    *,
+    allowed_tools: list[str] | None = None,
+    timeout: int | None = None,
+    cwd: str | None = None,
+    debug: bool = False,
+    no_mcp: bool = False,
+) -> WorkerResult:
+    """
+    Launch a fresh Gemini CLI process with a one-shot prompt.
+
+    The prompt is passed via stdin so it can be arbitrarily long.
+    Uses ``-p`` for proper headless mode and ``--output-format json``
+    for structured token usage.
+
+    no_mcp: If True, blocks MCP server initialization via
+            --allowed-mcp-server-names (faster startup).
+    """
+    timeout = timeout or settings.worker_timeout_secs
+    cmd = [
+        settings.gemini_cli_bin,
+        "--output-format", "json",
+    ]
+
+    if allowed_tools:
+        # Auto-approve all tool usage in headless worker mode
+        cmd += ["--yolo"]
+
+    # Block MCP if requested or if using allowed_tools (workers don't need MCP)
+    if no_mcp or allowed_tools:
+        cmd += ["--allowed-mcp-server-names", "_no_mcp_"]
+
+    if debug:
+        cmd += ["--debug"]
+
+    t0 = time.monotonic()
+    try:
+        result = subprocess.run(
+            cmd,
+            input=prompt,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=cwd,
+            shell=_SHELL,
+            encoding="utf-8",
+            env={**os.environ, "GEMINI_CLI_HEADLESS": "1"},
+        )
+        elapsed = time.monotonic() - t0
+
+        # Parse JSON output for text + token counts
+        response_text, in_tok, out_tok = _parse_json_output(result.stdout)
+
+        # Store transcript
+        transcript_ref = save_artifact(
+            "transcripts",
+            "gemini_standalone",
+            {
+                "prompt_preview": prompt[:500],
+                "stdout": result.stdout[-2000:],
+                "stderr": result.stderr[-500:],
+                "exit_code": result.returncode,
+                "input_tokens": in_tok,
+                "output_tokens": out_tok,
+            },
+        )
+
+        # Strip CLI noise from the parsed response
+        clean_stdout = _strip_cli_noise(response_text)
+
+        return WorkerResult(
+            worker_type="gemini_standalone",
+            exit_code=result.returncode,
+            stdout=clean_stdout,
+            stderr=result.stderr,
+            transcript_ref=str(transcript_ref),
+            elapsed_secs=elapsed,
+            input_tokens=in_tok,
+            output_tokens=out_tok,
+        )
+
+    except subprocess.TimeoutExpired:
+        elapsed = time.monotonic() - t0
+        return WorkerResult(
+            worker_type="gemini_standalone",
+            exit_code=-1,
+            stderr=f"Timed out after {timeout}s",
+            elapsed_secs=elapsed,
+        )
+
+
+def invoke_subagent(
+    agent_name: str,
+    context: str,
+    *,
+    agents_dir: Path | None = None,
+    timeout: int | None = None,
+    cwd: str | None = None,
+    no_mcp: bool = True,
+) -> WorkerResult:
+    """
+    Invoke a Gemini CLI subagent by name.
+
+    The agent Markdown definition is expected at
+    ``<agents_dir>/<agent_name>.md``.
+
+    no_mcp: Blocks MCP server init by default for faster startup.
+    """
+    timeout = timeout or settings.worker_timeout_secs
+
+    # Build the prompt that tells Gemini to use the subagent
+    prompt = f"@{agent_name} {context}"
+
+    return invoke_standalone(
+        prompt,
+        timeout=timeout,
+        cwd=cwd,
+        no_mcp=no_mcp,
+    )

rorchestra-0.1.0/app/adapters/luau_lsp.py

@@ -0,0 +1,94 @@
+"""
+luau-lsp adapter — run standalone analysis for symbols, diagnostics,
+and references using ``luau-lsp analyze``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from app.config import settings
+
+
+def run_analyze(
+    repo_root: Path,
+    sourcemap_path: Path | None = None,
+    *,
+    target_files: list[Path] | None = None,
+) -> dict[str, Any]:
+    """
+    Run ``luau-lsp analyze`` and parse its JSON diagnostic output.
+
+    Returns::
+
+        {
+            "diagnostics": [ { "file": ..., "severity": ..., "message": ..., ... } ],
+            "raw_stderr": "..."
+        }
+    """
+    cmd = [settings.luau_lsp_bin, "analyze"]
+
+    if sourcemap_path and sourcemap_path.exists():
+        cmd += ["--sourcemap", str(sourcemap_path)]
+
+    if target_files:
+        cmd += [str(f) for f in target_files]
+    else:
+        cmd.append(str(repo_root))
+
+    import re
+    result = subprocess.run(cmd, cwd=str(repo_root), capture_output=True, text=True)
+
+    diagnostics: list[dict[str, Any]] = []
+
+    # Strategy 1: Parse stdout as JSON lines (if --formatter=json is used or emits JSON)
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            diagnostics.append(json.loads(line))
+        except json.JSONDecodeError:
+            pass
+
+    # Strategy 2: Parse stderr text format: file(line,col-col): severity: message
+    _DIAG_PATTERN = re.compile(
+        r"^(.+?)\((\d+),(\d+)(?:-\d+)?\):\s*(Error|Warning|Information)\s*[:\-]\s*(.+)$",
+        re.IGNORECASE,
+    )
+    for line in result.stderr.splitlines():
+        line = line.strip()
+        m = _DIAG_PATTERN.match(line)
+        if m:
+            diagnostics.append({
+                "file": m.group(1).strip(),
+                "line": int(m.group(2)),
+                "col": int(m.group(3)),
+                "severity": m.group(4).capitalize(),
+                "message": m.group(5).strip(),
+            })
+
+    return {
+        "diagnostics": diagnostics,
+        "raw_stderr": result.stderr,
+        "exit_code": result.returncode,
+    }
+
+
+def check_patch(
+    repo_root: Path,
+    patched_file: Path,
+    sourcemap_path: Path | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Run analysis on a single patched file and return only *new* diagnostics.
+    """
+    output = run_analyze(
+        repo_root,
+        sourcemap_path,
+        target_files=[patched_file],
+    )
+    return output["diagnostics"]

rorchestra-0.1.0/app/adapters/roblox_mcp.py

@@ -0,0 +1,163 @@
+"""
+Canonical MCP capability dispatcher.
+
+Implements the routing table from the design doc:
+  primary → Roblox_Studio tools
+  fallback → robloxstudio-mcp tools
+
+Raw MCP output is stored in the artifact store.
+Only compact ValidationArtifact-shaped dicts are returned.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+from app.storage.artifacts import save_artifact
+
+
+# ── Capability Routing Table ──────────────────────────────────────────────
+
+# Each entry: canonical_name → (primary_tool, fallback_tool)
+# Tool names match the MCP tool names from the design doc.
+CAPABILITY_MAP: dict[str, tuple[str, str | None]] = {
+    "list_studios": ("Roblox_Studio.list_roblox_studios", None),
+    "set_active_studio": ("Roblox_Studio.set_active_studio", None),
+    "search_tree": (
+        "Roblox_Studio.search_game_tree",
+        "robloxstudio-mcp.get_project_structure",
+    ),
+    "inspect_instance": (
+        "Roblox_Studio.inspect_instance",
+        "robloxstudio-mcp.get_instance_properties",
+    ),
+    "read_script": (
+        "Roblox_Studio.script_read",
+        "robloxstudio-mcp.get_script_source",
+    ),
+    "search_scripts": (
+        "Roblox_Studio.script_grep",
+        "robloxstudio-mcp.grep_scripts",
+    ),
+    "playtest_control": (
+        "Roblox_Studio.start_stop_play",
+        "robloxstudio-mcp.start_playtest",
+    ),
+    "playtest_logs": (
+        "Roblox_Studio.get_console_output",
+        "robloxstudio-mcp.get_playtest_output",
+    ),
+    "edit_script_bounded": (
+        "Roblox_Studio.multi_edit",
+        "robloxstudio-mcp.edit_script_lines",
+    ),
+    "execute_validation_luau": (
+        "Roblox_Studio.execute_luau",
+        None,  # robloxstudio-mcp.execute_luau only if explicitly allowed
+    ),
+    "get_class_metadata": (
+        "robloxstudio-mcp.get_class_info",
+        None,  # could fall back to docs MCP
+    ),
+}
+
+
+# ── Dispatcher ────────────────────────────────────────────────────────────
+
+
+class MCPDispatcher:
+    """
+    Routes canonical capability calls to the correct MCP tool,
+    with automatic fallback and raw-output isolation.
+
+    In the MVP, the actual MCP calls are delegated to callback functions
+    that the orchestrator registers.  This keeps the dispatcher decoupled
+    from the transport (subprocess, HTTP, direct MCP client, etc.).
+    """
+
+    def __init__(self) -> None:
+        # tool_name → callable that actually executes the MCP tool
+        self._executors: dict[str, Callable[..., Any]] = {}
+
+    def register_executor(self, tool_name: str, fn: Callable[..., Any]) -> None:
+        """Register a function that can execute the given raw MCP tool."""
+        self._executors[tool_name] = fn
+
+    def call(
+        self,
+        capability: str,
+        params: dict[str, Any] | None = None,
+        *,
+        allow_fallback: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Invoke a canonical capability.
+
+        1. Try the primary tool.
+        2. If it fails and a fallback exists, try the fallback.
+        3. Store raw output as an artifact.
+        4. Return a compact result dict.
+        """
+        if capability not in CAPABILITY_MAP:
+            return {
+                "status": "error",
+                "error": f"Unknown capability: {capability}",
+            }
+
+        primary, fallback = CAPABILITY_MAP[capability]
+        params = params or {}
+
+        # Try primary
+        result = self._try_tool(primary, params)
+        if result is not None:
+            self._store_raw(capability, primary, result)
+            return self._compact(capability, result)
+
+        # Try fallback
+        if allow_fallback and fallback:
+            result = self._try_tool(fallback, params)
+            if result is not None:
+                self._store_raw(capability, fallback, result)
+                return self._compact(capability, result)
+
+        return {
+            "status": "fail",
+            "error": f"No executor available for {capability}",
+        }
+
+    def _try_tool(self, tool_name: str, params: dict[str, Any]) -> Any | None:
+        fn = self._executors.get(tool_name)
+        if fn is None:
+            return None
+        try:
+            return fn(**params)
+        except Exception as exc:
+            return None
+
+    def _store_raw(self, capability: str, tool_name: str, raw: Any) -> str:
+        """Persist raw MCP output out of band."""
+        ref = save_artifact(
+            "mcp_raw",
+            f"{capability}__{tool_name.replace('.', '_')}",
+            json.dumps(raw, default=str) if not isinstance(raw, str) else raw,
+        )
+        return str(ref)
+
+    @staticmethod
+    def _compact(capability: str, raw: Any) -> dict[str, Any]:
+        """
+        Reduce raw MCP output to a compact result.
+
+        The exact transformation is capability-specific;
+        this default just wraps the raw data.
+        """
+        return {
+            "status": "pass",
+            "capability": capability,
+            "data": raw,
+        }
+
+
+# Singleton
+dispatcher = MCPDispatcher()