codeer-cli 0.1.0__py3-none-any.whl

codeer_cli/__init__.py

@@ -0,0 +1,54 @@
+"""Thin Python client for the Codeer internal API.
+
+Import pattern for scripts::
+
+    from codeer_cli import CodeerClient, agents, kb, eval_, histories, chats
+
+    c = CodeerClient.from_env()
+    agent = agents.create(c, workspace_id=..., name="My Agent", system_prompt="...", unified_tools=[])
+
+Per-project env convention: set CODEER_AGENT_ID as an environment variable so
+scripts in a customer's directory don't have to re-pass it.
+
+The workspace and organization come from the workspace API-key virtual user's
+profile, not from CLI flags or environment overrides.
+
+Auth uses CODEER_API_KEY from process env only. CODEER_API_BASE defaults to
+production and can be overridden from process env. The CLI does not read
+workspace-local dotenv files or credential files.
+"""
+
+from ._validate import ToolValidationError
+from .client import AuthError, CodeerClient, CodeerError
+from .parse import (
+    AgentSummary,
+    ConversationTurn,
+    EvalResultSummary,
+    EvalToolCall,
+    HistorySummary,
+    KBNode,
+    ToolCall,
+    parse_agent,
+    parse_conversation_turn,
+    parse_conversations,
+    parse_eval_result,
+    parse_eval_tool_calls,
+    parse_kb_node,
+    parse_kb_nodes,
+    parse_rubrics_from_reason,
+    parse_tool_calls,
+    strip_tool_markers,
+    summarize_eval_tool_calls,
+    summarize_history,
+)
+
+__all__ = [
+    "CodeerClient", "CodeerError", "AuthError", "ToolValidationError",
+    # parsers
+    "AgentSummary", "ConversationTurn", "EvalResultSummary", "HistorySummary",
+    "KBNode", "ToolCall", "EvalToolCall",
+    "parse_agent", "parse_conversation_turn", "parse_conversations",
+    "parse_eval_result", "parse_eval_tool_calls", "parse_kb_node", "parse_kb_nodes",
+    "parse_rubrics_from_reason",
+    "parse_tool_calls", "strip_tool_markers", "summarize_eval_tool_calls", "summarize_history",
+]

codeer_cli/_validate.py

@@ -0,0 +1,131 @@
+"""Client-side validation for unified-tool payloads.
+
+These checks exist because the backend's form-schema validator is lenient
+(``extra="allow"``) and silently accepts unknown ``type`` strings, which then
+render as blank fields in the web builder. Catching the common mistakes here
+gives actionable errors before the PUT/POST round-trip.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from .constants import (
+    FORM_FIELD_TYPES,
+    MAX_CALL_AGENT_TOOLS,
+    MAX_MEMORY_TOOLS,
+    MAX_TOOLS_PER_AGENT,
+    REQUIRED_FORM_FIELD_KEYS,
+    UNIFIED_TOOL_TYPES,
+)
+
+
+class ToolValidationError(ValueError):
+    """Raised when a unified_tools payload is definitely wrong."""
+
+
+def validate_unified_tools(tools: Iterable[dict[str, Any]] | None) -> list[dict[str, Any]]:
+    """Raise ToolValidationError on invalid payloads; otherwise return the list.
+
+    Validates type strings against the backend enum and walks into
+    ``custom_form_schema.fields`` for request_form tools so we catch the
+    ``type: "text" | "email" | "select"`` mistake the UI renders as blank.
+    """
+    tools_list = list(tools or [])
+    if len(tools_list) > MAX_TOOLS_PER_AGENT:
+        raise ToolValidationError(
+            f"{len(tools_list)} tools configured, max allowed is {MAX_TOOLS_PER_AGENT} "
+            "(see user-docs/agent-creation/tools/index.md)."
+        )
+
+    call_agent_count = sum(1 for t in tools_list if t.get("type") == "call_agent")
+    if call_agent_count > MAX_CALL_AGENT_TOOLS:
+        raise ToolValidationError(
+            f"{call_agent_count} call_agent tools configured, max is {MAX_CALL_AGENT_TOOLS}."
+        )
+
+    memory_count = sum(1 for t in tools_list if t.get("type") == "memory")
+    if memory_count > MAX_MEMORY_TOOLS:
+        raise ToolValidationError(
+            f"{memory_count} memory tools configured, max is {MAX_MEMORY_TOOLS}."
+        )
+
+    for i, tool in enumerate(tools_list):
+        _validate_single_tool(tool, i)
+
+    return tools_list
+
+
+def _validate_single_tool(tool: dict[str, Any], index: int) -> None:
+    prefix = f"unified_tools[{index}]"
+    tool_type = tool.get("type")
+    if tool_type not in UNIFIED_TOOL_TYPES:
+        raise ToolValidationError(
+            f"{prefix}.type = {tool_type!r} is not a valid UnifiedToolType. "
+            f"Valid values: {sorted(UNIFIED_TOOL_TYPES)}."
+        )
+    if not tool.get("id"):
+        raise ToolValidationError(f"{prefix}.id is required and must be non-empty.")
+
+    if tool_type == "request_form":
+        _validate_form_schema(tool.get("custom_form_schema"), prefix)
+    elif tool_type == "knowledge_base":
+        node_ids = tool.get("knowledge_node_ids")
+        if node_ids is None or (isinstance(node_ids, list) and not node_ids):
+            raise ToolValidationError(
+                f"{prefix}: knowledge_base tool needs non-empty knowledge_node_ids."
+            )
+    elif tool_type == "call_agent":
+        if not tool.get("agent_id"):
+            raise ToolValidationError(f"{prefix}: call_agent tool requires agent_id.")
+    elif tool_type == "http_request":
+        cfg = tool.get("http_request")
+        if not cfg or not cfg.get("method") or not cfg.get("url_template"):
+            raise ToolValidationError(
+                f"{prefix}: http_request tool requires http_request.method and http_request.url_template."
+            )
+
+
+def _validate_form_schema(schema: Any, prefix: str) -> None:
+    if schema is None:
+        raise ToolValidationError(
+            f"{prefix}: request_form tool requires custom_form_schema "
+            "(with title, fields[], ...)."
+        )
+    if not isinstance(schema, dict):
+        raise ToolValidationError(f"{prefix}.custom_form_schema must be an object.")
+    fields = schema.get("fields")
+    if not isinstance(fields, list) or not fields:
+        raise ToolValidationError(
+            f"{prefix}.custom_form_schema.fields must be a non-empty list."
+        )
+
+    for j, field in enumerate(fields):
+        fp = f"{prefix}.custom_form_schema.fields[{j}]"
+        if not isinstance(field, dict):
+            raise ToolValidationError(f"{fp} must be an object.")
+        for key in REQUIRED_FORM_FIELD_KEYS:
+            if key not in field or field[key] in (None, ""):
+                raise ToolValidationError(
+                    f"{fp}.{key} is required and must be non-empty."
+                )
+        ftype = field.get("type")
+        if ftype not in FORM_FIELD_TYPES:
+            # The two traps we already hit — surface a hint, not just a rejection.
+            hint = ""
+            if ftype == "text":
+                hint = "  (use 'shortText' for single-line or 'longText' for multi-line)"
+            elif ftype == "email":
+                hint = "  (there is no 'email' type — use 'shortText' and add placeholder/helpText)"
+            elif ftype == "select":
+                hint = "  (use 'dropdown' with options=[{value,label}])"
+            raise ToolValidationError(
+                f"{fp}.type = {ftype!r} is not a valid FormFieldType. "
+                f"Valid: {sorted(FORM_FIELD_TYPES)}.{hint}"
+            )
+        if ftype == "dropdown" or ftype == "radio":
+            options = field.get("options")
+            if not isinstance(options, list) or not options:
+                raise ToolValidationError(
+                    f"{fp}: type={ftype!r} requires non-empty options=[{{value,label}}]."
+                )

codeer_cli/agents.py

@@ -0,0 +1,155 @@
+"""Agent CRUD, versioning, and publishing.
+
+Each function returns the parsed `data` field from the Ninja response envelope.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from ._validate import validate_unified_tools
+from .client import CodeerClient
+
+
+def create(
+    client: CodeerClient,
+    *,
+    workspace_id: str,
+    name: str,
+    system_prompt: str,
+    unified_tools: Optional[List[dict]] = None,
+    use_search: bool = False,
+    llm_model: Optional[str] = None,
+    description: Optional[str] = None,
+    suggested_questions: Optional[List[str]] = None,
+    primary_object_ids: Optional[List[int]] = None,
+    attachment_ids: Optional[List[str]] = None,
+) -> dict:
+    validated_tools = validate_unified_tools(unified_tools)
+    body: dict[str, Any] = {
+        "name": name,
+        "system_prompt": system_prompt,
+        "unified_tools": validated_tools,
+        "primary_object_ids": primary_object_ids or [],
+        "attachment_ids": attachment_ids or [],
+        "use_search": use_search,
+        "suggested_questions": suggested_questions or [],
+    }
+    if description is not None:
+        body["description"] = description
+    if llm_model is not None:
+        body["llm_model"] = llm_model
+    return client.post("/external/agents", json=body)
+
+
+def update(
+    client: CodeerClient,
+    agent_id: str,
+    *,
+    name: str,
+    system_prompt: str,
+    unified_tools: List[dict],
+    use_search: bool,
+    version_note: str = "",
+    description: Optional[str] = None,
+    llm_model: Optional[str] = None,
+    suggested_questions: Optional[List[str]] = None,
+    primary_object_ids: Optional[List[int]] = None,
+    attachment_ids: Optional[List[str]] = None,
+) -> dict:
+    """PUT creates a new AgentHistory snapshot (draft)."""
+    validated_tools = validate_unified_tools(unified_tools)
+    body: dict[str, Any] = {
+        "name": name,
+        "system_prompt": system_prompt,
+        "unified_tools": validated_tools,
+        "primary_object_ids": primary_object_ids or [],
+        "attachment_ids": attachment_ids or [],
+        "use_search": use_search,
+        "version_note": version_note,
+        "suggested_questions": suggested_questions or [],
+    }
+    if description is not None:
+        body["description"] = description
+    if llm_model is not None:
+        body["llm_model"] = llm_model
+    return client.patch(f"/external/agents/{agent_id}", json=body)
+
+
+def get(client: CodeerClient, agent_id: str) -> dict:
+    return client.get(f"/external/agents/{agent_id}")
+
+
+def get_default(client: CodeerClient) -> dict:
+    """Read whichever agent ``CODEER_AGENT_ID`` points to (project env).
+
+    Workspace and organization scope come from the API-key virtual user's
+    profile. Raises if no ``agent_id`` is in scope.
+    """
+    if not client.agent_id:
+        raise ValueError(
+            "No agent_id in scope. Set CODEER_AGENT_ID in .claude/settings.json, "
+            "export it in your shell, or pass agent_id explicitly to from_env()."
+        )
+    return get(client, client.agent_id)
+
+
+def get_latest_draft_history_id(client: CodeerClient, agent_id: str) -> Optional[str]:
+    """Return the id of the most recent unpublished AgentHistory, or None.
+
+    "Most recent" = highest ``version_number`` among ``status == 'draft'``.
+    Returns ``None`` if every version has been published (so there's no
+    open draft to pin a test against).
+    """
+    versions = list_versions(client, agent_id)
+    drafts = [v for v in versions if v.get("status") == "draft"]
+    if not drafts:
+        return None
+    drafts.sort(key=lambda v: v.get("version_number") or 0, reverse=True)
+    return drafts[0].get("id")
+
+
+def get_latest_history_id(client: CodeerClient, agent_id: str) -> Optional[str]:
+    """Return the id of the most recent AgentHistory, draft or published."""
+    versions = list_versions(client, agent_id)
+    if not versions:
+        return None
+    versions.sort(key=lambda v: v.get("version_number") or 0, reverse=True)
+    return versions[0].get("id")
+
+
+def list_in_workspace(client: CodeerClient, workspace_id: str) -> list[dict]:
+    """List **published** agents in a workspace (drafts are hidden).
+
+    If you need drafts too — which is almost always the case while iterating
+    on an agent — use :func:`list_all` with both workspace_id and organization_id.
+    """
+    return client.get("/external/agents")
+
+
+def list_all(
+    client: CodeerClient,
+    *,
+    workspace_id: str,
+    organization_id: str,
+) -> list[dict]:
+    """List every agent in a workspace including drafts.
+
+    Both IDs are required — ``GET /agents/all`` returns 400 ``Organization ID
+    is required`` if you omit ``oid``. Look up the org for a workspace via
+    ``/accounts/me`` → ``profile.workspace_organization_map``.
+    """
+    return client.get("/external/agents/all")
+
+
+def list_versions(client: CodeerClient, agent_id: str) -> list[dict]:
+    return client.get(f"/external/agents/{agent_id}/versions")
+
+
+def get_version(client: CodeerClient, agent_id: str, history_id: str) -> dict:
+    return client.get(f"/external/agents/{agent_id}/versions/{history_id}")
+
+
+def check_impact(client: CodeerClient, agent_id: str) -> dict:
+    """List downstream agents that call this one. Call before publishing breaking changes."""
+    return client.get(f"/external/agents/{agent_id}/impact")

codeer_cli/chats.py

@@ -0,0 +1,87 @@
+"""Chat creation and SSE-streamed agent responses — the Live Test surface.
+
+The send_message() path is the main dogfood driver: open a chat against a
+specific agent version (unpublished draft is fine) and consume the SSE stream
+to get tool calls, reasoning, and final text back.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterator, List, Optional
+
+from .client import CodeerClient
+
+
+def create(
+    client: CodeerClient,
+    *,
+    agent_id: str,
+    title: Optional[str] = None,
+    external_user_id: Optional[str] = None,
+) -> dict:
+    body: dict[str, Any] = {"agent_id": agent_id}
+    if title is not None:
+        body["name"] = title
+    if external_user_id is not None:
+        body["external_user_id"] = external_user_id
+    return client.post("/chats", json=body)
+
+
+def send_published_agent_message(
+    client: CodeerClient,
+    *,
+    chat_id: int,
+    message: str,
+    agent_id: str,
+    external_user_id: Optional[str] = None,
+    attachment_ids: Optional[List[str]] = None,
+    stream: bool = False,
+) -> Iterator[dict] | dict:
+    """Send a user message through the API-key external chat flow.
+
+    API-key chat endpoints use the agent's published version. They accept
+    ``agent_id`` rather than ``agent_history_id``.
+    """
+    body: dict[str, Any] = {"message": message, "agent_id": agent_id, "stream": stream}
+    if external_user_id is not None:
+        body["external_user_id"] = external_user_id
+    if attachment_ids:
+        body["attached_file_uuids"] = attachment_ids
+
+    path = f"/chats/{chat_id}/messages"
+    if stream:
+        return client.stream_sse("POST", path, json=body)
+    return client.post(path, json=body)
+
+
+def send_message(
+    client: CodeerClient,
+    *,
+    chat_id: int,
+    message: str,
+    agent_history_id: str,
+    attachment_ids: Optional[List[str]] = None,
+    stream: bool = True,
+) -> Iterator[dict] | dict:
+    """Send a user message; yield SSE events (if stream=True) or return the final payload.
+
+    ``agent_history_id`` is required — this is how you pin Live Test to a specific
+    (possibly unpublished) agent version without affecting production users.
+    """
+    body: dict[str, Any] = {"message": message, "agent_history_id": agent_history_id}
+    if attachment_ids:
+        body["attachment_ids"] = attachment_ids
+
+    path = f"/chats/{chat_id}/messages"
+    if stream:
+        return client.stream_sse("POST", path, json=body)
+    return client.post(path, json=body)
+
+
+def list_messages(client: CodeerClient, chat_id: int) -> list[dict]:
+    return client.get(f"/chats/{chat_id}/messages")
+
+
+def list_chats(client: CodeerClient) -> list[dict]:
+    return client.get("/chats")
+

codeer_cli/cli.py

@@ -0,0 +1,92 @@
+"""Codeer CLI — unified interface for agent lifecycle operations.
+
+    codeer check
+    codeer agent list|get|apply|diff|versions
+    codeer kb list|files|upload
+    codeer eval list|evaluators|evaluator-create|evaluator-update|run|export|reconcile|cases-apply|rubrics|rubrics-apply
+    codeer history list|get|conversations|negative-feedback
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import AuthError, CodeerClient, CodeerError
+from .commands import check
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="codeer")
+    sub = parser.add_subparsers(dest="group")
+
+    check.register(sub)
+
+    # Phase 2-4: agent, kb, eval commands will register here
+    try:
+        from .commands import agent as agent_cmd
+        agent_cmd.register(sub)
+    except ImportError:
+        pass
+
+    try:
+        from .commands import kb as kb_cmd
+        kb_cmd.register(sub)
+    except ImportError:
+        pass
+
+    try:
+        from .commands import eval_cmd
+        eval_cmd.register(sub)
+    except ImportError:
+        pass
+
+    try:
+        from .commands import history as history_cmd
+        history_cmd.register(sub)
+    except ImportError:
+        pass
+
+    try:
+        from .commands import profile as profile_cmd
+        profile_cmd.register(sub)
+    except ImportError:
+        pass
+
+    args = parser.parse_args(argv)
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 2
+
+    if getattr(args, "no_client", False):
+        client = None
+    else:
+        try:
+            client = CodeerClient.from_env()
+        except AuthError as e:
+            if args.group == "check":
+                print(f"FAIL  Auth: {e}", file=sys.stderr)
+                print("      Configure CODEER_API_KEY or a codeer profile", file=sys.stderr)
+                return 1
+            print(f"auth error: {e}", file=sys.stderr)
+            return 2
+
+    try:
+        return args.func(args, client)
+    except AuthError as e:
+        print(f"auth: {e}", file=sys.stderr)
+        return 3
+    except CodeerError as e:
+        print(f"error: {e}", file=sys.stderr)
+        if e.body:
+            print(json.dumps(e.body, ensure_ascii=False, indent=2, default=str), file=sys.stderr)
+        return 1
+    finally:
+        if client is not None:
+            client.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())