managed-research 0.1.0__tar.gz

managed_research-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/

managed_research-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: managed-research
+Version: 0.1.0
+Summary: Pure-Python SMR API client and MCP server.
+Author: Synth Laboratories
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pynacl>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.3; extra == 'dev'
+Requires-Dist: ruff>=0.11.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# managed-research
+
+Pure-Python public SMR surfaces for Managed Research.
+
+Current scope:
+
+- SMR API client
+- SMR MCP stdio server
+- generated-schema sync path for public SMR contracts
+
+Out of scope for this slice:
+
+- runtime internals
+- sandbox/session control
+- private backend models
+
+## Install
+
+```bash
+pip install -U managed-research
+```
+
+For local development:
+
+```bash
+uv sync --extra dev
+```
+
+## Run the MCP server
+
+```bash
+uv run managed-research-mcp
+```
+
+The package reads `SYNTH_API_KEY` and `SYNTH_BACKEND_URL` from the environment.
+
+Python API surface:
+
+```python
+from managed_research import ManagedResearchClient
+
+client = ManagedResearchClient(api_key="sk_...")
+projects = client.list_projects()
+```
+
+## Sync exported public schemas
+
+```bash
+uv run python scripts/sync_public_schemas.py --source /path/to/exported/schemas
+```
+
+If you prefer environment configuration, set `MANAGED_RESEARCH_SCHEMA_SOURCE`
+instead of passing `--source`.
+
+There is also a console entrypoint:
+
+```bash
+uv run managed-research-sync-schemas --source /path/to/exported/schemas
+```

managed_research-0.1.0/README.md

@@ -0,0 +1,59 @@
+# managed-research
+
+Pure-Python public SMR surfaces for Managed Research.
+
+Current scope:
+
+- SMR API client
+- SMR MCP stdio server
+- generated-schema sync path for public SMR contracts
+
+Out of scope for this slice:
+
+- runtime internals
+- sandbox/session control
+- private backend models
+
+## Install
+
+```bash
+pip install -U managed-research
+```
+
+For local development:
+
+```bash
+uv sync --extra dev
+```
+
+## Run the MCP server
+
+```bash
+uv run managed-research-mcp
+```
+
+The package reads `SYNTH_API_KEY` and `SYNTH_BACKEND_URL` from the environment.
+
+Python API surface:
+
+```python
+from managed_research import ManagedResearchClient
+
+client = ManagedResearchClient(api_key="sk_...")
+projects = client.list_projects()
+```
+
+## Sync exported public schemas
+
+```bash
+uv run python scripts/sync_public_schemas.py --source /path/to/exported/schemas
+```
+
+If you prefer environment configuration, set `MANAGED_RESEARCH_SCHEMA_SOURCE`
+instead of passing `--source`.
+
+There is also a console entrypoint:
+
+```bash
+uv run managed-research-sync-schemas --source /path/to/exported/schemas
+```

managed_research-0.1.0/managed_research/__init__.py

@@ -0,0 +1,53 @@
+"""Public Managed Research package."""
+
+from managed_research.errors import SmrApiError
+from managed_research.models import (
+    SmrActorStatus,
+    SmrApproval,
+    SmrArtifact,
+    SmrCapabilities,
+    SmrIntegrationStatus,
+    SmrLinearTeam,
+    SmrLinearTeamListing,
+    SmrOAuthStart,
+    SmrProject,
+    SmrProjectStatusSnapshot,
+    SmrProviderKeyStatus,
+    SmrQuestion,
+    SmrRun,
+    SmrRunEconomics,
+    SmrRunLogArchive,
+)
+from managed_research.sdk.client import (
+    ACTIVE_RUN_STATES,
+    DEFAULT_TIMEOUT_SECONDS,
+    ManagedResearchClient,
+    SmrControlClient,
+    first_id,
+)
+from managed_research.version import __version__
+
+__all__ = [
+    "ACTIVE_RUN_STATES",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "ManagedResearchClient",
+    "SmrActorStatus",
+    "SmrApiError",
+    "SmrApproval",
+    "SmrArtifact",
+    "SmrCapabilities",
+    "SmrControlClient",
+    "SmrIntegrationStatus",
+    "SmrLinearTeam",
+    "SmrLinearTeamListing",
+    "SmrOAuthStart",
+    "SmrProject",
+    "SmrProjectStatusSnapshot",
+    "SmrProviderKeyStatus",
+    "SmrQuestion",
+    "SmrRun",
+    "SmrRunEconomics",
+    "SmrRunLogArchive",
+    "__version__",
+    "first_id",
+]

managed_research-0.1.0/managed_research/auth.py

@@ -0,0 +1,75 @@
+"""Auth and transport helpers for the public Managed Research package."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from pathlib import Path
+from urllib.parse import urlparse, urlunparse
+
+from nacl.public import PublicKey, SealedBox
+
+BACKEND_URL_BASE = (os.getenv("SYNTH_BACKEND_URL") or "https://api.usesynth.ai").strip()
+
+
+def _read_json_object(path: Path) -> dict[str, object]:
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return raw if isinstance(raw, dict) else {}
+
+
+def _config_search_paths() -> list[Path]:
+    home = Path.home()
+    return [
+        home / ".synth_ai" / "config.json",
+        home / ".config" / "synth" / "config.json",
+    ]
+
+
+def get_api_key(env_key: str = "SYNTH_API_KEY", required: bool = True) -> str | None:
+    """Resolve the Synth API key from environment or local config."""
+    value = (os.getenv(env_key) or "").strip()
+    if value:
+        return value
+
+    for path in _config_search_paths():
+        payload = _read_json_object(path)
+        config_value = payload.get(env_key)
+        if isinstance(config_value, str) and config_value.strip():
+            return config_value.strip()
+
+    if required:
+        raise ValueError(f"{env_key} is required (set {env_key} or store it in local Synth config)")
+    return None
+
+
+def _strip_terminal_segment(path: str, segment: str) -> str:
+    trimmed = path.rstrip("/")
+    if trimmed.endswith(segment):
+        return trimmed[: -len(segment)].rstrip("/")
+    return trimmed
+
+
+def normalize_backend_base(url: str) -> str:
+    """Normalize a backend URL down to the service base."""
+    parsed = urlparse(url.strip())
+    path = _strip_terminal_segment(parsed.path, "/v1")
+    path = _strip_terminal_segment(path, "/api")
+    normalized = parsed._replace(path=path.rstrip("/"), query="", fragment="")
+    return urlunparse(normalized)
+
+
+def encrypt_for_backend(pubkey_b64: str, secret: str | bytes) -> str:
+    """Encrypt a provider key using the backend's sealed-box public key."""
+    if isinstance(secret, bytes):
+        secret = secret.decode("utf-8")
+    try:
+        pubkey_raw = base64.b64decode(pubkey_b64, validate=True)
+    except Exception as exc:
+        raise RuntimeError("Invalid backend public key (not base64)") from exc
+    box = SealedBox(PublicKey(pubkey_raw))
+    ciphertext = box.encrypt(secret.encode("utf-8"))
+    return base64.b64encode(ciphertext).decode("utf-8")

managed_research-0.1.0/managed_research/client.py

@@ -0,0 +1,3 @@
+"""Compatibility wrapper for the public SMR client surface."""
+
+from managed_research.sdk.client import *  # noqa: F403

managed_research-0.1.0/managed_research/errors.py

@@ -0,0 +1,8 @@
+"""Public error types for Managed Research."""
+
+
+class SmrApiError(RuntimeError):
+    """Raised when the SMR API returns a non-success response."""
+
+
+__all__ = ["SmrApiError"]

managed_research-0.1.0/managed_research/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Managed Research MCP exports."""
+
+from managed_research.mcp.server import ManagedResearchMcpServer, main, run_stdio_server
+
+__all__ = ["ManagedResearchMcpServer", "main", "run_stdio_server"]

managed_research-0.1.0/managed_research/mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Run the Managed Research MCP server with ``python -m managed_research.mcp``."""
+
+from managed_research.mcp.server import main
+
+main()

managed_research-0.1.0/managed_research/mcp/registry.py

@@ -0,0 +1,47 @@
+"""Shared MCP registry types and schema helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+JSONDict = dict[str, Any]
+ToolHandler = Callable[[JSONDict], Any]
+
+
+@dataclass(frozen=True)
+class ToolDefinition:
+    """MCP tool metadata and handler."""
+
+    name: str
+    description: str
+    input_schema: JSONDict
+    handler: ToolHandler
+
+
+_CONNECTION_PROPERTIES: JSONDict = {
+    "api_key": {
+        "type": "string",
+        "description": "Optional API key override (defaults to SYNTH_API_KEY).",
+    },
+    "backend_base": {
+        "type": "string",
+        "description": "Optional backend URL override (defaults to SYNTH_BACKEND_URL).",
+    },
+}
+
+
+def tool_schema(properties: JSONDict, required: list[str]) -> JSONDict:
+    """Attach shared connection properties to a tool schema."""
+    merged: JSONDict = dict(properties)
+    merged.update(_CONNECTION_PROPERTIES)
+    return {
+        "type": "object",
+        "properties": merged,
+        "required": required,
+        "additionalProperties": False,
+    }
+
+
+__all__ = ["JSONDict", "ToolDefinition", "ToolHandler", "tool_schema"]