codeer-cli 0.1.0__py3-none-any.whl

codeer_cli/client.py

@@ -0,0 +1,277 @@
+"""HTTP client for the Codeer API.
+
+Auth uses a workspace API key supplied through ``CODEER_API_KEY`` or a named
+profile stored outside the workspace. ``CODEER_API_BASE`` defaults to
+production and can be overridden for local, beta, or preview. The CLI
+intentionally does not read workspace-local dotenv files or credential files,
+because those locations are commonly visible to LLM workspace context.
+"""
+
+from __future__ import annotations
+
+import json as json_lib
+import os
+from dataclasses import dataclass
+from typing import Any, Iterable, Iterator, Mapping, Optional
+
+import httpx
+
+DEFAULT_CODEER_API_BASE = "https://api.codeer.ai"
+
+
+class CodeerError(RuntimeError):
+    """Raised when the server returns a non-2xx response or an error envelope."""
+
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+class AuthError(CodeerError):
+    """Raised when the API key is missing, expired, revoked, or rejected."""
+
+
+class ScopeResolutionError(CodeerError):
+    """Raised when workspace or organization scope cannot be inferred."""
+
+
+@dataclass
+class CodeerClient:
+    """Thin wrapper around httpx.Client with Codeer API-key auth.
+
+    Construct via ``CodeerClient.from_env()`` so your script picks up credentials
+    from the process environment without hardcoding them.
+    """
+
+    base_url: str
+    api_key: str
+    workspace_id: Optional[str] = None
+    organization_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        self._me_cache: Optional[dict[str, Any]] = None
+        self._client = httpx.Client(
+            base_url=self.base_url.rstrip("/"),
+            timeout=self.timeout,
+            headers={
+                "x-api-key": self.api_key,
+                "Accept": "application/json",
+            },
+        )
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "CodeerClient":
+        base_url = overrides.pop("base_url", None)
+        api_key = overrides.pop("api_key", None)
+
+        if not api_key:
+            from .commands.profile import resolve_profile
+
+            profile = resolve_profile()
+            api_key = profile.get("api_key")
+            base_url = (
+                base_url
+                or os.environ.get("CODEER_API_BASE")
+                or profile.get("api_base")
+                or DEFAULT_CODEER_API_BASE
+            )
+        else:
+            base_url = base_url or os.environ.get("CODEER_API_BASE") or DEFAULT_CODEER_API_BASE
+
+        if not api_key:
+            raise AuthError(
+                0,
+                "Missing API key. Export CODEER_API_KEY or run `codeer profile add <name>` "
+                "and `codeer profile use <name>`.",
+            )
+
+        overrides.pop("workspace_id", None)
+        overrides.pop("organization_id", None)
+
+        return cls(
+            base_url=base_url,
+            api_key=api_key,
+            agent_id=overrides.pop("agent_id", None) or os.environ.get("CODEER_AGENT_ID") or None,
+            **overrides,
+        )
+
+    def get_me(self) -> dict[str, Any]:
+        if self._me_cache is None:
+            self._me_cache = self.get("/external/me")
+        return self._me_cache
+
+    def resolve_scope(self) -> tuple[str, str]:
+        """Resolve workspace/org from the API-key virtual user's profile."""
+        me = self.get_me()
+        profile = me.get("profile") or {}
+        ws_id = profile.get("default_workspace_id")
+        org_id = profile.get("default_organization_id")
+
+        if not ws_id or not org_id:
+            default_scopes = profile.get("default_scopes") or {}
+            ws_org_map = {str(k): str(v) for k, v in (profile.get("workspace_organization_map") or {}).items()}
+            candidates = _workspace_candidates(default_scopes, ws_org_map)
+            detail = ""
+            if candidates:
+                detail = "\nAvailable workspace candidates from profile:\n" + _format_workspace_choices(
+                    candidates, ws_org_map, _workspace_names(profile)
+                )
+            raise ScopeResolutionError(
+                0,
+                "API key profile is missing default_workspace_id or default_organization_id. "
+                "This CLI expects a workspace API key virtual user profile."
+                + detail,
+            )
+
+        self.workspace_id = str(ws_id)
+        self.organization_id = str(org_id)
+        return self.workspace_id, self.organization_id
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "CodeerClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+        files: Any = None,
+        data: Any = None,
+    ) -> Any:
+        url = path if path.startswith("http") else f"/api/v1{path if path.startswith('/') else '/' + path}"
+        r = self._client.request(method, url, params=params, json=json, files=files, data=data)
+        return self._parse(r)
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def stream_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+    ) -> Iterator[dict]:
+        """Yield parsed SSE events from a streaming endpoint (e.g. POST /chats/{id}/messages).
+
+        Each event is a dict like ``{"event": "message", "data": <parsed-json-or-str>}``.
+        """
+        url = path if path.startswith("http") else f"/api/v1{path if path.startswith('/') else '/' + path}"
+        with self._client.stream(method, url, params=params, json=json) as r:
+            if r.status_code >= 400:
+                body = r.read().decode("utf-8", "replace")
+                self._raise_for_error(r.status_code, body)
+            event = "message"
+            buf: list[str] = []
+            for line in r.iter_lines():
+                if line == "":
+                    if buf:
+                        raw = "\n".join(buf)
+                        yield {"event": event, "data": _maybe_json(raw)}
+                        buf = []
+                        event = "message"
+                    continue
+                if line.startswith(":"):
+                    continue
+                if line.startswith("event:"):
+                    event = line[len("event:"):].strip()
+                    continue
+                if line.startswith("data:"):
+                    buf.append(line[len("data:"):].lstrip())
+            if buf:
+                yield {"event": event, "data": _maybe_json("\n".join(buf))}
+
+    def _parse(self, r: httpx.Response) -> Any:
+        text = r.text
+        try:
+            payload = r.json() if text else None
+        except ValueError:
+            payload = text
+
+        if r.status_code >= 400:
+            self._raise_for_error(r.status_code, payload)
+
+        # Ninja responses follow {error_code, message, data, pagination}. Unwrap `data`
+        # when present and the envelope indicates success, but return the full envelope
+        # if callers need the pagination cursor or error_code detail.
+        if isinstance(payload, dict) and "error_code" in payload and "data" in payload:
+            if payload.get("error_code") not in (0, None):
+                raise CodeerError(r.status_code, payload.get("message") or "error", payload)
+            return payload["data"]
+        return payload
+
+    def _raise_for_error(self, status: int, payload: Any) -> None:
+        message = payload if isinstance(payload, str) else (payload or {}).get("message") if isinstance(payload, dict) else None
+        if status in (401, 403):
+            raise AuthError(
+                status,
+                f"{message or 'auth rejected'}. API key may be missing, invalid, expired, or revoked.",
+                payload,
+            )
+        raise CodeerError(status, message or f"HTTP {status}", payload)
+
+
+def _maybe_json(raw: str) -> Any:
+    try:
+        return json_lib.loads(raw)
+    except (ValueError, TypeError):
+        return raw
+
+
+def _workspace_names(profile: Mapping[str, Any]) -> dict[str, str]:
+    names: dict[str, str] = {}
+    for ws in profile.get("workspaces") or []:
+        ws_id = ws.get("id")
+        if ws_id:
+            names[str(ws_id)] = str(ws.get("name") or "(unnamed)")
+    return names
+
+
+def _workspace_candidates(default_scopes: Mapping[str, Any], ws_org_map: Mapping[str, str]) -> list[str]:
+    candidates: set[str] = set()
+    for scope in default_scopes.values():
+        if isinstance(scope, Mapping) and scope.get("workspace_id"):
+            candidates.add(str(scope["workspace_id"]))
+    candidates.update(str(ws_id) for ws_id in ws_org_map.keys())
+    return sorted(candidates)
+
+
+def _format_workspace_choices(
+    workspace_ids: Iterable[str],
+    ws_org_map: Mapping[str, str],
+    workspace_names: Mapping[str, str],
+) -> str:
+    lines = []
+    for ws_id in workspace_ids:
+        name = workspace_names.get(ws_id)
+        org = ws_org_map.get(ws_id)
+        label = f"{name} ({ws_id})" if name else ws_id
+        if org:
+            label = f"{label} in org {org}"
+        lines.append(f"  - {label}")
+    return "\n".join(lines)

codeer_cli/commands/_util.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import sys
+
+
+def log(*args, **kwargs):
+    print(*args, file=sys.stderr, **kwargs)
+
+
+def truncate(text: str, n: int = 60) -> str:
+    text = text.replace("\n", " ").strip()
+    return text[:n] + "..." if len(text) > n else text

codeer_cli/commands/agent.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import difflib
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+from .. import agents as agents_mod
+from ..client import CodeerClient
+from ._util import log
+
+
+def register(subparsers):
+    agent = subparsers.add_parser("agent", help="Agent CRUD, versioning, publishing")
+    sub = agent.add_subparsers(dest="action", required=True)
+
+    # codeer agent list
+    p = sub.add_parser("list", help="List agents in workspace")
+    p.set_defaults(func=run_list)
+
+    # codeer agent get <id>
+    p = sub.add_parser("get", help="Read agent details")
+    p.add_argument("agent_id")
+    p.set_defaults(func=run_get)
+
+    # codeer agent apply --payload agent.json
+    p = sub.add_parser("apply", help="Create or update agent from JSON payload")
+    p.add_argument("--payload", required=True, help="Path to agent payload JSON")
+    p.add_argument("--agent-id", default=None, help="If set, PUT (update). Else POST (create).")
+    p.add_argument("--note", default="", help="version_note for PUT")
+    p.add_argument("--out", default=None, help="Write result JSON to this file too")
+    p.set_defaults(func=run_apply)
+
+    # codeer agent diff --from-version 41 --to-version 42
+    p = sub.add_parser("diff", help="Diff system_prompt + tools between two versions")
+    p.add_argument("--agent", required=True)
+    p.add_argument("--from", dest="frm", default=None, help="From history_id")
+    p.add_argument("--to", default=None, help="To history_id")
+    p.add_argument("--from-version", type=int, default=None)
+    p.add_argument("--to-version", type=int, default=None)
+    p.add_argument("--field", choices=("system_prompt", "tools", "all"), default="all")
+    p.set_defaults(func=run_diff)
+
+    # codeer agent versions --agent <id>
+    p = sub.add_parser("versions", help="List version history for an agent")
+    p.add_argument("--agent", required=True)
+    p.set_defaults(func=run_versions)
+
+
+
+def run_list(args, client) -> int:
+    ws, org = client.resolve_scope()
+    result = agents_mod.list_all(client, workspace_id=ws, organization_id=org)
+    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_get(args, client) -> int:
+    result = agents_mod.get(client, args.agent_id)
+    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_apply(args, client) -> int:
+    body = json.loads(Path(args.payload).read_text())
+
+    if args.agent_id:
+        body.pop("workspace_id", None)
+        agents_mod.update(
+            client, args.agent_id,
+            name=body["name"],
+            system_prompt=body["system_prompt"],
+            unified_tools=body.get("unified_tools") or [],
+            use_search=body.get("use_search", False),
+            version_note=args.note,
+            description=body.get("description"),
+            llm_model=body.get("llm_model"),
+            suggested_questions=body.get("suggested_questions") or [],
+            primary_object_ids=body.get("primary_object_ids") or [],
+            attachment_ids=body.get("attachment_ids") or [],
+        )
+        agent_id = args.agent_id
+        log(f"PUT /agents/{agent_id} ok")
+    else:
+        if not body.get("workspace_id"):
+            body["workspace_id"] = client.resolve_scope()[0]
+        agent = agents_mod.create(
+            client,
+            workspace_id=body["workspace_id"],
+            name=body["name"],
+            system_prompt=body["system_prompt"],
+            unified_tools=body.get("unified_tools") or [],
+            use_search=body.get("use_search", False),
+            description=body.get("description"),
+            llm_model=body.get("llm_model"),
+            suggested_questions=body.get("suggested_questions") or [],
+            primary_object_ids=body.get("primary_object_ids") or [],
+            attachment_ids=body.get("attachment_ids") or [],
+        )
+        agent_id = agent["id"]
+        log(f"POST /agents ok, id={agent_id}")
+
+    histories = agents_mod.list_versions(client, agent_id)
+    latest = max(histories, key=lambda h: h.get("version_number", 0))
+    result = {
+        "agent_id": agent_id,
+        "history_id": latest["id"],
+        "version_number": latest.get("version_number"),
+        "status": latest.get("status"),
+    }
+    out_text = json.dumps(result, indent=2)
+    print(out_text)
+    if args.out:
+        Path(args.out).write_text(out_text + "\n")
+    return 0
+
+
+def run_versions(args, client) -> int:
+    versions = agents_mod.list_versions(client, args.agent)
+    print(json.dumps(versions, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+
+# --- diff helpers ---
+
+def _resolve(c: CodeerClient, agent_id: str, hid: Optional[str], version: Optional[int]) -> dict:
+    if hid:
+        return agents_mod.get_version(c, agent_id, hid)
+    if version is not None:
+        for v in agents_mod.list_versions(c, agent_id):
+            if v.get("version_number") == version:
+                return agents_mod.get_version(c, agent_id, v["id"])
+        raise SystemExit(f"no version {version} on agent {agent_id}")
+    raise SystemExit("must pass --from/--to (history id) or --from-version/--to-version")
+
+
+def _label(snap: dict) -> str:
+    vn = snap.get("version_number")
+    note = (snap.get("version_note") or "").strip().replace("\n", " ")
+    pub = " (published)" if snap.get("status") == "published" else ""
+    return f"v{vn}{pub}: {note[:60]}"
+
+
+def _diff_text(a: str, b: str, label_a: str, label_b: str) -> str:
+    return "".join(difflib.unified_diff(
+        (a or "").splitlines(keepends=True),
+        (b or "").splitlines(keepends=True),
+        fromfile=label_a, tofile=label_b,
+    ))
+
+
+def _summarize_tool(t: dict) -> str:
+    keep_keys = ("type", "name", "description", "invocation_instruction",
+                 "knowledge_node_ids", "domain", "agent_id",
+                 "custom_form_schema", "http_request")
+    safe = {k: t.get(k) for k in keep_keys if t.get(k) is not None}
+    return json.dumps(safe, ensure_ascii=False, indent=2, sort_keys=True)
+
+
+def run_diff(args, client) -> int:
+    snap_a = _resolve(client, args.agent, args.frm, args.from_version)
+    snap_b = _resolve(client, args.agent, args.to, args.to_version)
+    la, lb = _label(snap_a), _label(snap_b)
+
+    if args.field in ("system_prompt", "all"):
+        d = _diff_text(snap_a.get("system_prompt", ""), snap_b.get("system_prompt", ""),
+                       f"{la} [system_prompt]", f"{lb} [system_prompt]")
+        if d.strip():
+            print(d)
+        else:
+            print(f"# system_prompt unchanged between {la} and {lb}")
+
+    if args.field in ("tools", "all"):
+        a_tools = snap_a.get("unified_tools") or []
+        b_tools = snap_b.get("unified_tools") or []
+        a_text = "\n".join(_summarize_tool(t) for t in a_tools) + "\n"
+        b_text = "\n".join(_summarize_tool(t) for t in b_tools) + "\n"
+        d = _diff_text(a_text, b_text, f"{la} [tools]", f"{lb} [tools]")
+        if d.strip():
+            print(d)
+        else:
+            print(f"# tools unchanged between {la} and {lb}")
+
+    return 0

codeer_cli/commands/check.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import sys
+
+from ..client import AuthError, CodeerError
+
+
+def register(subparsers):
+    p = subparsers.add_parser("check", help="Validate auth, workspace, and agent config")
+    p.set_defaults(func=run)
+
+
+def run(args, client) -> int:
+    errors = []
+
+    try:
+        me = client.get_me()
+    except AuthError:
+        print("FAIL  Auth: API key missing, invalid, expired, or revoked (401/403)", file=sys.stderr)
+        print("      Create an admin workspace API key and export CODEER_API_KEY before running codeer", file=sys.stderr)
+        return 1
+    except CodeerError as e:
+        print(f"FAIL  Auth: {e}", file=sys.stderr)
+        return 1
+
+    profile = me.get("profile", {})
+    email = me.get("email") or "(unknown)"
+    print(f"  OK  Auth: logged in as {email}")
+
+    try:
+        ws_id, org_id = client.resolve_scope()
+    except CodeerError as e:
+        errors.append(f"FAIL  Scope: {e.message if hasattr(e, 'message') else str(e)}")
+        ws_id, org_id = None, None
+
+    if ws_id:
+        ws_name = _workspace_name(profile, ws_id)
+        if ws_name:
+            print(f"  OK  Workspace: {ws_name} ({ws_id})")
+        else:
+            print(f"  OK  Workspace: {ws_id}")
+
+    if org_id:
+        print(f"  OK  Organization: {org_id}")
+
+    agent_id = client.agent_id
+    if agent_id:
+        try:
+            agent = client.get(f"/external/agents/{agent_id}")
+            print(f"  OK  Agent: {agent.get('name', '(unnamed)')} ({agent_id})")
+        except CodeerError:
+            errors.append(f"WARN  Agent: ID {agent_id} could not be read (may be in a different workspace)")
+    else:
+        print("  --  Agent: CODEER_AGENT_ID not set (optional)")
+
+    for err in errors:
+        print(err, file=sys.stderr)
+
+    return 1 if any(e.startswith("FAIL") for e in errors) else 0
+
+
+def _workspace_name(profile: dict, workspace_id: str) -> str | None:
+    for ws in profile.get("workspaces", []) or []:
+        if str(ws.get("id")) == str(workspace_id):
+            return ws.get("name")
+    return None