kelam 0.1.0__tar.gz

kelam-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: kelam
+Version: 0.1.0
+Summary: Build and run voice AI agents from the terminal — the Kelam CLI.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: kelam-core>=0.1.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typer<1,>=0.12
+
+# kelam
+
+Build and run voice AI agents from the terminal — the **Kelam CLI**.
+
+A thin, dependency-light client (httpx + typer + the shared `kelam-core` contract) for the
+Kelam voice-agent control plane. Create agents, deploy them, place real phone calls, talk to
+them in the browser, send texts, and export call data — all from `kelam`.
+
+## Install
+
+```sh
+curl -fsSL https://kelam.sh | sh        # one-command installer
+# or:
+uv tool install kelam
+pipx install kelam
+```
+
+## Configure
+
+```sh
+export KELAM_API_URL=https://<your-kelam-host>
+export KELAM_PASSWORD=<password>        # only if the server uses shared-password auth
+kelam list
+```
+
+## The loop
+
+```sh
+kelam create my-bot              # scaffold + provision a phone number
+kelam deploy <agent_id>          # assemble + cache the runtime
+kelam call   <agent_id> +1206... # place a real outbound call
+kelam web    <agent_id>          # or talk in the browser, no phone number
+kelam export --since 7d          # call logs + derived metrics
+```
+
+The platform (API + voice worker) lives in the separate `kelam-backend` package; this package
+is just the operator CLI.

kelam-0.1.0/README.md

@@ -0,0 +1,37 @@
+# kelam
+
+Build and run voice AI agents from the terminal — the **Kelam CLI**.
+
+A thin, dependency-light client (httpx + typer + the shared `kelam-core` contract) for the
+Kelam voice-agent control plane. Create agents, deploy them, place real phone calls, talk to
+them in the browser, send texts, and export call data — all from `kelam`.
+
+## Install
+
+```sh
+curl -fsSL https://kelam.sh | sh        # one-command installer
+# or:
+uv tool install kelam
+pipx install kelam
+```
+
+## Configure
+
+```sh
+export KELAM_API_URL=https://<your-kelam-host>
+export KELAM_PASSWORD=<password>        # only if the server uses shared-password auth
+kelam list
+```
+
+## The loop
+
+```sh
+kelam create my-bot              # scaffold + provision a phone number
+kelam deploy <agent_id>          # assemble + cache the runtime
+kelam call   <agent_id> +1206... # place a real outbound call
+kelam web    <agent_id>          # or talk in the browser, no phone number
+kelam export --since 7d          # call logs + derived metrics
+```
+
+The platform (API + voice worker) lives in the separate `kelam-backend` package; this package
+is just the operator CLI.

kelam-0.1.0/kelam.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: kelam
+Version: 0.1.0
+Summary: Build and run voice AI agents from the terminal — the Kelam CLI.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: kelam-core>=0.1.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typer<1,>=0.12
+
+# kelam
+
+Build and run voice AI agents from the terminal — the **Kelam CLI**.
+
+A thin, dependency-light client (httpx + typer + the shared `kelam-core` contract) for the
+Kelam voice-agent control plane. Create agents, deploy them, place real phone calls, talk to
+them in the browser, send texts, and export call data — all from `kelam`.
+
+## Install
+
+```sh
+curl -fsSL https://kelam.sh | sh        # one-command installer
+# or:
+uv tool install kelam
+pipx install kelam
+```
+
+## Configure
+
+```sh
+export KELAM_API_URL=https://<your-kelam-host>
+export KELAM_PASSWORD=<password>        # only if the server uses shared-password auth
+kelam list
+```
+
+## The loop
+
+```sh
+kelam create my-bot              # scaffold + provision a phone number
+kelam deploy <agent_id>          # assemble + cache the runtime
+kelam call   <agent_id> +1206... # place a real outbound call
+kelam web    <agent_id>          # or talk in the browser, no phone number
+kelam export --since 7d          # call logs + derived metrics
+```
+
+The platform (API + voice worker) lives in the separate `kelam-backend` package; this package
+is just the operator CLI.

kelam-0.1.0/kelam.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+kelam.egg-info/PKG-INFO
+kelam.egg-info/SOURCES.txt
+kelam.egg-info/dependency_links.txt
+kelam.egg-info/entry_points.txt
+kelam.egg-info/requires.txt
+kelam.egg-info/top_level.txt
+kelam_cli/__init__.py
+kelam_cli/main.py

kelam-0.1.0/kelam.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kelam-0.1.0/kelam.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kelam = kelam_cli.main:app

kelam-0.1.0/kelam.egg-info/requires.txt

@@ -0,0 +1,3 @@
+kelam-core>=0.1.0
+httpx<1,>=0.27
+typer<1,>=0.12

kelam-0.1.0/kelam.egg-info/top_level.txt

@@ -0,0 +1 @@
+kelam_cli

kelam-0.1.0/kelam_cli/__init__.py

@@ -0,0 +1,6 @@
+"""kelam — the command-line client for the Kelam voice-agent platform.
+
+A thin HTTP client over the control plane (depends only on kelam-core + httpx + typer), so
+`uv tool install kelam` / `pipx install kelam` stays small and fast. The platform itself
+(API + worker) lives in the separate kelam-backend package.
+"""

kelam-0.1.0/kelam_cli/main.py

@@ -0,0 +1,557 @@
+"""The `kelam` CLI — a thin HTTP client over the control plane, operated by the
+engineer (or by Claude). Core logic is plain functions taking an httpx.Client so
+the whole CLI<->API<->AWS path is integration-testable; Typer commands wrap them.
+
+Config via env: KELAM_API_URL (default http://localhost:8000), KELAM_WORKSPACE (default "default").
+The git-style loop: create -> pull -> (edit/Claude) -> verify -> push -> deploy -> call.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+import re
+import webbrowser
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from urllib.parse import urlencode
+
+import httpx
+import typer
+
+from kelam_core.metrics import CSV_FIELDS, flatten_call, summarize
+from kelam_core.translation import folder_to_records, records_to_folder
+
+
+def api_base() -> str:
+    """The control-plane base URL (KELAM_API_URL, default localhost), no trailing slash.
+    The single place the default lives — make_client and the URL builders all read it."""
+    return os.environ.get("KELAM_API_URL", "http://localhost:8000").rstrip("/")
+
+
+def make_client() -> httpx.Client:
+    ws = os.environ.get("KELAM_WORKSPACE", "default")
+    headers = {"X-Workspace": ws}
+    password = os.environ.get("KELAM_PASSWORD")
+    if password:
+        headers["X-Kelam-Password"] = password
+    return httpx.Client(base_url=api_base(), headers=headers, timeout=120.0)
+
+
+# ---- core operations (testable; take an httpx.Client) ----
+
+def cli_create(client: httpx.Client, name: str, description: str = "",
+               inbound: bool = True, outbound: bool = True) -> dict:
+    r = client.post("/agents", json={"name": name, "description": description,
+                                     "inbound": inbound, "outbound": outbound})
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_pull(client: httpx.Client, agent_id: str, dest) -> dict:
+    r = client.get(f"/agents/{agent_id}")
+    r.raise_for_status()
+    data = r.json()
+    dest = Path(dest)
+    records_to_folder(data["records"], dest)
+    (dest / ".agentmeta.json").write_text(
+        json.dumps({"agent_id": agent_id, **data["meta"]}, indent=2), encoding="utf-8"
+    )
+    return data
+
+
+def cli_push(client: httpx.Client, agent_id: str, src) -> dict:
+    r = client.post(f"/agents/{agent_id}/push", json={"records": folder_to_records(src)})
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_verify(client: httpx.Client, agent_id: str, src) -> list[str]:
+    r = client.post(f"/agents/{agent_id}/verify", json={"records": folder_to_records(src)})
+    r.raise_for_status()
+    return r.json()["issues"]
+
+
+def cli_deploy(client: httpx.Client, agent_id: str) -> dict:
+    r = client.post(f"/agents/{agent_id}/deploy")
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_list(client: httpx.Client) -> list[dict]:
+    r = client.get("/agents")
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_secret_set(client: httpx.Client, name: str, value: str) -> dict:
+    r = client.post("/secrets", json={"name": name, "value": value})
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_delete(client: httpx.Client, agent_id: str) -> dict:
+    r = client.delete(f"/agents/{agent_id}")
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_call(client: httpx.Client, agent_id: str, to_number: str,
+             prompt: str | None = None) -> dict:
+    body = {"agent_id": agent_id, "to_number": to_number}
+    if prompt:
+        body["prompt"] = prompt
+    r = client.post("/calls", json=body)
+    r.raise_for_status()
+    return r.json()
+
+
+def web_call_url(agent_id: str, prompt: str | None = None) -> str:
+    """The browser test-page URL for an agent: <KELAM_API_URL>/web-call?agent_id=...
+    The page (served by the API) dispatches the agent and connects over WebRTC on Start.
+
+    The per-call prompt and the shared password (KELAM_PASSWORD, if set) travel in the
+    URL FRAGMENT: the browser never sends it to the server, so a 32 KiB prompt can't
+    blow the HTTP request-line limit and the password never lands in access logs."""
+    ws = os.environ.get("KELAM_WORKSPACE", "default")
+    url = f"{api_base()}/web-call?{urlencode({'agent_id': agent_id, 'workspace': ws})}"
+    frag = {}
+    if prompt:
+        frag["prompt"] = prompt
+    password = os.environ.get("KELAM_PASSWORD")
+    if password:
+        frag["key"] = password
+    if frag:
+        url += "#" + urlencode(frag)
+    return url
+
+
+def resolve_instructions(prompt: str | None, file: str | None) -> str | None:
+    """Combine --prompt text and the contents of --file into the per-call instructions.
+    The file is read here (on the operator's machine); only the resulting text crosses the API."""
+    parts = []
+    if prompt:
+        parts.append(prompt)
+    if file:
+        parts.append(Path(file).read_text(encoding="utf-8"))
+    combined = "\n\n".join(p.strip() for p in parts if p and p.strip())
+    return combined or None
+
+
+def cli_get_call(client: httpx.Client, call_id: str) -> dict:
+    r = client.get(f"/calls/{call_id}")
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_list_calls(client: httpx.Client, agent_id: str,
+                   limit: int = 50, cursor: str | None = None) -> dict:
+    """One page: {"calls": [...], "next_cursor": str|null}."""
+    params: dict = {"agent_id": agent_id, "limit": limit}
+    if cursor:
+        params["cursor"] = cursor
+    r = client.get("/calls", params=params)
+    r.raise_for_status()
+    return r.json()
+
+
+def parse_since(text: str) -> str:
+    """ "30m" / "24h" / "7d" / "2w" shorthand -> ISO-8601 UTC; ISO dates pass through.
+    Raises BadParameter on anything else so the error surfaces before the HTTP call."""
+    m = re.fullmatch(r"(\d+)([mhdw])", text.strip())
+    if m:
+        n, unit = int(m.group(1)), m.group(2)
+        delta = {"m": timedelta(minutes=n), "h": timedelta(hours=n),
+                 "d": timedelta(days=n), "w": timedelta(weeks=n)}[unit]
+        return (datetime.now(timezone.utc) - delta).isoformat()
+    try:
+        datetime.fromisoformat(text)
+    except ValueError:
+        raise typer.BadParameter(
+            f"--since must be like 30m/24h/7d/2w or ISO-8601, got {text!r}")
+    return text
+
+
+def cli_export(client: httpx.Client, agent_id: str | None = None, since: str | None = None,
+               status: str | None = None, limit: int | None = None,
+               page_size: int = 200) -> list[dict]:
+    """Walk the paginated export until exhausted (or `limit` calls collected). Each
+    page is one bounded server-side query; the loop key is next_cursor, never item
+    count — filtered pages can run short and still have more behind them."""
+    calls: list[dict] = []
+    cursor: str | None = None
+    while True:
+        params = {k: v for k, v in {
+            "agent_id": agent_id, "since": since, "status": status,
+            "limit": min(page_size, limit - len(calls)) if limit else page_size,
+            "cursor": cursor,
+        }.items() if v is not None}
+        r = client.get("/calls/export", params=params)
+        r.raise_for_status()
+        body = r.json()
+        calls.extend(body["calls"])
+        cursor = body.get("next_cursor")
+        if not cursor or (limit and len(calls) >= limit):
+            return calls[:limit] if limit else calls
+
+
+def render_export(calls: list[dict], fmt: str) -> str:
+    """Enriched calls -> jsonl (one call per line), json (array), or csv (flat metric
+    rows, no transcript text). jsonl/csv are what the kelam-viz skill consumes."""
+    if fmt == "jsonl":
+        return "\n".join(json.dumps(c) for c in calls) + ("\n" if calls else "")
+    if fmt == "json":
+        return json.dumps(calls, indent=2) + "\n"
+    if fmt == "csv":
+        buf = io.StringIO()
+        writer = csv.DictWriter(buf, fieldnames=CSV_FIELDS)
+        writer.writeheader()
+        for call in calls:
+            writer.writerow(flatten_call(call))
+        return buf.getvalue()
+    raise typer.BadParameter(f"--format must be jsonl, json, or csv, got {fmt!r}")
+
+
+def cli_text(client: httpx.Client, agent_id: str, to_number: str, body: str = "",
+             media_urls: list[str] | None = None, channel: str = "sms") -> dict:
+    r = client.post("/messages", json={"agent_id": agent_id, "to_number": to_number,
+                                       "body": body, "media_urls": media_urls or [],
+                                       "channel": channel})
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_list_texts(client: httpx.Client, agent_id: str | None = None, peer: str | None = None,
+                   since: str | None = None, limit: int = 50,
+                   cursor: str | None = None) -> dict:
+    """One page: {"messages": [...], "next_cursor": str|null}."""
+    params = {k: v for k, v in {"agent_id": agent_id, "peer": peer, "since": since,
+                                "limit": limit, "cursor": cursor}.items() if v is not None}
+    r = client.get("/messages", params=params)
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_context(client: httpx.Client, agent_id: str, peer: str) -> dict:
+    """The compose-a-reply bundle: message thread + call transcripts with the peer."""
+    r = client.get("/messages/context", params={"agent_id": agent_id, "peer": peer})
+    r.raise_for_status()
+    return r.json()
+
+
+def cli_peers(client: httpx.Client, agent_id: str, limit: int = 20) -> dict:
+    """Recently active numbers across calls + texts: {"peers": [...], "truncated": bool}."""
+    r = client.get(f"/agents/{agent_id}/peers", params={"limit": limit})
+    r.raise_for_status()
+    return r.json()
+
+
+def stream_call_events(client: httpx.Client, call_id: str):
+    """Yield the call's live events from the SSE endpoint until the stream closes.
+    Long-lived read: no read timeout (the server sends keepalives and closes on `ended`)."""
+    timeout = httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)
+    with client.stream("GET", f"/calls/{call_id}/stream", timeout=timeout) as r:
+        r.raise_for_status()
+        for line in r.iter_lines():
+            if line.startswith("data: "):
+                yield json.loads(line[len("data: "):])
+
+
+def follow_call(client: httpx.Client, call_id: str, echo=print) -> dict | None:
+    """Print events as JSONL until the call ends; return the final CallLog (None on timeout)."""
+    for event in stream_call_events(client, call_id):
+        echo(json.dumps(event))
+        if event.get("type") == "ended":
+            return event.get("call")
+        if event.get("type") == "timeout":
+            return None
+    return None
+
+
+# ---- Typer commands ----
+
+app = typer.Typer(help="Kelam — build and run voice AI agents from the terminal.")
+
+
+@app.command()
+def create(
+    name: str,
+    description: str = "",
+    no_number: bool = typer.Option(
+        False, "--no-number",
+        help="web-only agent: skip provisioning a phone number (talk to it with `kelam web`)",
+    ),
+):
+    """Create an agent and pull it into ./<name>/.
+
+    By default auto-provisions a phone number. With --no-number the agent has no inbound or
+    outbound telephony and costs nothing — reach it over the browser with `kelam web <id>`."""
+    with make_client() as c:
+        d = cli_create(c, name, description,
+                       inbound=not no_number, outbound=not no_number)
+        cli_pull(c, d["agent_id"], Path(name))
+    typer.echo(json.dumps(d))
+
+
+@app.command()
+def pull(agent_id: str, dest: str = ""):
+    """Pull an agent's files into a local folder."""
+    with make_client() as c:
+        cli_pull(c, agent_id, Path(dest or agent_id))
+    typer.echo(json.dumps({"pulled": agent_id, "dest": dest or agent_id}))
+
+
+@app.command()
+def verify(agent_id: str, src: str = "."):
+    """Lint a local agent folder (config, tools, secret references)."""
+    with make_client() as c:
+        issues = cli_verify(c, agent_id, src)
+    typer.echo(json.dumps({"issues": issues}))
+    if issues:
+        raise typer.Exit(1)
+
+
+@app.command()
+def push(agent_id: str, src: str = "."):
+    """Push a local agent folder (creates a new version)."""
+    with make_client() as c:
+        typer.echo(json.dumps(cli_push(c, agent_id, src)))
+
+
+@app.command()
+def deploy(agent_id: str):
+    """Deploy: assemble + cache the runtime, ready for calls."""
+    with make_client() as c:
+        typer.echo(json.dumps(cli_deploy(c, agent_id)))
+
+
+@app.command("list")
+def list_cmd():
+    """List agents in the workspace."""
+    with make_client() as c:
+        typer.echo(json.dumps(cli_list(c)))
+
+
+@app.command("secret-set")
+def secret_set(
+    name: str,
+    env_var: str = typer.Option(
+        None, "--env-var", help="read the value from this env var instead of a hidden prompt"
+    ),
+):
+    """Set a workspace secret (stored encrypted in SSM). The value is read from --env-var or a
+    hidden prompt — never passed on the command line (keeps it out of shell history/transcripts)."""
+    if env_var:
+        if env_var not in os.environ:
+            raise typer.BadParameter(f"env var {env_var!r} is not set")
+        value = os.environ[env_var]
+    else:
+        value = typer.prompt("Secret value", hide_input=True)
+    with make_client() as c:
+        cli_secret_set(c, name, value)
+    typer.echo(json.dumps({"ok": True}))
+
+
+@app.command()
+def call(
+    agent_id: str,
+    to_number: str,
+    prompt: str = typer.Option(
+        None, "--prompt", "-p", help="per-call instructions, seeded as the agent's first message"
+    ),
+    file: str = typer.Option(
+        None, "--file", "-f", help="read per-call instructions from this file (combined with --prompt)"
+    ),
+    wait: bool = typer.Option(
+        False, "--wait", "-w", help="stream the call live and exit with the final transcript"
+    ),
+):
+    """Place an outbound call from the agent to a phone number (fire-and-forget).
+
+    Optional --prompt/--file tailor THIS call without redeploying — e.g.
+    `kelam call <id> +1206... -p "extract their email, budget, and timeline"`.
+    With --wait, stream the call's events live (JSONL) and exit when it ends,
+    printing the final CallLog — the place->follow->transcript loop in one command."""
+    if file and not Path(file).is_file():
+        raise typer.BadParameter(f"file not found: {file}")
+    instructions = resolve_instructions(prompt, file)
+    with make_client() as c:
+        placed = cli_call(c, agent_id, to_number, prompt=instructions)
+        typer.echo(json.dumps(placed))
+        if not wait:
+            return
+        final = follow_call(c, placed["call_id"], echo=typer.echo)
+        if final is None:
+            raise typer.Exit(1)  # stream timed out without a terminal status
+        typer.echo(json.dumps(final))
+        if final.get("status") != "completed":
+            raise typer.Exit(1)
+
+
+@app.command()
+def web(
+    agent_id: str,
+    prompt: str = typer.Option(
+        None, "--prompt", "-p", help="per-call instructions, seeded as the agent's first message"
+    ),
+    file: str = typer.Option(
+        None, "--file", "-f", help="read per-call instructions from this file (combined with --prompt)"
+    ),
+    no_open: bool = typer.Option(
+        False, "--no-open", help="just print the URL; don't open a browser"
+    ),
+):
+    """Talk to a deployed agent in your browser over WebRTC — no phone number required.
+
+    Opens the test page; click Start to dispatch the agent, connect your mic, and watch
+    the live transcript. The call is logged like any other (`kelam transcript <call_id>`).
+    Optional --prompt/--file tailor THIS call without redeploying. The page is served by
+    the API, so point KELAM_API_URL at the box you want (defaults to localhost:8000)."""
+    if file and not Path(file).is_file():
+        raise typer.BadParameter(f"file not found: {file}")
+    url = web_call_url(agent_id, resolve_instructions(prompt, file))
+    typer.echo(json.dumps({"agent_id": agent_id, "url": url}))
+    if not no_open:
+        webbrowser.open(url)
+
+
+@app.command()
+def transcript(
+    target: str = typer.Argument(..., metavar="CALL_ID|AGENT_ID",
+                                 help="a call_id (one call) — or an agent_id, with a phone number"),
+    peer: str = typer.Argument(
+        None, metavar="[PEER]",
+        help="a peer from `kelam peers` (usually a phone number): return the full "
+             "voice+text history with it instead"),
+):
+    """Fetch a transcript.
+
+    One arg (a call_id) -> that call's log: status + transcript + recording_url,
+    plus a short-lived presigned recording_playback_url (click-to-listen, no manual
+    aws s3 presign). Two args (an agent_id and a phone number) -> the whole
+    conversation with that number: the text thread plus call logs/transcripts, as
+    {messages, calls}. Read it, then reply with `kelam text`."""
+    with make_client() as c:
+        if peer is None:
+            typer.echo(json.dumps(cli_get_call(c, target)))
+            return
+        # Full-length numbers are normalized to E.164 (a bare 12065550123 gains its +);
+        # everything else `kelam peers` can yield — short codes, alphanumeric sender ids,
+        # anonymous caller ids — passes through exactly as stored, never rejected.
+        peer = peer.strip()
+        if re.fullmatch(r"\+?[1-9]\d{7,14}", peer):
+            peer = "+" + peer.lstrip("+")
+        typer.echo(json.dumps(cli_context(c, target, peer)))
+
+
+@app.command()
+def calls(
+    agent_id: str,
+    limit: int = typer.Option(50, "--limit", "-n", help="page size"),
+    cursor: str = typer.Option(None, "--cursor", help="resume from a previous page's next_cursor"),
+):
+    """List an agent's recent calls (newest first), one page at a time.
+    Output is {"calls": [...], "next_cursor": ...}; pass --cursor to continue."""
+    with make_client() as c:
+        typer.echo(json.dumps(cli_list_calls(c, agent_id, limit=limit, cursor=cursor)))
+
+
+@app.command()
+def export(
+    agent_id: str = typer.Option(None, "--agent", "-a", help="only this agent's calls (default: whole workspace)"),
+    since: str = typer.Option(None, "--since", help='only calls started after this: "30m", "24h", "7d", "2w", or ISO-8601'),
+    status: str = typer.Option(None, "--status", help="filter by status: completed | failed | busy | no_answer | in_progress"),
+    limit: int = typer.Option(None, "--limit", "-n", help="newest N calls after filtering"),
+    fmt: str = typer.Option("jsonl", "--format", help="jsonl (default) | json | csv (flat metrics, no transcript)"),
+    out: str = typer.Option(None, "--out", "-o", help="write to this file instead of stdout"),
+):
+    """Export call logs — transcripts plus derived metrics (turns, words, talk ratio,
+    durations) — for analysis or visualization. Newest first."""
+    with make_client() as c:
+        calls = cli_export(c, agent_id=agent_id, since=parse_since(since) if since else None,
+                           status=status, limit=limit)
+    rendered = render_export(calls, fmt)
+    if out:
+        Path(out).write_text(rendered, encoding="utf-8")
+        typer.echo(json.dumps({"exported": len(calls), "format": fmt, "out": out}))
+    else:
+        typer.echo(rendered, nl=False)
+
+
+@app.command()
+def stats(
+    agent_id: str = typer.Option(None, "--agent", "-a", help="only this agent's calls (default: whole workspace)"),
+    since: str = typer.Option(None, "--since", help='only calls started after this: "30m", "24h", "7d", "2w", or ISO-8601'),
+):
+    """Aggregate call stats: counts by status/direction/agent, duration percentiles, turn totals."""
+    with make_client() as c:
+        calls = cli_export(c, agent_id=agent_id, since=parse_since(since) if since else None)
+    typer.echo(json.dumps(summarize(calls), indent=2))
+
+
+@app.command()
+def text(
+    agent_id: str,
+    to_number: str,
+    body: str = typer.Argument("", help="the message text (optional when --media is given)"),
+    media: list[str] = typer.Option(
+        None, "--media", "-m", help="media URL to attach (repeatable) — images etc."
+    ),
+    channel: str = typer.Option(
+        "sms", "--channel", "-c", help="delivery channel: sms (default) or whatsapp"
+    ),
+):
+    """Send a message (SMS, MMS with --media, or --channel whatsapp) from the agent's number.
+
+    e.g. `kelam text <id> +12065550123 "running 5 minutes late"`. The message is
+    stored on the (agent, number) thread; replies land there too (the number's SMS
+    webhook is wired to this server automatically at provision when KELAM_PUBLIC_URL
+    is set)."""
+    if not body and not media:
+        raise typer.BadParameter("provide a message body and/or --media")
+    with make_client() as c:
+        typer.echo(json.dumps(cli_text(c, agent_id, to_number, body=body,
+                                       media_urls=list(media) if media else None,
+                                       channel=channel)))
+
+
+@app.command()
+def texts(
+    agent_id: str,
+    peer: str = typer.Option(None, "--peer", help="only the thread with this number"),
+    since: str = typer.Option(None, "--since", help='only messages after this: "30m", "24h", "7d", "2w", or ISO-8601'),
+    limit: int = typer.Option(50, "--limit", "-n", help="page size"),
+    cursor: str = typer.Option(None, "--cursor", help="resume from a previous page's next_cursor"),
+):
+    """List an agent's messages (newest first), one page at a time.
+    Output is {"messages": [...], "next_cursor": ...}; pass --cursor to continue."""
+    with make_client() as c:
+        typer.echo(json.dumps(cli_list_texts(
+            c, agent_id, peer=peer, since=parse_since(since) if since else None,
+            limit=limit, cursor=cursor)))
+
+
+@app.command()
+def peers(
+    agent_id: str,
+    limit: int = typer.Option(20, "--limit", "-n", help="how many distinct numbers to return"),
+):
+    """Recently active numbers across this agent's calls AND texts, newest contact first.
+
+    The starting point for following up: pick a number, then `kelam transcript <id> <number>`
+    for the full voice+text history. Each entry has last_contact, last_direction, and the
+    channels (call/text) it used. Output: {"peers": [...], "truncated": bool}."""
+    with make_client() as c:
+        typer.echo(json.dumps(cli_peers(c, agent_id, limit=limit)))
+
+
+@app.command()
+def delete(agent_id: str):
+    """Delete an agent."""
+    with make_client() as c:
+        typer.echo(json.dumps(cli_delete(c, agent_id)))
+
+
+if __name__ == "__main__":
+    app()

kelam-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "kelam"
+version = "0.1.0"
+description = "Build and run voice AI agents from the terminal — the Kelam CLI."
+readme = "README.md"
+requires-python = ">=3.11"
+# Capped at the next major per the repo dep policy (issue #40); 0.x libs capped at <1.
+dependencies = [
+  "kelam-core>=0.1.0",
+  "httpx>=0.27,<1",
+  "typer>=0.12,<1",
+]
+
+[project.scripts]
+kelam = "kelam_cli.main:app"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["kelam_cli*"]

kelam-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+