codeer-cli 0.1.0__py3-none-any.whl

codeer_cli/commands/history.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import json
+import os
+
+from .. import agents as agents_mod
+from .. import chats as chats_mod
+from .. import histories as hist_mod
+from ._util import log
+
+
+def register(subparsers):
+    h = subparsers.add_parser("history", help="Conversation history analysis")
+    sub = h.add_subparsers(dest="action", required=True)
+
+    # codeer history list
+    p = sub.add_parser("list", help="List conversation histories")
+    p.add_argument("--agent", default=None)
+    p.add_argument("--user", default=None, help="Filter by external_user_id")
+    p.add_argument("--feedback", default=None, help="positive / negative / any")
+    p.add_argument("--exclude-users", default=None,
+                   help="Comma-separated external_user_ids to exclude")
+    p.add_argument("--version", type=int, default=None,
+                   help="Filter to histories created while this agent version was live (requires --agent)")
+    p.add_argument("--limit", type=int, default=500)
+    p.add_argument("--offset", type=int, default=0)
+    p.set_defaults(func=run_list)
+
+    # codeer history get <id>
+    p = sub.add_parser("get", help="Get single history metadata")
+    p.add_argument("history_id", type=int)
+    p.set_defaults(func=run_get)
+
+    # codeer history conversations <id>
+    p = sub.add_parser("conversations", help="Get all turns in a history")
+    p.add_argument("history_id", type=int)
+    p.set_defaults(func=run_conversations)
+
+    # codeer history negative-feedback
+    p = sub.add_parser("negative-feedback", help="Surface assistant turns with negative feedback")
+    p.add_argument("--agent", required=True)
+    p.add_argument("--exclude-users", default=None,
+                   help="Comma-separated external_user_ids to exclude")
+    p.add_argument("--limit", type=int, default=500)
+    p.set_defaults(func=run_negative_feedback)
+
+    # codeer history create --agent <id> --message ...
+    p = sub.add_parser("create", help="Create a real persisted conversation history")
+    p.add_argument("--agent", default=None, help="Agent ID (defaults to CODEER_AGENT_ID)")
+    p.add_argument("--title", default=None, help="Conversation title")
+    p.add_argument("--user", default=None, help="external_user_id to associate with the history")
+    p.add_argument("--message", action="append", required=True,
+                   help="User message to send. Repeat for multi-turn histories.")
+    p.set_defaults(func=run_create)
+
+
+def _parse_exclude(raw: str | None) -> list[str]:
+    if not raw:
+        return []
+    return [x.strip() for x in raw.split(",") if x.strip()]
+
+
+def _version_window(client, agent_id: str, version_number: int) -> tuple[str | None, str | None]:
+    """Compute (start, end) ISO timestamps for when a version was the live published one."""
+    versions = agents_mod.list_versions(client, agent_id)
+    published = sorted(
+        [v for v in versions if v.get("was_published") or v.get("status") == "published"],
+        key=lambda v: v.get("version_number") or 0,
+    )
+    target = None
+    next_version = None
+    for i, v in enumerate(published):
+        if v.get("version_number") == version_number:
+            target = v
+            if i + 1 < len(published):
+                next_version = published[i + 1]
+            break
+    if target is None:
+        return None, None
+    start = target.get("published_at") or target.get("created_at")
+    end = next_version.get("published_at") or next_version.get("created_at") if next_version else None
+    return start, end
+
+
+def run_list(args, client) -> int:
+    agent_id = args.agent or os.environ.get("CODEER_AGENT_ID")
+    exclude = _parse_exclude(args.exclude_users)
+    workspace_id, organization_id = client.resolve_scope()
+
+    if args.version is not None and not agent_id:
+        log("error: --version requires --agent")
+        return 2
+
+    rows = hist_mod.list(
+        client,
+        agent_id=agent_id,
+        workspace_id=workspace_id,
+        organization_id=organization_id,
+        external_user_id=args.user,
+        feedback_filter=args.feedback,
+        exclude_users=exclude,
+        limit=args.limit,
+        offset=args.offset,
+    )
+
+    if args.version is not None:
+        start, end = _version_window(client, agent_id, args.version)
+        if start is None:
+            log(f"error: version {args.version} not found among published versions")
+            return 2
+        log(f"filtering to version {args.version} window: {start} .. {end or 'now'}")
+        filtered = []
+        for h in rows:
+            created = h.get("created_at") or ""
+            if created < start:
+                continue
+            if end and created >= end:
+                continue
+            filtered.append(h)
+        rows = filtered
+
+    print(json.dumps(rows, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_get(args, client) -> int:
+    result = hist_mod.get(client, args.history_id)
+    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_conversations(args, client) -> int:
+    result = hist_mod.get_conversations(client, args.history_id)
+    print(json.dumps(result, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_negative_feedback(args, client) -> int:
+    exclude = _parse_exclude(args.exclude_users)
+    workspace_id, organization_id = client.resolve_scope()
+    rows = hist_mod.list_negative_feedback_turns(
+        client,
+        agent_id=args.agent,
+        workspace_id=workspace_id,
+        organization_id=organization_id,
+        exclude_users=exclude,
+        limit=args.limit,
+    )
+    print(json.dumps(rows, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def _history_url(client, workspace_id: str, history_id: int) -> str:
+    base = client.base_url.rstrip("/")
+    if base.startswith("https://api."):
+        base = "https://" + base[len("https://api."):]
+    return f"{base}/workspaces/{workspace_id}/histories/{history_id}"
+
+
+def run_create(args, client) -> int:
+    agent_id = args.agent or os.environ.get("CODEER_AGENT_ID")
+    if not agent_id:
+        log("error: --agent is required or set CODEER_AGENT_ID")
+        return 2
+
+    workspace_id, _ = client.resolve_scope()
+    title = args.title or (args.message[0].strip()[:80] if args.message else "CLI conversation")
+
+    chat = chats_mod.create(
+        client,
+        agent_id=agent_id,
+        title=title,
+        external_user_id=args.user,
+    )
+    history_id = chat["id"]
+    message_results = []
+
+    for idx, message in enumerate(args.message, 1):
+        log(f"sending turn {idx}/{len(args.message)}")
+        result = chats_mod.send_published_agent_message(
+            client,
+            chat_id=history_id,
+            message=message,
+            agent_id=agent_id,
+            external_user_id=args.user,
+            stream=False,
+        )
+        message_results.append(result)
+
+    conversations = hist_mod.get_conversations(client, history_id)
+    out = {
+        "agent_id": agent_id,
+        "history_id": history_id,
+        "external_user_id": args.user,
+        "url": _history_url(client, workspace_id, history_id),
+        "messages": message_results,
+        "conversations": conversations,
+    }
+    print(json.dumps(out, ensure_ascii=False, indent=2, default=str))
+    return 0

codeer_cli/commands/kb.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+from .. import kb as kb_mod
+from ._util import log
+
+POLL_INTERVAL = 3
+POLL_TIMEOUT = 600
+
+
+def register(subparsers):
+    k = subparsers.add_parser("kb", help="Knowledge base operations")
+    sub = k.add_subparsers(dest="action", required=True)
+
+    # codeer kb list
+    p = sub.add_parser("list", help="List knowledge bases in workspace")
+    p.add_argument("--parent-id", default=None, help="List children of this node (omit for top-level KBs)")
+    p.set_defaults(func=run_list)
+
+    # codeer kb files
+    p = sub.add_parser("files", help="List files inside a knowledge base")
+    p.add_argument("--kb-id", required=True, help="KB node UUID to list files from")
+    p.set_defaults(func=run_files)
+
+    p = sub.add_parser("upload", help="Create/reuse KB and upload files from a directory")
+    p.add_argument("--dir", required=True, help="Directory containing files to upload")
+    p.add_argument("--name", required=True, help="KB display name (idempotent on name)")
+    p.add_argument("--description", default=None)
+    p.add_argument("--glob", default="*", help="File glob within --dir (default: all files)")
+    p.add_argument("--out", default=None, help="Write result JSON to this file too")
+    p.add_argument("--poll-timeout", type=int, default=POLL_TIMEOUT)
+    p.set_defaults(func=run_upload)
+
+
+def run_list(args, client) -> int:
+    workspace_id, organization_id = client.resolve_scope()
+    nodes = kb_mod.list_nodes(
+        client, organization_id=organization_id, workspace_id=workspace_id,
+        parent_id=getattr(args, "parent_id", None),
+    )
+    print(json.dumps(nodes, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_files(args, client) -> int:
+    workspace_id, organization_id = client.resolve_scope()
+    nodes = kb_mod.list_nodes(
+        client, organization_id=organization_id, workspace_id=workspace_id,
+        parent_id=args.kb_id,
+    )
+    print(json.dumps(nodes, ensure_ascii=False, indent=2, default=str))
+    return 0
+
+
+def run_upload(args, client) -> int:
+    workspace_id, organization_id = client.resolve_scope()
+    kb_dir = Path(args.dir).resolve()
+    if not kb_dir.is_dir():
+        log(f"error: --dir {kb_dir} is not a directory")
+        return 2
+
+    files = sorted(p for p in kb_dir.glob(args.glob) if p.is_file())
+    if not files:
+        log(f"error: no files matched in {kb_dir} (glob={args.glob})")
+        return 2
+    log(f"uploading {len(files)} files to KB '{args.name}'")
+
+    existing = kb_mod.list_nodes(client, organization_id=organization_id, workspace_id=workspace_id)
+    match = next((n for n in existing if n.get("name") == args.name), None)
+    if match:
+        kb_id = match.get("node_id") or match.get("id")
+        log(f"reusing KB '{args.name}' id={kb_id}")
+    else:
+        created = kb_mod.create_kb(
+            client, organization_id=organization_id, workspace_id=workspace_id,
+            name=args.name, description=args.description,
+        )
+        kb_id = created.get("node_id") or created.get("id")
+        log(f"created KB '{args.name}' id={kb_id}")
+
+    t0 = time.time()
+    resp = kb_mod.upload_files(
+        client, organization_id=organization_id, workspace_id=workspace_id,
+        kb_id=kb_id, file_paths=[str(p) for p in files], parent_id=kb_id,
+    )
+    log(f"upload returned in {time.time()-t0:.1f}s, {len(resp.get('nodes', []))} nodes")
+
+    nodes = resp.get("nodes", [])
+    node_ids = [n["node_id"] for n in nodes if n.get("node_id")]
+    name_to_id = {n.get("original_name", "?"): n.get("node_id") for n in nodes}
+    if not node_ids:
+        log("error: no node_ids returned from upload")
+        return 1
+
+    deadline = time.time() + args.poll_timeout
+    last_status = []
+    while time.time() < deadline:
+        last_status = kb_mod.file_status(
+            client, organization_id=organization_id, workspace_id=workspace_id, node_ids=node_ids,
+        )
+        counts: dict[str, int] = {}
+        for s in last_status:
+            k = s.get("status", "?").upper()
+            counts[k] = counts.get(k, 0) + 1
+        log(f"  status: {counts}")
+        terminal = sum(counts.get(k, 0) for k in ("READY", "FAILED", "ERROR"))
+        if terminal >= len(node_ids):
+            break
+        time.sleep(POLL_INTERVAL)
+
+    not_ready = [s for s in last_status if s.get("status", "").upper() != "READY"]
+    if not_ready:
+        log(f"warning: {len(not_ready)} files NOT in READY state")
+        for s in not_ready:
+            log(f"  {s}")
+
+    result = {"kb_id": kb_id, "node_ids": node_ids, "name_to_id": name_to_id}
+    out_text = json.dumps(result, indent=2, ensure_ascii=False)
+    print(out_text)
+    if args.out:
+        Path(args.out).write_text(out_text + "\n")
+        log(f"wrote {args.out}")
+    return 0 if not not_ready else 1

codeer_cli/commands/profile.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+from typing import Any
+
+from ..client import DEFAULT_CODEER_API_BASE
+
+CONFIG_DIR = ".codeer"
+LOCAL_PROFILE_FILE = "profile"
+GLOBAL_PROFILE_FILE = "profiles.json"
+
+
+def register(subparsers):
+    p = subparsers.add_parser("profile", help="Manage named API-key profiles")
+    p.set_defaults(no_client=True)
+    sub = p.add_subparsers(dest="action")
+
+    current = sub.add_parser("current", help="Show the selected profile")
+    current.set_defaults(func=run_current, no_client=True)
+
+    list_ = sub.add_parser("list", help="List configured profiles")
+    list_.set_defaults(func=run_list, no_client=True)
+
+    add = sub.add_parser("add", help="Add or update a global profile")
+    add.add_argument("name")
+    add.add_argument("--api-base", default=DEFAULT_CODEER_API_BASE)
+    add.set_defaults(func=run_add, no_client=True)
+
+    use = sub.add_parser("use", help="Use a profile in this directory")
+    use.add_argument("name")
+    use.set_defaults(func=run_use, no_client=True)
+
+    default = sub.add_parser("default", help="Set the global default profile")
+    default.add_argument("name")
+    default.set_defaults(func=run_default, no_client=True)
+
+    remove = sub.add_parser("remove", help="Remove a global profile")
+    remove.add_argument("name")
+    remove.set_defaults(func=run_remove, no_client=True)
+
+
+def resolve_profile() -> dict[str, str | None]:
+    if "CODEER_API_KEY" in os.environ:
+        return {
+            "name": os.environ.get("CODEER_PROFILE"),
+            "source": "environment",
+            "api_key": os.environ["CODEER_API_KEY"],
+            "api_base": os.environ.get("CODEER_API_BASE") or DEFAULT_CODEER_API_BASE,
+        }
+
+    selected = os.environ.get("CODEER_PROFILE")
+    source = "CODEER_PROFILE" if selected else None
+
+    if not selected:
+        local = _find_local_profile(Path.cwd())
+        if local:
+            selected = local.read_text(encoding="utf-8").strip()
+            source = str(local)
+
+    data = _read_profiles()
+    if not selected:
+        selected = data.get("default")
+        source = str(_profiles_path()) if selected else None
+
+    if not selected:
+        return {"name": None, "source": None, "api_key": None, "api_base": DEFAULT_CODEER_API_BASE}
+
+    profile = (data.get("profiles") or {}).get(selected)
+    if not isinstance(profile, dict):
+        return {"name": selected, "source": source, "api_key": None, "api_base": DEFAULT_CODEER_API_BASE}
+
+    return {
+        "name": selected,
+        "source": source,
+        "api_key": profile.get("api_key"),
+        "api_base": profile.get("api_base") or DEFAULT_CODEER_API_BASE,
+    }
+
+
+def run_current(args, client=None) -> int:
+    resolved = resolve_profile()
+    name = resolved.get("name") or "(none)"
+    source = resolved.get("source") or "(none)"
+    api_key = resolved.get("api_key")
+    api_base = resolved.get("api_base") or DEFAULT_CODEER_API_BASE
+
+    print(f"Profile: {name}")
+    print(f"Source: {source}")
+    print(f"API base: {api_base}")
+    print(f"API key: {_mask(api_key) if api_key else '(missing)'}")
+    return 0 if api_key else 1
+
+
+def run_list(args, client=None) -> int:
+    data = _read_profiles()
+    profiles = data.get("profiles") or {}
+    default = data.get("default")
+    if not profiles:
+        print("No profiles configured")
+        return 0
+
+    for name in sorted(profiles):
+        marker = "*" if name == default else " "
+        api_base = profiles[name].get("api_base") or DEFAULT_CODEER_API_BASE
+        print(f"{marker} {name}\t{api_base}")
+    return 0
+
+
+def run_add(args, client=None) -> int:
+    api_key = getpass.getpass("API key: ").strip()
+    if not api_key:
+        print("error: API key is required", file=sys.stderr)
+        return 2
+
+    data = _read_profiles()
+    profiles = data.setdefault("profiles", {})
+    profiles[args.name] = {"api_key": api_key, "api_base": args.api_base}
+    if not data.get("default"):
+        data["default"] = args.name
+    _write_profiles(data)
+    print(f"Saved profile {args.name}")
+    return 0
+
+
+def run_use(args, client=None) -> int:
+    data = _read_profiles()
+    if args.name not in (data.get("profiles") or {}):
+        print(f"error: profile {args.name!r} does not exist", file=sys.stderr)
+        return 2
+
+    path = Path.cwd() / CONFIG_DIR / LOCAL_PROFILE_FILE
+    path.parent.mkdir(mode=0o700, exist_ok=True)
+    path.write_text(args.name + "\n", encoding="utf-8")
+    print(f"Using profile {args.name} in {Path.cwd()}")
+    return 0
+
+
+def run_default(args, client=None) -> int:
+    data = _read_profiles()
+    if args.name not in (data.get("profiles") or {}):
+        print(f"error: profile {args.name!r} does not exist", file=sys.stderr)
+        return 2
+    data["default"] = args.name
+    _write_profiles(data)
+    print(f"Default profile is {args.name}")
+    return 0
+
+
+def run_remove(args, client=None) -> int:
+    data = _read_profiles()
+    profiles = data.get("profiles") or {}
+    if args.name not in profiles:
+        print(f"error: profile {args.name!r} does not exist", file=sys.stderr)
+        return 2
+
+    del profiles[args.name]
+    if data.get("default") == args.name:
+        data["default"] = sorted(profiles)[0] if profiles else None
+    _write_profiles(data)
+    print(f"Removed profile {args.name}")
+    return 0
+
+
+def _profiles_path() -> Path:
+    return Path.home() / CONFIG_DIR / GLOBAL_PROFILE_FILE
+
+
+def _read_profiles() -> dict[str, Any]:
+    path = _profiles_path()
+    if not path.exists():
+        return {"default": None, "profiles": {}}
+    with path.open(encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"Invalid profile config: {path}")
+    data.setdefault("profiles", {})
+    return data
+
+
+def _write_profiles(data: dict[str, Any]) -> None:
+    path = _profiles_path()
+    path.parent.mkdir(mode=0o700, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+
+def _find_local_profile(start: Path) -> Path | None:
+    for path in [start, *start.parents]:
+        candidate = path / CONFIG_DIR / LOCAL_PROFILE_FILE
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _mask(value: str | None) -> str:
+    if not value:
+        return "(missing)"
+    if len(value) <= 8:
+        return "*" * len(value)
+    return value[:4] + "..." + value[-4:]

codeer_cli/constants.py

@@ -0,0 +1,66 @@
+"""Enum values and known identifiers, kept in sync with the backend + frontend.
+
+Having these in one place stops callers from inventing strings like ``"text"``
+or ``"select"`` that silently save as broken config. If you're adding a new
+tool type or form field type, update both the backend (``codeer/agents/types.py``,
+``web/src/types/requestForm.ts``) and this file.
+"""
+
+from __future__ import annotations
+
+# Unified tool types accepted on an Agent's ``unified_tools[]`` list.
+# Source: codeer/agents/types.py :: UnifiedToolType
+UNIFIED_TOOL_TYPES: frozenset[str] = frozenset({
+    "knowledge_base",
+    "web_search",
+    "call_agent",
+    "image_generation",
+    "request_form",
+    "payment",
+    "memory",
+    "http_request",
+})
+
+# Valid type values for a field inside ``custom_form_schema.fields[]``.
+# Source: web/src/types/requestForm.ts :: FormFieldType
+# NOTE: there is no ``"email"`` / ``"text"`` / ``"select"`` type. Common gotchas:
+#   email  → use "shortText" (plus helpText/placeholder to hint the format)
+#   text   → use "shortText" (single-line) or "longText" (multi-line)
+#   select → use "dropdown" (with ``options: [{value,label}]``)
+FORM_FIELD_TYPES: frozenset[str] = frozenset({
+    "shortText",
+    "longText",
+    "number",
+    "dropdown",
+    "radio",
+    "checkbox",
+    "date",
+})
+
+# An agent's ``publish_state``.
+# Source: codeer/agents/types.py :: PublishState
+PUBLISH_STATES: frozenset[str] = frozenset({
+    "private",
+    "in_organization",
+    "public",
+})
+
+# ``AgentHistory.status`` values returned by ``GET /agents/{id}/histories``.
+# Source: codeer/agents/types.py :: AgentHistoryStatus
+AGENT_HISTORY_STATUSES: frozenset[str] = frozenset({
+    "draft",
+    "published",
+    "archived",
+})
+
+# Hard limits mirrored from user-docs/agent-creation/tools/index.md. Enforce
+# client-side so we fail before the server rejects.
+MAX_TOOLS_PER_AGENT = 10
+MAX_CALL_AGENT_TOOLS = 5
+MAX_MEMORY_TOOLS = 1
+
+# Fields that must be set (and non-empty) on every form-builder field so the UI
+# renders labels and the backend can capture submissions by a stable key.
+# ``name`` is the submission key, ``label`` is the analytics/column name,
+# ``question`` is the user-facing prompt.
+REQUIRED_FORM_FIELD_KEYS: tuple[str, ...] = ("id", "type", "name", "label", "question", "required")