codeer-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{codeer_cli-0.1.0 → codeer_cli-0.1.1}/.gitignore

@@ -22,6 +22,7 @@ venv/
 env/
 .env
 .env.*
+*.env
 !.env.example
 !.env.sample
 session.env

{codeer_cli-0.1.0 → codeer_cli-0.1.1}/API_REFERENCE.md

@@ -66,6 +66,38 @@ Base path: `/organizations/{org_id}/workspaces/{ws_id}/knowledge_bases`
 Attach KB files to an agent by listing their node IDs in the agent's
 `unified_tools[].knowledge_node_ids`.
 
+### Context Object FAQ
+
+Base path: `/external/context-object-faqs`
+
+| Method & path | Purpose |
+| --- | --- |
+| `GET /context-object-faqs` | List FAQ entries, optionally filtered by `context_object_id` |
+| `GET /context-object-faqs/{faq_id}` | Read one FAQ entry |
+| `POST /context-object-faqs` | Create an FAQ entry |
+| `PATCH /context-object-faqs/{faq_id}` | Update the linked context object and/or question |
+| `DELETE /context-object-faqs/{faq_id}` | Delete an FAQ entry |
+
+Create body:
+
+```json
+{"context_object_id": 123, "question": "How do I reset billing?"}
+```
+
+Update body accepts either or both fields:
+
+```json
+{"context_object_id": 456, "question": "How do I update billing?"}
+```
+
+`context_object_id` is the KB file's `snapshot_object_id` from the KB node
+listing. The compact CLI output includes it:
+
+```bash
+codeer kb files --kb-id <kb-id>
+codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+```
+
 ## Stage 3 — Live Test on a specific version
 
 | Method & path | Purpose |

{codeer_cli-0.1.0 → codeer_cli-0.1.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: codeer-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Command line tools for managing Codeer agents over the Codeer API.
 Project-URL: Homepage, https://www.codeer.ai
 Author: Codeer.AI
-License: Proprietary
+License: MIT
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -106,3 +106,44 @@ Validate setup before API work:
 ```bash
 codeer check
 ```
+
+## Output policy for coding agents
+
+The CLI is optimized for Codex, Claude Code, Claude Cowork, and similar coding
+agents that keep command output in their LLM context. Default stdout is a
+compact lifecycle summary, not the full server payload.
+
+Use this pattern during agent lifecycle work:
+
+```bash
+codeer agent list
+codeer history list --agent <agent-id> --limit 50
+codeer eval run --agent <agent-id> --evaluators <evaluator-id> --out .codeer/eval_run.json
+```
+
+Flags:
+
+- `--full` prints bounded extra detail for human inspection. It is still
+  intended to be safe for LLM context.
+- `--out <path>` writes complete diagnostic artifacts to a local file. Use it
+  for raw eval results, full conversation turns, full rubric matrices, and
+  other data that can grow with cases, versions, or turns.
+
+Avoid piping large raw JSON directly into agent chat. Prefer `--out`, then ask
+the coding agent to inspect targeted summaries, IDs, failing cases, or selected
+snippets from the saved file.
+
+## Context Object FAQ
+
+Use Context Object FAQ entries to route high-value questions to a canonical KB
+file when semantic retrieval misses the right source. The FAQ target is a KB
+file's `snapshot_object_id`, shown by `codeer kb files`.
+
+```bash
+codeer kb files --kb-id <kb-id>
+codeer kb faq-list --context-object-id <snapshot-object-id>
+codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+```
+
+After reviewing the dry-run output, rerun the create/update/delete command
+without `--dry-run` to apply it.

{codeer_cli-0.1.0 → codeer_cli-0.1.1}/README.md

@@ -88,3 +88,44 @@ Validate setup before API work:
 ```bash
 codeer check
 ```
+
+## Output policy for coding agents
+
+The CLI is optimized for Codex, Claude Code, Claude Cowork, and similar coding
+agents that keep command output in their LLM context. Default stdout is a
+compact lifecycle summary, not the full server payload.
+
+Use this pattern during agent lifecycle work:
+
+```bash
+codeer agent list
+codeer history list --agent <agent-id> --limit 50
+codeer eval run --agent <agent-id> --evaluators <evaluator-id> --out .codeer/eval_run.json
+```
+
+Flags:
+
+- `--full` prints bounded extra detail for human inspection. It is still
+  intended to be safe for LLM context.
+- `--out <path>` writes complete diagnostic artifacts to a local file. Use it
+  for raw eval results, full conversation turns, full rubric matrices, and
+  other data that can grow with cases, versions, or turns.
+
+Avoid piping large raw JSON directly into agent chat. Prefer `--out`, then ask
+the coding agent to inspect targeted summaries, IDs, failing cases, or selected
+snippets from the saved file.
+
+## Context Object FAQ
+
+Use Context Object FAQ entries to route high-value questions to a canonical KB
+file when semantic retrieval misses the right source. The FAQ target is a KB
+file's `snapshot_object_id`, shown by `codeer kb files`.
+
+```bash
+codeer kb files --kb-id <kb-id>
+codeer kb faq-list --context-object-id <snapshot-object-id>
+codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+```
+
+After reviewing the dry-run output, rerun the create/update/delete command
+without `--dry-run` to apply it.

{codeer_cli-0.1.0 → codeer_cli-0.1.1}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codeer-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Command line tools for managing Codeer agents over the Codeer API."
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [{ name = "Codeer.AI" }]
-license = { text = "Proprietary" }
+license = { text = "MIT" }
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Environment :: Console",
@@ -23,6 +23,11 @@ dependencies = [
   "httpx>=0.27",
 ]
 
+[dependency-groups]
+dev = [
+  "ruff>=0.11",
+]
+
 [project.urls]
 Homepage = "https://www.codeer.ai"
 

{codeer_cli-0.1.0 → codeer_cli-0.1.1}/src/codeer_cli/cli.py

@@ -2,7 +2,7 @@
 
     codeer check
     codeer agent list|get|apply|diff|versions
-    codeer kb list|files|upload
+    codeer kb list|files|upload|faq-list|faq-get|faq-create|faq-update|faq-delete
     codeer eval list|evaluators|evaluator-create|evaluator-update|run|export|reconcile|cases-apply|rubrics|rubrics-apply
     codeer history list|get|conversations|negative-feedback
 """
@@ -18,7 +18,31 @@ from .commands import check
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="codeer")
+    parser = argparse.ArgumentParser(
+        prog="codeer",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="Codeer CLI — self-describing agent lifecycle tools.",
+        epilog="""\
+Safe workflow for coding agents:
+  codeer check --json
+  codeer agent list
+  codeer agent get <agent-id> --full
+  codeer kb list
+  codeer eval list --agent <agent-id>
+  codeer eval evaluators
+  codeer agent diff --agent <agent-id> --from-version <n> --to-version <n>
+  codeer eval reconcile --agent <agent-id> --manifest .codeer/eval_cases.json
+
+Preview mutations before applying:
+  codeer agent apply --payload agent.json --dry-run
+  codeer eval cases-apply --agent <agent-id> --cases eval_cases.json --dry-run
+  codeer eval rubrics-apply --rubrics rubrics.json --dry-run
+  codeer kb upload --dir kb --name "Product KB" --dry-run
+  codeer kb faq-create --context-object-id <snapshot-object-id> --question "..." --dry-run
+
+Use --out <path> for large raw artifacts; stdout defaults to compact summaries.
+""",
+    )
     sub = parser.add_subparsers(dest="group")
 
     check.register(sub)
@@ -67,6 +91,16 @@ def main(argv: list[str] | None = None) -> int:
             client = CodeerClient.from_env()
         except AuthError as e:
             if args.group == "check":
+                if getattr(args, "json", False):
+                    print(json.dumps({
+                        "status": "fail",
+                        "auth": {
+                            "ok": False,
+                            "error": str(e),
+                        },
+                        "next_step": "Configure CODEER_API_KEY or a codeer profile",
+                    }, ensure_ascii=False, indent=2))
+                    return 1
                 print(f"FAIL  Auth: {e}", file=sys.stderr)
                 print("      Configure CODEER_API_KEY or a codeer profile", file=sys.stderr)
                 return 1

codeer_cli-0.1.1/src/codeer_cli/commands/_util.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+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
+
+
+NOISY_KEYS = {
+    "avatar",
+    "brand",
+    "creator",
+    "default_organization_id",
+    "default_scopes",
+    "default_workspace_id",
+    "is_owner",
+    "members",
+    "my_permissions",
+    "owner",
+    "profile",
+    "source_creator",
+    "user_role",
+    "workspace_organization_map",
+}
+
+
+def strip_noisy_fields(value: Any) -> Any:
+    """Remove server/account metadata that is not useful for agent lifecycle work."""
+    if isinstance(value, list):
+        return [strip_noisy_fields(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+
+    out = {}
+    for key, item in value.items():
+        if key in NOISY_KEYS:
+            continue
+        if key == "workspace" and isinstance(item, dict):
+            out[key] = {
+                k: item.get(k)
+                for k in ("id", "name", "organization_id")
+                if item.get(k) is not None
+            }
+            continue
+        out[key] = strip_noisy_fields(item)
+    return out
+
+
+def print_json(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2, default=str))
+
+
+def write_json(path: str | None, value: Any) -> None:
+    if not path:
+        return
+    Path(path).write_text(json.dumps(value, ensure_ascii=False, indent=2, default=str) + "\n")
+    log(f"wrote full detail to {path}")

{codeer_cli-0.1.0 → codeer_cli-0.1.1}/src/codeer_cli/commands/agent.py

@@ -2,33 +2,48 @@ 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
+from ._util import log, print_json, strip_noisy_fields, truncate, write_json
 
 
 def register(subparsers):
-    agent = subparsers.add_parser("agent", help="Agent CRUD, versioning, publishing")
+    agent = subparsers.add_parser("agent", help="Agent CRUD and versioning")
     sub = agent.add_subparsers(dest="action", required=True)
 
     # codeer agent list
-    p = sub.add_parser("list", help="List agents in workspace")
+    p = sub.add_parser(
+        "list",
+        help="List agents in workspace. Defaults to a lifecycle summary safe for Codex/Claude context.",
+    )
+    p.add_argument("--full", action="store_true",
+                   help="Print bounded detail instead of the default lifecycle summary.")
+    p.add_argument("--out", default=None,
+                   help="Write stripped full server detail to this file; stdout stays compact.")
     p.set_defaults(func=run_list)
 
     # codeer agent get <id>
-    p = sub.add_parser("get", help="Read agent details")
+    p = sub.add_parser(
+        "get",
+        help="Read one agent. Defaults to summary; use --full for prompt/tool detail or --out for an artifact.",
+    )
     p.add_argument("agent_id")
+    p.add_argument("--full", action="store_true",
+                   help="Print stripped full agent config, including system_prompt and tools.")
+    p.add_argument("--out", default=None,
+                   help="Write stripped full agent config to this file.")
     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 = sub.add_parser("apply", help="Create or update agent from JSON payload; run --dry-run first")
     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("--dry-run", action="store_true",
+                   help="Validate payload and print intended mutation without writing server state.")
     p.add_argument("--out", default=None, help="Write result JSON to this file too")
     p.set_defaults(func=run_apply)
 
@@ -43,27 +58,104 @@ def register(subparsers):
     p.set_defaults(func=run_diff)
 
     # codeer agent versions --agent <id>
-    p = sub.add_parser("versions", help="List version history for an agent")
+    p = sub.add_parser(
+        "versions",
+        help="List version history. Defaults to version metadata only; use --out for full snapshots.",
+    )
     p.add_argument("--agent", required=True)
+    p.add_argument("--full", action="store_true",
+                   help="Add bounded prompt/tool size metadata; full snapshots still require --out.")
+    p.add_argument("--out", default=None,
+                   help="Write stripped full version snapshots to this file; stdout stays compact.")
     p.set_defaults(func=run_versions)
 
 
+def _tool_summary(tools: list[dict] | None) -> list[dict]:
+    out = []
+    for t in tools or []:
+        form = t.get("custom_form_schema") if isinstance(t.get("custom_form_schema"), dict) else {}
+        out.append({
+            "id": t.get("id"),
+            "type": t.get("type"),
+            "name": t.get("name"),
+            "knowledge_node_count": len(t.get("knowledge_node_ids") or []),
+            "form_title": form.get("title"),
+            "invocation_preview": truncate(t.get("invocation_instruction") or "", 160),
+        })
+    return out
+
+
+def _agent_summary(agent: dict, *, full: bool = False) -> dict:
+    tools = agent.get("unified_tools") or agent.get("tools") or []
+    row = {
+        "id": agent.get("id"),
+        "name": agent.get("name"),
+        "workspace": {
+            "id": agent.get("workspace_id") or (agent.get("workspace") or {}).get("id"),
+            "name": (agent.get("workspace") or {}).get("name"),
+        },
+        "publish_state": agent.get("publish_state"),
+        "version": agent.get("version"),
+        "latest_version_number": agent.get("latest_version_number"),
+        "published_version_number": agent.get("published_version_number"),
+        "publish_history_id": agent.get("publish_history_id"),
+        "llm_model": agent.get("llm_model"),
+        "agent_type": agent.get("agent_type"),
+        "updated_at": agent.get("updated_at"),
+        "tool_count": len(tools),
+        "system_prompt_chars": len(agent.get("system_prompt") or ""),
+    }
+    if full:
+        row["description"] = agent.get("description") or ""
+        row["use_search"] = agent.get("use_search")
+        row["suggested_questions"] = agent.get("suggested_questions") or []
+        row["tools"] = _tool_summary(tools)
+        row["system_prompt_preview"] = truncate(agent.get("system_prompt") or "", 1200)
+    return row
+
+
 
 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))
+    write_json(args.out, strip_noisy_fields(result))
+    print_json([_agent_summary(a, full=args.full) for a in result])
     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))
+    full_result = strip_noisy_fields(result)
+    write_json(args.out, full_result)
+    print_json(full_result if args.full else _agent_summary(result))
     return 0
 
 
 def run_apply(args, client) -> int:
     body = json.loads(Path(args.payload).read_text())
+    missing = [field for field in ("name", "system_prompt") if not body.get(field)]
+    if missing:
+        log(f"error: payload missing required field(s): {', '.join(missing)}")
+        return 2
+
+    if args.dry_run:
+        operation = "update" if args.agent_id else "create"
+        result = {
+            "dry_run": True,
+            "operation": operation,
+            "agent_id": args.agent_id,
+            "payload": str(Path(args.payload)),
+            "name": body.get("name"),
+            "system_prompt_chars": len(body.get("system_prompt") or ""),
+            "tool_count": len(body.get("unified_tools") or []),
+            "use_search": body.get("use_search", False),
+            "llm_model": body.get("llm_model"),
+            "version_note": args.note if args.agent_id else None,
+            "would_write_server_state": True,
+            "next_step": "Review this summary, then rerun without --dry-run after approval.",
+        }
+        print_json(result)
+        return 0
 
     if args.agent_id:
         body.pop("workspace_id", None)
@@ -118,7 +210,22 @@ def run_apply(args, client) -> int:
 
 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))
+    write_json(args.out, strip_noisy_fields(versions))
+    rows = []
+    for v in versions:
+        row = {
+            "id": v.get("id"),
+            "version_number": v.get("version_number"),
+            "status": v.get("status"),
+            "was_published": v.get("was_published"),
+            "version_note": v.get("version_note") or "",
+            "created_at": v.get("created_at"),
+        }
+        if args.full:
+            row["system_prompt_chars"] = len(v.get("system_prompt") or "")
+            row["tool_count"] = len(v.get("unified_tools") or v.get("tools") or [])
+        rows.append(row)
+    print_json(rows)
     return 0
 
 

codeer_cli-0.1.1/src/codeer_cli/commands/check.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from ..client import AuthError, CodeerError
+
+
+def register(subparsers):
+    p = subparsers.add_parser("check", help="Validate auth, workspace, and agent config")
+    p.add_argument("--json", action="store_true", help="Print machine-readable setup status")
+    p.set_defaults(func=run)
+
+
+def run(args, client) -> int:
+    errors = []
+    report = {
+        "status": "ok",
+        "auth": {"ok": False},
+        "workspace": {"ok": False},
+        "organization": {"ok": False},
+        "agent": {"ok": False, "configured": False, "optional": True},
+    }
+
+    try:
+        me = client.get_me()
+    except AuthError:
+        if args.json:
+            report["status"] = "fail"
+            report["auth"]["error"] = "API key missing, invalid, expired, or revoked (401/403)"
+            report["next_step"] = "Create an admin workspace API key and export CODEER_API_KEY before running codeer"
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+            return 1
+        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:
+        if args.json:
+            report["status"] = "fail"
+            report["auth"]["error"] = str(e)
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+            return 1
+        print(f"FAIL  Auth: {e}", file=sys.stderr)
+        return 1
+
+    profile = me.get("profile", {})
+    email = me.get("email") or "(unknown)"
+    report["auth"] = {"ok": True, "email": email}
+    if not args.json:
+        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)
+        report["workspace"] = {"ok": True, "id": ws_id, "name": ws_name}
+        if ws_name:
+            if not args.json:
+                print(f"  OK  Workspace: {ws_name} ({ws_id})")
+        else:
+            if not args.json:
+                print(f"  OK  Workspace: {ws_id}")
+
+    if org_id:
+        report["organization"] = {"ok": True, "id": org_id}
+        if not args.json:
+            print(f"  OK  Organization: {org_id}")
+
+    agent_id = client.agent_id
+    if agent_id:
+        report["agent"] = {"ok": False, "configured": True, "optional": True, "id": agent_id}
+        try:
+            agent = client.get(f"/external/agents/{agent_id}")
+            report["agent"].update({"ok": True, "name": agent.get("name", "(unnamed)")})
+            if not args.json:
+                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:
+        if not args.json:
+            print("  --  Agent: CODEER_AGENT_ID not set (optional)")
+
+    if errors:
+        report["messages"] = errors
+        if any(e.startswith("FAIL") for e in errors):
+            report["status"] = "fail"
+        elif report["status"] == "ok":
+            report["status"] = "warn"
+
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        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