deepparallel 0.2.0__py3-none-any.whl

deepparallel/renderer.py

@@ -0,0 +1,222 @@
+"""Terminal renderers for DeepParallel.
+
+The agent loop is UI-agnostic: it talks to a `Renderer`. Two concrete
+implementations:
+- `RichRenderer`: interactive tty - inline token streaming + tool cards.
+- `PlainRenderer`: pipe-friendly plain text for `run` / non-tty / CI.
+
+`tool_start` / `tool_result` are a paired sequence around a tool call.
+`confirm()` reads y/n via an injectable input function. The renderer prints
+incrementally (no redrawing Live regions) so output never ghosts.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+import time
+from abc import ABC, abstractmethod
+from typing import Iterable
+
+from rich.console import Console
+
+from deepparallel import branding
+
+_REVEAL_SECONDS = 0.04  # per-line delay for the animated intro (tests set 0)
+
+
+class Renderer(ABC):
+    @abstractmethod
+    def welcome(
+        self,
+        backend_label: str,
+        *,
+        version: str = "",
+        tool_count: int = 0,
+        fusion_modes: tuple[str, ...] = (),
+    ) -> None: ...
+
+    @abstractmethod
+    def answer(self, text: str) -> None: ...
+
+    @abstractmethod
+    def answer_stream(self, chunks: Iterable[str]) -> str: ...
+
+    @abstractmethod
+    def reasoning(self, text: str) -> None: ...
+
+    @abstractmethod
+    def tool_start(self, name: str, args_preview: str) -> None: ...
+
+    @abstractmethod
+    def tool_result(self, ok: bool, summary: str, duration_s: float) -> None: ...
+
+    @abstractmethod
+    def confirm(self, action_title: str, detail: str) -> bool: ...
+
+    @abstractmethod
+    def error(self, msg: str) -> None: ...
+
+    @abstractmethod
+    def attribution_footer(self) -> None: ...
+
+
+class PlainRenderer(Renderer):
+    """Pipe-friendly renderer. The final answer goes to stdout; tool activity
+    and diagnostics go to stderr, so `deepparallel run ... | pipe` stays clean."""
+
+    def __init__(self, out=None, err=None, *, assume_yes: bool = False):
+        self._out = out or sys.stdout
+        self._err = err or sys.stderr
+        self._assume_yes = assume_yes
+        self._cur: str | None = None
+
+    def _wo(self, s: str) -> None:
+        self._out.write(s)
+        self._out.flush()
+
+    def _we(self, s: str) -> None:
+        self._err.write(s)
+        self._err.flush()
+
+    def welcome(self, backend_label, *, version="", tool_count=0, fusion_modes=()) -> None:
+        self._we(
+            f"DeepParallel v{version} - served via Crowe Logic\n"
+            f"{tool_count} tools - Backend: {backend_label}\n"
+        )
+
+    def answer(self, text: str) -> None:
+        self._wo(text.rstrip("\n") + "\n")
+
+    def answer_stream(self, chunks: Iterable[str]) -> str:
+        parts: list[str] = []
+        for c in chunks:
+            parts.append(c)
+            self._wo(c)
+        self._wo("\n")
+        return "".join(parts)
+
+    def reasoning(self, text: str) -> None:
+        self._we(f"[reasoning] {text}\n")
+
+    def tool_start(self, name: str, args_preview: str) -> None:
+        self._cur = name
+        self._we(f"> {name} {args_preview}".rstrip() + "\n")
+
+    def tool_result(self, ok: bool, summary: str, duration_s: float) -> None:
+        mark = "ok" if ok else "FAILED"
+        self._we(f"  [{mark}] {self._cur} - {summary} ({duration_s:.1f}s)\n")
+        self._cur = None
+
+    def confirm(self, action_title: str, detail: str) -> bool:
+        return self._assume_yes
+
+    def error(self, msg: str) -> None:
+        self._we(f"error: {msg}\n")
+
+    def attribution_footer(self) -> None:
+        self._we("DeepParallel - served via Crowe Logic infrastructure. https://crowelogic.com\n")
+
+
+class RichRenderer(Renderer):
+    def __init__(self, console: Console | None = None, *, input_fn=None):
+        self._console = console or branding.console
+        self._input_fn = input_fn or self._console.input
+        self._cur: str | None = None
+        self._timer_stop: threading.Event | None = None
+        self._timer_thread: threading.Thread | None = None
+
+    def welcome(self, backend_label, *, version="", tool_count=0, fusion_modes=()) -> None:
+        animate = self._console.is_terminal and _REVEAL_SECONDS > 0
+        for line in branding.wordmark_lines():
+            self._console.print(f"[{branding.DP_ACCENT}]{line}[/]", highlight=False)
+            if animate:
+                time.sleep(_REVEAL_SECONDS)
+        self._console.print()
+        self._console.print(
+            branding.status_text(
+                version=version,
+                tool_count=tool_count,
+                fusion_modes=fusion_modes,
+                backend_label=backend_label,
+            )
+        )
+
+    def answer(self, text: str) -> None:
+        self._console.print(branding.build_transcript_markdown(self._console, text))
+
+    def answer_stream(self, chunks: Iterable[str]) -> str:
+        # Inline token streaming: no Live/transient panels, so it never ghosts
+        # in wide terminals or when tool turns interleave. The marker is printed
+        # only on the first VISIBLE character, so empty / whitespace-leading
+        # (tool-only) turns render no stray marker.
+        parts: list[str] = []
+        started = False
+        for c in chunks:
+            parts.append(c)
+            if started:
+                self._console.print(c, end="", soft_wrap=True, highlight=False, markup=False)
+                continue
+            if not "".join(parts).strip():
+                continue  # only whitespace so far; hold the marker back
+            started = True
+            self._console.print(
+                f"[{branding.DP_ACCENT}]{branding.MARK}[/] ", end="", highlight=False
+            )
+            self._console.print(c.lstrip(), end="", soft_wrap=True, highlight=False, markup=False)
+        if started:
+            self._console.print()
+        return "".join(parts)
+
+    def reasoning(self, text: str) -> None:
+        self._console.print(branding.build_reasoning_panel(self._console, text))
+
+    def tool_start(self, name: str, args_preview: str) -> None:
+        self._cur = name
+        branding.render_tool_card(self._console, name, args_preview, status="running")
+        if self._console.is_terminal:
+            self._timer_stop = threading.Event()
+            start = time.monotonic()
+            fh = self._console.file
+
+            def tick() -> None:
+                while not self._timer_stop.wait(0.5):  # type: ignore[union-attr]
+                    fh.write(f"\r  {name}... {time.monotonic() - start:.0f}s ")
+                    fh.flush()
+
+            self._timer_thread = threading.Thread(target=tick, daemon=True)
+            self._timer_thread.start()
+
+    def _stop_timer(self) -> None:
+        if self._timer_stop is None:
+            return
+        self._timer_stop.set()
+        if self._timer_thread is not None:
+            self._timer_thread.join(timeout=1.0)
+        self._timer_stop = None
+        self._timer_thread = None
+        self._console.file.write("\r" + " " * 48 + "\r")  # clear the timer line
+        self._console.file.flush()
+
+    def tool_result(self, ok: bool, summary: str, duration_s: float) -> None:
+        self._stop_timer()
+        branding.render_tool_card(
+            self._console,
+            self._cur or "",
+            "",
+            status="ok" if ok else "fail",
+            result=summary,
+            duration_ms=int(duration_s * 1000),
+        )
+        self._cur = None
+
+    def confirm(self, action_title: str, detail: str) -> bool:
+        branding.render_confirm_body(self._console, action_title, detail)
+        ans = (self._input_fn("  approve? [y/N] ") or "").strip().lower()
+        return ans in {"y", "yes"}
+
+    def error(self, msg: str) -> None:
+        branding.render_error(self._console, "error", detail=msg)
+
+    def attribution_footer(self) -> None:
+        branding.attribution_footer()

deepparallel/system_prompt.txt

@@ -0,0 +1,4 @@
+You are DeepParallel, a precise and capable coding assistant served via Crowe Logic.
+Answer clearly and directly. When a problem benefits from step-by-step reasoning, reason carefully before giving the final answer. Be concise unless asked for depth.
+
+You can use tools to read, search, analyze, edit, and run code. Use them when they help; do not call them speculatively. When asked to run something with different parameters, prefer non-destructive approaches (command-line arguments, environment variables, or a temporary copy) over editing the user's source files. Only edit a source file when changing that file is the actual goal, and explain what you changed.

deepparallel/tools/__init__.py

@@ -0,0 +1,27 @@
+"""Tool package: a single registry singleton plus the registered tool modules.
+
+`registry` and `tool` are defined before the submodule imports so the tool
+modules can decorate against the singleton without a circular-import error.
+"""
+
+from deepparallel.tools.registry import ToolRegistry
+
+registry = ToolRegistry()
+tool = registry.tool
+
+
+def get_registry() -> ToolRegistry:
+    return registry
+
+
+# Importing the submodules registers their tools against `registry`.
+from deepparallel.tools import (  # noqa: E402,F401
+    codeast,
+    edit,
+    files,
+    sandbox,
+    search,
+    shell,
+    vision,
+    web,
+)

deepparallel/tools/codeast.py

@@ -0,0 +1,171 @@
+"""Multi-language, AST-aware code tools backed by tree-sitter.
+
+Symbols are located structurally (not by text), so edits replace a whole
+function/class definition by its byte span, preserving the rest of the file.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from tree_sitter import Parser
+from tree_sitter_language_pack import get_language
+
+from deepparallel.tools import tool
+
+_EXT_LANG = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+    ".rb": "ruby",
+    ".c": "c",
+    ".h": "c",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".hpp": "cpp",
+    ".cs": "csharp",
+    ".php": "php",
+}
+
+_DEF_KINDS = {
+    "python": {"function_definition", "class_definition"},
+    "javascript": {"function_declaration", "class_declaration", "method_definition"},
+    "typescript": {
+        "function_declaration",
+        "class_declaration",
+        "method_definition",
+        "interface_declaration",
+    },
+    "tsx": {
+        "function_declaration",
+        "class_declaration",
+        "method_definition",
+        "interface_declaration",
+    },
+    "go": {"function_declaration", "method_declaration", "type_declaration"},
+    "rust": {"function_item", "struct_item", "enum_item", "trait_item"},
+    "java": {
+        "class_declaration",
+        "method_declaration",
+        "interface_declaration",
+        "constructor_declaration",
+    },
+    "ruby": {"method", "class", "module"},
+    "c": {"function_definition", "struct_specifier"},
+    "cpp": {"function_definition", "class_specifier", "struct_specifier"},
+    "csharp": {"class_declaration", "method_declaration", "interface_declaration"},
+    "php": {"function_definition", "class_declaration", "method_declaration"},
+}
+_DEFAULT_KINDS = {
+    "function_definition",
+    "function_declaration",
+    "class_definition",
+    "class_declaration",
+    "method_definition",
+    "method_declaration",
+}
+
+
+def _collect(file_path: str):
+    """Return (error_str | None, lang, data_bytes, symbols)."""
+    path = Path(file_path).expanduser().resolve()
+    if not path.is_file():
+        return json.dumps({"error": f"File not found: {file_path}"}), None, b"", []
+    lang = _EXT_LANG.get(path.suffix.lower())
+    if not lang:
+        return json.dumps({"error": f"Unsupported file type: {path.suffix}"}), None, b"", []
+    data = path.read_bytes()
+    try:
+        root = Parser(get_language(lang)).parse(data).root_node
+    except Exception as e:  # noqa: BLE001 - surface parser failure
+        return json.dumps({"error": f"parse failed: {e}"}), lang, data, []
+    kinds = _DEF_KINDS.get(lang, _DEFAULT_KINDS)
+    symbols: list[dict] = []
+
+    def walk(node):
+        for child in node.children:
+            if child.type in kinds:
+                name_node = child.child_by_field_name("name")
+                if name_node is not None:
+                    symbols.append(
+                        {
+                            "name": data[name_node.start_byte : name_node.end_byte].decode(
+                                "utf-8", "replace"
+                            ),
+                            "kind": child.type,
+                            "start_line": child.start_point[0] + 1,
+                            "end_line": child.end_point[0] + 1,
+                            "start_byte": child.start_byte,
+                            "end_byte": child.end_byte,
+                        }
+                    )
+            walk(child)
+
+    walk(root)
+    return None, lang, data, symbols
+
+
+@tool(dangerous=False)
+def ast_symbols(file_path: str) -> str:
+    """List the functions, classes, and methods defined in a source file.
+
+    :param file_path: Path to a source file (language inferred from extension).
+    """
+    err, lang, _data, symbols = _collect(file_path)
+    if err:
+        return err
+    public = [{k: s[k] for k in ("name", "kind", "start_line", "end_line")} for s in symbols]
+    return json.dumps({"language": lang, "symbols": public})
+
+
+@tool(dangerous=False)
+def ast_show_symbol(file_path: str, name: str) -> str:
+    """Return the full source of a named function/class/method.
+
+    :param file_path: Path to the source file.
+    :param name: Symbol name to show; must be unique in the file.
+    """
+    err, _lang, data, symbols = _collect(file_path)
+    if err:
+        return err
+    hits = [s for s in symbols if s["name"] == name]
+    if not hits:
+        return json.dumps({"error": f"symbol not found: {name}"})
+    if len(hits) > 1:
+        return json.dumps({"error": f"symbol '{name}' is ambiguous ({len(hits)} matches)"})
+    s = hits[0]
+    return json.dumps(
+        {
+            "source": data[s["start_byte"] : s["end_byte"]].decode("utf-8", "replace"),
+            "start_line": s["start_line"],
+            "end_line": s["end_line"],
+        }
+    )
+
+
+@tool(dangerous=True)
+def ast_replace_symbol(file_path: str, name: str, new_source: str) -> str:
+    """Replace the full definition of a named symbol with new source.
+
+    :param file_path: Path to the source file.
+    :param name: Symbol name to replace; must be unique in the file.
+    :param new_source: Replacement source for the entire definition.
+    """
+    err, _lang, data, symbols = _collect(file_path)
+    if err:
+        return err
+    hits = [s for s in symbols if s["name"] == name]
+    if not hits:
+        return json.dumps({"error": f"symbol not found: {name}"})
+    if len(hits) > 1:
+        return json.dumps({"error": f"symbol '{name}' is ambiguous ({len(hits)} matches)"})
+    s = hits[0]
+    new_bytes = data[: s["start_byte"]] + new_source.encode("utf-8") + data[s["end_byte"] :]
+    Path(file_path).expanduser().resolve().write_bytes(new_bytes)
+    return json.dumps({"success": True, "name": name, "start_line": s["start_line"]})

deepparallel/tools/edit.py

@@ -0,0 +1,29 @@
+"""Code-delivery edit tool (unique-match replacement)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from deepparallel.tools import tool
+
+
+@tool(dangerous=True)
+def edit_file(file_path: str, old_string: str, new_string: str) -> str:
+    """Replace a unique occurrence of old_string with new_string in a file.
+
+    :param file_path: Path to the file to edit.
+    :param old_string: Exact text to replace; must appear exactly once.
+    :param new_string: Replacement text.
+    """
+    path = Path(file_path).expanduser().resolve()
+    if not path.is_file():
+        return json.dumps({"error": f"File not found: {file_path}"})
+    text = path.read_text(encoding="utf-8")
+    count = text.count(old_string)
+    if count == 0:
+        return json.dumps({"error": "old_string not found"})
+    if count > 1:
+        return json.dumps({"error": "old_string must be unique; found multiple matches"})
+    path.write_text(text.replace(old_string, new_string), encoding="utf-8")
+    return json.dumps({"success": True, "path": str(path)})

deepparallel/tools/files.py

@@ -0,0 +1,74 @@
+"""Read-only filesystem tools (write_file is added alongside edit tooling)."""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+
+from deepparallel.tools import tool
+
+
+@tool(dangerous=False)
+def read_file(file_path: str, offset: int = 0, limit: int = 0) -> str:
+    """Read a file and return its contents with line numbers.
+
+    :param file_path: Path to the file to read.
+    :param offset: 0-based line index to start from.
+    :param limit: Maximum lines to return (0 = all).
+    """
+    path = Path(file_path).expanduser().resolve()
+    if not path.exists():
+        return json.dumps({"error": f"File not found: {file_path}"})
+    if not path.is_file():
+        return json.dumps({"error": f"Not a file: {file_path}"})
+    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    if offset > 0:
+        lines = lines[offset:]
+    if limit > 0:
+        lines = lines[:limit]
+    return "\n".join(f"{i + offset + 1:>6}\t{line}" for i, line in enumerate(lines))
+
+
+@tool(dangerous=False)
+def list_dir(dir_path: str = ".") -> str:
+    """List the entries in a directory.
+
+    :param dir_path: Directory to list.
+    """
+    path = Path(dir_path).expanduser().resolve()
+    if not path.is_dir():
+        return json.dumps({"error": f"Not a directory: {dir_path}"})
+    entries = [{"name": c.name, "is_dir": c.is_dir()} for c in sorted(path.iterdir())]
+    return json.dumps({"path": str(path), "entries": entries})
+
+
+@tool(dangerous=False)
+def glob(dir_path: str, pattern: str) -> str:
+    """Find files matching a glob pattern under a directory.
+
+    :param dir_path: Root directory to search.
+    :param pattern: Glob pattern, for example **/*.py.
+    """
+    root = Path(dir_path).expanduser().resolve()
+    matches = [str(p) for p in sorted(root.glob(pattern)) if p.is_file()]
+    return json.dumps({"matches": matches[:1000]})
+
+
+@tool(dangerous=True)
+def write_file(file_path: str, content: str = "", content_b64: str = "") -> str:
+    """Write text to a file, creating parent directories as needed.
+
+    :param file_path: Destination path.
+    :param content: Text content to write.
+    :param content_b64: Base64-encoded content; used instead of content when
+        set, for code payloads that are awkward to JSON-escape.
+    """
+    path = Path(file_path).expanduser().resolve()
+    if content_b64:
+        data = base64.b64decode(content_b64).decode("utf-8", errors="replace")
+    else:
+        data = content
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(data, encoding="utf-8")
+    return json.dumps({"success": True, "path": str(path), "bytes": len(data.encode("utf-8"))})

deepparallel/tools/registry.py

@@ -0,0 +1,149 @@
+"""Lightweight tool registry with docstring-driven JSON-schema introspection.
+
+Each tool is a plain function decorated with `@registry.tool(...)`. The signature
+and docstring `:param name:` lines build an OpenAI-style function schema. Tools
+carry a `dangerous` flag the agent uses to gate execution behind confirmation.
+Pure Python (inspect) - no heavy SDK.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from dataclasses import dataclass
+from typing import Any, Callable, Union
+
+_JSON_TYPES = {
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    bool: {"type": "boolean"},
+    str: {"type": "string"},
+    dict: {"type": "object"},
+    list: {"type": "array"},
+}
+
+
+def _normalize_type(annotation) -> dict[str, Any]:
+    if annotation is inspect.Parameter.empty:
+        return {"type": "string"}
+    origin = getattr(annotation, "__origin__", None)
+    args = getattr(annotation, "__args__", None)
+    if origin is Union and args:
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return _normalize_type(non_none[0])
+    return dict(_JSON_TYPES.get(annotation, {"type": "string"}))
+
+
+def _extract_parameters(fn: Callable) -> dict[str, Any]:
+    sig = inspect.signature(fn)
+    doc = inspect.getdoc(fn) or ""
+    props: dict[str, Any] = {}
+    required: list[str] = []
+    for name, param in sig.parameters.items():
+        if name == "self":
+            continue
+        schema = _normalize_type(param.annotation)
+        if param.default is inspect.Parameter.empty:
+            required.append(name)
+        for line in doc.splitlines():
+            s = line.strip()
+            if s.startswith(f":param {name}:"):
+                schema["description"] = s.split(":", 2)[-1].strip()
+                break
+        props[name] = schema
+    return {"type": "object", "properties": props, "required": required}
+
+
+def _extract_description(fn: Callable) -> str:
+    doc = inspect.getdoc(fn) or ""
+    out: list[str] = []
+    for line in doc.splitlines():
+        if line.strip().startswith(":"):
+            break
+        out.append(line)
+    return "\n".join(out).strip() or fn.__name__
+
+
+def coerce_args(parameters: dict, args: dict) -> dict:
+    """Coerce string argument values to the schema's declared scalar type.
+
+    Models often emit "5" for an int param or "yes" for a bool. Bad values are
+    left untouched so the tool (or the model) can deal with them.
+    """
+    props = parameters.get("properties", {})
+    out: dict[str, Any] = {}
+    for key, value in args.items():
+        declared = props.get(key, {}).get("type")
+        if isinstance(value, str):
+            if declared == "integer":
+                try:
+                    value = int(value)
+                except ValueError:
+                    pass
+            elif declared == "number":
+                try:
+                    value = float(value)
+                except ValueError:
+                    pass
+            elif declared == "boolean":
+                value = value.strip().lower() in {"1", "true", "yes", "on"}
+        out[key] = value
+    return out
+
+
+@dataclass
+class ToolMeta:
+    name: str
+    fn: Callable
+    description: str
+    parameters: dict[str, Any]
+    dangerous: bool
+
+    def to_openai_schema(self) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolMeta] = {}
+
+    def tool(self, *, dangerous: bool = False) -> Callable:
+        def deco(fn: Callable) -> Callable:
+            self._tools[fn.__name__] = ToolMeta(
+                name=fn.__name__,
+                fn=fn,
+                description=_extract_description(fn),
+                parameters=_extract_parameters(fn),
+                dangerous=dangerous,
+            )
+
+            @functools.wraps(fn)
+            def wrapper(*a, **k):
+                return fn(*a, **k)
+
+            return wrapper
+
+        return deco
+
+    def get(self, name: str) -> ToolMeta | None:
+        return self._tools.get(name)
+
+    def list_all(self) -> list[ToolMeta]:
+        return list(self._tools.values())
+
+    def call(self, name: str, **kwargs) -> Any:
+        meta = self._tools.get(name)
+        if meta is None:
+            raise KeyError(name)
+        return meta.fn(**kwargs)
+
+    def schemas(self) -> list[dict]:
+        return [m.to_openai_schema() for m in self._tools.values()]