hum-cli 0.0.1__tar.gz

hum_cli-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: publish
+# Trusted publishing to PyPI (no token): tag vX.Y.Z → build → publish.
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: pypa/gh-action-pypi-publish@release/v1

hum_cli-0.0.1/.github/workflows/test.yml

@@ -0,0 +1,16 @@
+name: test
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  test:
+    strategy:
+      matrix: { os: [ubuntu-latest, macos-latest, windows-latest] }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.12
+      - run: uv venv --python 3.12 && uv pip install -e ".[dev,server,harbor]"
+      - run: uv run --no-project pytest -q
+        shell: bash

hum_cli-0.0.1/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.5
+Name: hum-cli
+Version: 0.0.1
+Summary: An agent harness built as an RL environment that humans can drive: session trees, interchangeable human/policy drivers, counterfactual shadow, earned autonomy, verifier in the loop.
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: litellm>=1.70
+Requires-Dist: mcp>=1.2
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pydantic>=2
+Requires-Dist: rich>=13
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: google-auth>=2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: python-multipart; extra == 'dev'
+Provides-Extra: harbor
+Requires-Dist: harbor>=0.21; extra == 'harbor'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: google-auth>=2; extra == 'server'
+Requires-Dist: python-multipart; extra == 'server'
+Requires-Dist: uvicorn[standard]; extra == 'server'

hum_cli-0.0.1/README.md

@@ -0,0 +1,50 @@
+# Hum — हम
+
+*We.* Human and model, one harness.
+
+Hum is an agent harness built as an RL environment that humans can drive. The same loop serves a person at a keyboard, a policy in a rollout, or a shadow continuing from a fork — and the loop remembers who did what.
+
+What makes it different from a coding agent:
+
+- **Interchangeable drivers.** A human turn is a first-class move in the session tree, not a prompt.
+- **Counterfactual shadow.** When a human overrides a proposal, the pre-intervention state is forked, the policy finishes in shadow, and the grader scores both futures. Every override becomes a preference pair whose preference is a verifier, not a rater.
+- **Earned autonomy.** How much the policy may do unsupervised on a class of tasks is a number the world assigns from graded outcomes, updated online — `observe → propose → review → act`.
+- **Verifier in the loop.** The grader is both a tool the agent calls and the reward the trainer reads.
+- **Trajectory-native.** Every session is a valid ATIF trajectory with authorship, interventions, shadow branches, verdicts and token custody — a training sample as it is written.
+- **Model-agnostic, sovereign.** Any OpenAI-compatible endpoint: frontier, open weights, or your own policy served from the trainer. Runs on Modal or on your iron.
+
+## Run it
+
+```bash
+uv tool install git+https://github.com/metaphi-labs/hum-cli
+hum login                 # browser opens → sign in with Google → back to the terminal
+cd your-repo
+hum                       # say what we're doing; it works, streams, shows its tool calls
+hum "make the nightly job idempotent"
+hum resume                # pick up the last session
+```
+
+While it works, just type: a message steers it, `!cmd` runs a command yourself, Ctrl-C stops the current turn. Edit files in your editor whenever you like. `/help` in a session lists the rest (`/model`, `/tools`, `/cost`).
+
+Signing in gives you a key on Metaphi's model proxy — GLM-5.3 by default. Bringing your own model is allowed (`hum model anthropic/claude-fable-5`, `hum key anthropic <key>`); those sessions are marked as running on your model.
+
+Other commands: `hum run "task"` (unattended, then exit — the mode rollouts use), `hum sessions`, `hum show <id>`, `hum sync`, `hum whoami`, `hum logout`.
+
+## Deployment (Metaphi)
+
+One Modal app, `server/modal_app.py`: sign-in (Firebase Auth in the browser, ID token verified server-side; allowlist), the **model proxy** every client talks to (OpenAI-compatible `/v1/chat/completions`; the person's Hum token is their key; every call metered per person with a monthly budget), and session intake. State is SQLite + session files on the volume `hum-data`. Routes are named — `glm-5.3` on zero-data-retention providers, `policy` = our weights from the trainer, `fable` — so moving the fleet onto our model is one route change, no client update.
+
+`~/.hum/config.toml` on a machine can override the model, mount MCP servers (`control`, `run-unit`) as native tools, and turn on backend behaviour — grader, autonomy-gated sessions, fork-and-grade on intervention. Defaults are "be a great agent".
+
+## As a Harbor agent
+
+`harbor run -a hum.adapters.harbor:HumAgent -m openrouter/z-ai/glm-5.3 ...` — Terminal-Bench, MainframeBench through simhub `task_run --harness hum`, and Slime rollouts run the same class, with no human driver.
+
+## Layout
+
+```
+hum/runtime/   session tree · drivers · loop (shadow) · autonomy · tools (+MCP) · grader · llm · observe · trajectory (ATIF)
+hum/adapters/  harbor
+hum/cli.py     terminal client
+deploy/        litellm proxy config
+```

hum_cli-0.0.1/hum/__init__.py

@@ -0,0 +1,4 @@
+"""Hum — an agent harness built as an RL environment that humans can drive.
+
+हम (Hindi): we, us. Human and model, one harness."""
+__version__ = "0.0.1"

hum_cli-0.0.1/hum/adapters/harbor.py

@@ -0,0 +1,128 @@
+"""Harbor adapter: the runtime as a Harbor ``BaseAgent``.
+
+This is how the harness enters every arena that already speaks Harbor —
+Terminal-Bench, MainframeBench through simhub's task_run, and Slime rollouts
+(the policy is served at an OpenAI-compatible endpoint; Harbor passes it as
+``-m openai/policy`` with ``OPENAI_BASE_URL``). Same class, no human driver.
+
+Register with ``harbor run --agent-import-path hum.adapters.harbor:HumAgent``.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import shlex
+import uuid
+from pathlib import Path
+from typing import Any
+
+from harbor.agents.base import BaseAgent
+from harbor.agents.model_connection import ModelConnectionSpec
+from harbor.environments.base import BaseEnvironment
+from harbor.models.agent.context import AgentContext
+from harbor.models.trajectories import Trajectory
+
+from hum import __version__
+from hum.runtime import LiteLLMClient, PolicyDriver, RunConfig, Runner, Session, ToolRegistry, builtin_tools
+from hum.runtime.executor import ExecResult, decode
+from hum.runtime.prompt import system_prompt
+from hum.runtime.tools import MCPToolset
+from hum.runtime.trajectory import to_atif
+
+AGENT_NAME = "hum"
+
+
+class HarborExecutor:
+    """Executor over a Harbor environment. Files move as base64 through exec so
+    no host-side temp paths are involved; snapshots are tarballs in the sandbox."""
+
+    def __init__(self, env: BaseEnvironment, cwd: str = "/app"):
+        self.env, self.cwd = env, cwd
+
+    async def exec(self, command: str, cwd: str | None = None, timeout_sec: int | None = None) -> ExecResult:
+        r = await self.env.exec(command, cwd=cwd or self.cwd, timeout_sec=timeout_sec)
+        return ExecResult(stdout=r.stdout or "", stderr=r.stderr or "", returncode=r.return_code if r.return_code is not None else 0)
+
+    async def read(self, path: str) -> bytes:
+        r = await self.env.exec(f"base64 -w0 {shlex.quote(path)}", cwd=self.cwd, timeout_sec=60)
+        if r.return_code not in (0, None):
+            raise FileNotFoundError(r.stderr or path)
+        return base64.b64decode(r.stdout or "")
+
+    async def write(self, path: str, data: bytes) -> None:
+        b64 = base64.b64encode(data).decode()
+        r = await self.env.exec(f"mkdir -p $(dirname {shlex.quote(path)}) && echo {b64} | base64 -d > {shlex.quote(path)}", cwd=self.cwd, timeout_sec=60)
+        if r.return_code not in (0, None):
+            raise OSError(r.stderr or f"write failed: {path}")
+
+    async def snapshot(self) -> str:
+        sid = uuid.uuid4().hex[:12]
+        await self.env.exec(f"mkdir -p /tmp/harness_snap && tar czf /tmp/harness_snap/{sid}.tgz -C {shlex.quote(self.cwd)} .", timeout_sec=600)
+        return sid
+
+    async def fork(self, snapshot_id: str):
+        # One sandbox per trial: shadow forks need a second sandbox, which Harbor
+        # does not hand out. Unattended runs never fork; attended runs use the
+        # hosted-session executor instead.
+        raise NotImplementedError("HarborExecutor cannot fork; run attended sessions on a forkable executor")
+
+    async def close(self) -> None:
+        return None
+
+
+class HumAgent(BaseAgent):
+    SUPPORTS_ATIF = True
+    MODEL_CONNECTION = ModelConnectionSpec()  # provider inferred from the model name (openai/..., anthropic/..., openrouter/...)
+
+    def __init__(self, logs_dir: Path, model_name: str | None = None, *args: Any, temperature: float | None = None,
+                 reasoning_effort: str | None = None, max_turns: int = 200, max_wall_s: float = 3600.0,
+                 observation_max_bytes: int = 16_000, **kwargs: Any):
+        super().__init__(logs_dir, model_name, *args, **kwargs)
+        self._temperature = temperature
+        self._reasoning_effort = reasoning_effort
+        self._cfg = RunConfig(max_turns=int(max_turns), max_wall_s=float(max_wall_s), shadow=False)
+        self._obs_bytes = int(observation_max_bytes)
+        self._toolsets: list[MCPToolset] = []
+
+    @staticmethod
+    def name() -> str:
+        return AGENT_NAME
+
+    def version(self) -> str | None:
+        return __version__
+
+    async def setup(self, environment: BaseEnvironment) -> None:
+        return None  # nothing is installed in the sandbox; the loop runs host-side
+
+    async def run(self, instruction: str, environment: BaseEnvironment, context: AgentContext) -> None:
+        executor = HarborExecutor(environment)
+        tools = ToolRegistry(observation_max_bytes=self._obs_bytes).extend(builtin_tools())
+        notes = []
+        for s in self.mcp_servers or []:
+            ts = MCPToolset(s.name, url=s.url, command=s.command, args=s.args) if s.transport == "stdio" or s.url else None
+            if ts is None:
+                continue
+            mounted = await ts.connect()
+            tools.extend(mounted)
+            self._toolsets.append(ts)
+            notes.append(f"- {s.name}: " + ", ".join(t.name for t in mounted))
+        conn = self.model_connection
+        llm = LiteLLMClient(self.model_name or "", api_base=conn.base_url, api_key=conn.api_key,
+                            temperature=self._temperature, reasoning_effort=self._reasoning_effort)
+        prompt = system_prompt(tools_note="\n".join(notes))
+        session = Session({"instruction": instruction}, session_id=self.session_id, path=self.logs_dir / "session.jsonl")
+        runner = Runner(session, executor, tools, PolicyDriver(llm), config=self._cfg, system_prompt=prompt)
+        try:
+            result = await runner.run()
+        finally:
+            for ts in self._toolsets:
+                await ts.close()
+            traj = to_atif(session, agent_name=AGENT_NAME, agent_version=__version__ or "0", model_name=self.model_name,
+                           system_prompt=prompt, tool_definitions=tools.to_openai())
+            Trajectory.model_validate(traj)  # stay a valid ATIF document
+            (self.logs_dir / "trajectory.json").write_text(json.dumps(traj, ensure_ascii=False, indent=1))
+        context.n_input_tokens = result.usage.input_tokens
+        context.n_output_tokens = result.usage.output_tokens
+        context.n_cache_tokens = result.usage.cache_tokens
+        context.cost_usd = result.usage.cost_usd
+        context.metadata = {"harness": AGENT_NAME, "turns": result.turns, "stop_reason": result.stop_reason}

hum_cli-0.0.1/hum/auth.py

@@ -0,0 +1,112 @@
+"""Sign-in from the terminal: ``hum login`` opens the browser (device-code flow,
+RFC 8628), the person signs in with Google, the terminal receives a Hum token
+plus their key on our model proxy. Credentials live in ~/.hum/credentials.json
+(mode 0600). BYO provider keys live next to them.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import webbrowser
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from hum import __version__
+from hum.runtime.store import home
+
+DEFAULT_AUTH_URL = os.environ.get("HUM_AUTH_URL", "https://metaphi-ai--hum-web.modal.run")
+
+
+@dataclass
+class Credentials:
+    auth_url: str = DEFAULT_AUTH_URL
+    access_token: str | None = None
+    email: str | None = None
+    name: str | None = None
+    api_base: str | None = None      # our proxy
+    api_key: str | None = None       # this person's key on it
+    default_model: str | None = None
+    byo: dict[str, str] = field(default_factory=dict)  # provider -> key, user-supplied
+    model: str | None = None         # user's chosen model, if any
+
+    @property
+    def logged_in(self) -> bool:
+        return bool(self.access_token and self.email)
+
+
+def path() -> Path:
+    return home() / "credentials.json"
+
+
+def load() -> Credentials:
+    p = path()
+    if not p.exists():
+        return Credentials()
+    try:
+        d = json.loads(p.read_text())
+        return Credentials(**{k: v for k, v in d.items() if k in Credentials.__dataclass_fields__})
+    except Exception:  # noqa: BLE001
+        return Credentials()
+
+
+def save(c: Credentials) -> None:
+    p = path()
+    p.write_text(json.dumps(asdict(c), indent=1))
+    os.chmod(p, 0o600)
+
+
+PROVIDER_ENV = {"openrouter": "OPENROUTER_API_KEY", "anthropic": "ANTHROPIC_API_KEY", "openai": "OPENAI_API_KEY", "gemini": "GEMINI_API_KEY"}
+
+
+def provider_of(model: str) -> str:
+    return model.split("/", 1)[0] if "/" in model else "openai"
+
+
+def login(auth_url: str | None = None, open_browser: bool = True, poll_timeout_s: float = 600.0, client: Any = None) -> Credentials:
+    """Device-code flow. ``client`` is an httpx.Client (tests inject one)."""
+    import httpx
+
+    base = (auth_url or load().auth_url or DEFAULT_AUTH_URL).rstrip("/")
+    http = client or httpx.Client(timeout=20.0)
+    r = http.post(f"{base}/device/code", json={"client": "hum-cli", "version": __version__})
+    r.raise_for_status()
+    d = r.json()
+    uri = d.get("verification_uri_complete") or d["verification_uri"]
+    print(f"\nOpen {uri}\nand confirm the code  {d['user_code']}\n")
+    if open_browser:
+        try:
+            webbrowser.open(uri)
+        except Exception:  # noqa: BLE001
+            pass
+    interval = float(d.get("interval", 3))
+    deadline = time.monotonic() + min(poll_timeout_s, float(d.get("expires_in", 600)))
+    while time.monotonic() < deadline:
+        time.sleep(interval)
+        t = http.post(f"{base}/device/token", json={"device_code": d["device_code"]})
+        body = t.json()
+        if t.status_code == 200 and body.get("access_token"):
+            c = load()
+            c.auth_url = base
+            c.access_token = body["access_token"]
+            c.email = body["user"]["email"]
+            c.name = body["user"].get("name")
+            m = body.get("model") or {}
+            c.api_base, c.api_key, c.default_model = m.get("api_base"), m.get("api_key"), m.get("default_model")
+            save(c)
+            return c
+        err = body.get("error")
+        if err == "slow_down":
+            interval += 2
+        elif err in ("authorization_pending", None):
+            continue
+        else:
+            raise RuntimeError(f"login failed: {err}")
+    raise TimeoutError("login timed out; run `hum login` again")
+
+
+def logout() -> None:
+    c = load()
+    c.access_token = c.email = c.name = c.api_base = c.api_key = c.default_model = None
+    save(c)