corethink 1.0.0__py3-none-any.whl

corethink/__init__.py

@@ -0,0 +1,17 @@
+"""CoreThink: the Workbench from your terminal (`corethink --help`), and the older evaluation SDK.
+
+The SDK names (Environment, TaskInstance, Template) are loaded only when asked for: they need the evaluation packages,
+which a plain `pip install corethink` does not bring.
+"""
+
+from corethink._version import __version__
+
+__all__ = ["Environment", "TaskInstance", "Template", "__version__"]
+
+
+def __getattr__(name: str):
+    if name in {"Environment", "TaskInstance", "Template"}:
+        from corethink import sdk
+
+        return getattr(sdk, name)
+    raise AttributeError(f"module 'corethink' has no attribute {name!r}")

corethink/__main__.py

@@ -0,0 +1,3 @@
+from corethink.main import main
+
+raise SystemExit(main())

corethink/_version.py

@@ -0,0 +1,3 @@
+"""The version of the `corethink` package (read by the build and by `corethink --version`)."""
+
+__version__ = "1.0.0"

corethink/account.py

@@ -0,0 +1,470 @@
+"""`corethink login` — a CoreThink account, not a model provider's key.
+
+Before this, `login` stored whichever provider key an evaluation would send to a
+model endpoint, and `CORETHINK_API_KEY` named that. Nothing authenticated a
+*CoreThink* account at all: hosted work needed a Google login and a shared
+operator token that no customer can be given. This module is the account half,
+and it keeps the two apart on purpose — the failure it is written to prevent is a
+provider key being sent to CoreThink, or a CoreThink key to a provider.
+
+Two rules make that concrete:
+
+* **A CoreThink credential is recognised by its prefix.** `ctu_` for a browser
+  session, `ctk_` for an API key. A value that is neither is refused before any
+  request is made, with a message naming where a provider key actually goes. So
+  an exported `CORETHINK_API_KEY=sk-...` from the old arrangement produces an
+  explanation rather than a leak.
+* **The session lives in its own file**, not in `config.json`, because
+  `config list` prints that file and a session token must never be printed.
+
+The flow is RFC 8628 device authorization. A browser is the only place the Google
+sign-in can happen, the CLI never sees the Google credential, and the code the
+CLI holds is short-lived, single-use, and worth nothing until somebody signed in
+approves it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+__all__ = ["AccountError", "CoreThinkClient", "credentials_path", "load_credential", "register"]
+
+#: Where the public API lives unless a deployment or a test says otherwise.
+DEFAULT_API_URL = "https://corethink-api-qtb56vjxea-uc.a.run.app"
+
+#: What a CoreThink credential looks like. See the module docstring.
+CREDENTIAL_PREFIXES = ("ctu_", "ctk_")
+
+#: How long `login` waits for the browser before giving up on its own.
+LOGIN_TIMEOUT_SECONDS = 600
+
+
+class AccountError(RuntimeError):
+    """Something the person at the terminal can act on."""
+
+
+# -- where the credential lives ------------------------------------------
+
+
+def credentials_path() -> Path:
+    """The session file, beside the config and overridable the same way.
+
+    `CORETHINK_CREDENTIALS` exists so a test never touches a developer's real
+    session, and so two projects on one machine can hold different accounts.
+    """
+
+    override = os.environ.get("CORETHINK_CREDENTIALS")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CONFIG_HOME") or "~/.config"
+    return Path(base).expanduser() / "corethink" / "credentials.json"
+
+
+def save_credential(payload: dict[str, Any]) -> Path:
+    """Write the session with the permissions a credential deserves.
+
+    Mode before content, so there is no window in which the token exists in a
+    world-readable file.
+    """
+
+    target = credentials_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(target.parent, 0o700)
+    target.touch(mode=0o600, exist_ok=True)
+    os.chmod(target, 0o600)
+    target.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return target
+
+
+def clear_credential() -> bool:
+    target = credentials_path()
+    if not target.is_file():
+        return False
+    target.unlink()
+    return True
+
+
+def load_credential() -> dict[str, Any] | None:
+    target = credentials_path()
+    if not target.is_file():
+        return None
+    try:
+        stored = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return stored if isinstance(stored, dict) and stored.get("access_token") else None
+
+
+def resolve_api_url(override: str | None = None) -> str:
+    from corethink.config import ConfigError, resolve
+
+    if override:
+        return override.rstrip("/")
+    try:
+        stored = resolve("api_url")
+    except ConfigError:  # pragma: no cover - a broken config must not block login
+        stored = None
+    saved = (load_credential() or {}).get("api_url")
+    return str(stored or saved or DEFAULT_API_URL).rstrip("/")
+
+
+def resolve_token(override: str | None = None) -> str | None:
+    """The CoreThink credential in force: flag, environment, then the session file.
+
+    The prefix check is the migration guard. `CORETHINK_API_KEY` used to name a
+    *model provider's* key; a value that is not a CoreThink credential is refused
+    here, before any request, rather than sent to an endpoint it was never meant
+    for.
+    """
+
+    candidate = (override or os.environ.get("CORETHINK_API_KEY", "")).strip()
+    if candidate:
+        if not candidate.startswith(CREDENTIAL_PREFIXES):
+            raise AccountError(
+                "CORETHINK_API_KEY does not hold a CoreThink credential (they start with "
+                "ctk_ or ctu_). A model provider's key belongs in "
+                "`corethink config set provider_api_key`, or in the variable named by "
+                "--model-api-key-env; it is never sent to CoreThink."
+            )
+        return candidate
+    stored = load_credential()
+    return str(stored["access_token"]) if stored else None
+
+
+# -- talking to the API ---------------------------------------------------
+
+
+def _ssl_context() -> ssl.SSLContext:
+    """Verify TLS properly even where the interpreter has no CA bundle.
+
+    Shared with `jobs_cli` rather than re-derived: a framework Python on macOS
+    ships without a CA bundle, and the fallback is the difference between working
+    and CERTIFICATE_VERIFY_FAILED on every HTTPS call.
+    """
+
+    from corethink.jobs_cli import _ssl_context as shared
+
+    return shared()
+
+
+def request(
+    api_url: str,
+    method: str,
+    path: str,
+    *,
+    payload: dict[str, Any] | None = None,
+    token: str | None = None,
+    timeout: float = 60.0,
+) -> tuple[int, Any]:
+    """One API call. Returns (status, decoded body) rather than raising on 4xx.
+
+    The device-flow poll needs the body of a 400 — `authorization_pending` is a
+    normal state, not an error — so the status comes back as data and each caller
+    decides what it means.
+    """
+
+    headers = {"accept": "application/json"}
+    if token:
+        headers["authorization"] = f"Bearer {token}"
+    data = None
+    if payload is not None:
+        data = json.dumps(payload).encode("utf-8")
+        headers["content-type"] = "application/json"
+    call = urllib.request.Request(  # noqa: S310 - the base URL comes from explicit config
+        f"{api_url}{path}", data=data, headers=headers, method=method
+    )
+    try:
+        with urllib.request.urlopen(call, timeout=timeout, context=_ssl_context()) as response:  # noqa: S310
+            body = response.read().decode("utf-8")
+            return response.status, (json.loads(body) if body.strip() else {})
+    except urllib.error.HTTPError as error:
+        raw = error.read().decode("utf-8", errors="replace")
+        try:
+            return error.code, json.loads(raw)
+        except json.JSONDecodeError:
+            return error.code, {"error": {"message": raw.strip() or error.reason}}
+    except urllib.error.URLError as error:
+        raise AccountError(f"cannot reach {api_url}: {error.reason}") from None
+
+
+def _message(body: Any) -> str:
+    if isinstance(body, dict):
+        error = body.get("error")
+        if isinstance(error, dict):
+            return str(error.get("message") or error.get("code") or body)
+        if isinstance(error, str):
+            return str(body.get("error_description") or error)
+    return str(body)
+
+
+class CoreThinkClient:
+    """An authenticated caller for every command that reaches the platform.
+
+    One place where a 401 becomes a sentence somebody can act on, so no command
+    has to guess whether a refusal means expired, revoked or under-scoped.
+    """
+
+    def __init__(self, *, api_url: str | None = None, token: str | None = None) -> None:
+        self.api_url = resolve_api_url(api_url)
+        self._token = resolve_token(token)
+        if not self._token:
+            raise AccountError(
+                "not signed in to CoreThink. Run `corethink login`, or set "
+                "CORETHINK_API_KEY to an API key from the Workbench's Account page."
+            )
+
+    def call(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        timeout: float = 60.0,
+    ) -> Any:
+        status, body = request(
+            self.api_url, method, path, payload=payload, token=self._token, timeout=timeout
+        )
+        if status == 401:
+            raise AccountError(
+                f"{_message(body)}\n"
+                "Your CoreThink session may have expired or been revoked. "
+                "Run `corethink login` to sign in again."
+            )
+        if status == 429:
+            raise AccountError(_message(body))
+        if status >= 400:
+            raise AccountError(f"{method} {path} failed [{status}]: {_message(body)}")
+        return body
+
+
+# -- the commands ---------------------------------------------------------
+
+
+def _print_account(payload: dict[str, Any]) -> None:
+    account = payload.get("account") or {}
+    credential = payload.get("credential") or {}
+    print(f"  account    {account.get('email', 'unknown')}")
+    print(f"  workspace  {account.get('workspace', 'unknown')}")
+    if credential:
+        print(f"  credential {credential.get('kind', 'session')} ({credential.get('id', '')})")
+    scopes = payload.get("scopes") or []
+    if scopes:
+        print(f"  access     {', '.join(scopes)}")
+
+
+def run_login(args: Any) -> int:
+    """Authorize this CLI installation through the browser you already sign in with."""
+
+    api_url = resolve_api_url(getattr(args, "api_url", None))
+    status, started = request(
+        api_url, "POST", "/v1/auth/device", payload={"client": "corethink-cli"}
+    )
+    if status != 200:
+        raise AccountError(f"cannot start sign-in: {_message(started)}")
+
+    # The plain page, never one with the code already in it. The browser half
+    # exists to have a person check this code against their own terminal, and a
+    # link that fills it in for them is the device-code phishing shape: someone
+    # else sends the link, the page pre-fills their code, one click authorizes
+    # their laptop as you.
+    verification = started.get("verification_uri")
+    print("Sign in to CoreThink")
+    print(f"  code {started['user_code']}")
+    print(f"  open {verification}")
+    print("  type that code on the page; it is not filled in for you")
+    if not getattr(args, "no_browser", False):
+        # Failure here is ordinary — a headless machine, no session bus — and the
+        # printed URL is the fallback, so it is never an error.
+        with contextlib.suppress(Exception):  # pragma: no cover - platform dependent
+            webbrowser.open(verification)
+    print("Waiting for approval… (ctrl-c to cancel)")
+
+    interval = float(started.get("interval") or 5)
+    deadline = time.monotonic() + min(
+        float(started.get("expires_in") or 600), LOGIN_TIMEOUT_SECONDS
+    )
+    while time.monotonic() < deadline:
+        time.sleep(interval)
+        status, body = request(
+            api_url,
+            "POST",
+            "/v1/auth/device/token",
+            payload={"device_code": started["device_code"]},
+        )
+        if status == 200:
+            saved = {
+                "api_url": api_url,
+                "access_token": body["access_token"],
+                "account": body.get("account", {}),
+                "scopes": body.get("scopes", []),
+                "expires_at": body.get("expires_at"),
+            }
+            written = save_credential(saved)
+            print("Signed in.")
+            _print_account({"account": saved["account"], "scopes": saved["scopes"]})
+            print(f"  stored     {written} (mode 0600)")
+            return 0
+        code = body.get("error") if isinstance(body, dict) else None
+        if code == "authorization_pending":
+            continue
+        if code == "slow_down":
+            interval += 2
+            continue
+        if code == "access_denied":
+            raise AccountError(
+                "the sign-in was declined, or that Google account is not admitted to this "
+                "CoreThink workspace. Ask an operator to add it, then run `corethink login` again."
+            )
+        if code == "expired_token":
+            raise AccountError("the sign-in request expired. Run `corethink login` again.")
+        raise AccountError(f"sign-in failed: {_message(body)}")
+    raise AccountError("timed out waiting for browser approval. Run `corethink login` again.")
+
+
+def run_whoami(args: Any) -> int:
+    client = CoreThinkClient(api_url=getattr(args, "api_url", None))
+    payload = client.call("GET", "/v1/account")
+    if getattr(args, "json", False):
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 0
+    print(f"Signed in to {client.api_url}")
+    _print_account(payload)
+    return 0
+
+
+def run_logout(args: Any) -> int:
+    """End the session on the server, then remove it from this machine.
+
+    In that order, and the local file goes whatever the server says. A CLI that
+    kept the credential because logout could not reach the network would leave a
+    usable token on a laptop somebody is trying to clean.
+    """
+
+    stored = load_credential()
+    if not stored and not os.environ.get("CORETHINK_API_KEY"):
+        print("not signed in")
+        return 0
+    remote = "not contacted"
+    try:
+        client = CoreThinkClient(api_url=getattr(args, "api_url", None))
+        client.call("POST", "/v1/account/logout")
+        remote = "session invalidated"
+    except AccountError as error:
+        remote = f"server not updated ({error})"
+    removed = clear_credential()
+    print(f"signed out: {remote}")
+    print(f"  local credential {'removed' if removed else 'not present'}")
+    if os.environ.get("CORETHINK_API_KEY"):
+        print("  note: CORETHINK_API_KEY is still set in this shell and still authenticates")
+    return 0
+
+
+def _print_keys(keys: list[dict[str, Any]]) -> None:
+    if not keys:
+        print("no API keys. Create one with `corethink keys create --name <name>`.")
+        return
+    print(f"{'ID':<18}{'NAME':<24}{'CREATED':<22}{'LAST USED':<22}STATUS")
+    for key in keys:
+        status = "revoked" if key.get("revoked_at") else "active"
+        print(
+            f"{key['id']:<18}{key['name'][:22]:<24}"
+            f"{_stamp(key.get('created_at')):<22}{_stamp(key.get('last_used_at')):<22}{status}"
+        )
+        print(f"{'':<18}scopes: {', '.join(key.get('scopes') or [])}")
+
+
+def _stamp(value: Any) -> str:
+    if not isinstance(value, (int, float)):
+        return "never"
+    return time.strftime("%Y-%m-%d %H:%M", time.localtime(value))
+
+
+def run_keys_list(args: Any) -> int:
+    client = CoreThinkClient(api_url=getattr(args, "api_url", None))
+    payload = client.call("GET", "/v1/account/keys")
+    if getattr(args, "json", False):
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 0
+    _print_keys(payload.get("keys") or [])
+    return 0
+
+
+def run_keys_create(args: Any) -> int:
+    client = CoreThinkClient(api_url=getattr(args, "api_url", None))
+    body: dict[str, Any] = {"name": args.name}
+    if args.scope:
+        body["scopes"] = list(args.scope)
+    if args.expires_in_days:
+        body["expires_in"] = int(args.expires_in_days) * 86400
+    created = client.call("POST", "/v1/account/keys", payload=body)
+    if getattr(args, "json", False):
+        print(json.dumps(created, indent=2, sort_keys=True))
+        return 0
+    print(f"created key {created['id']} ({created['name']})")
+    print(f"  scopes  {', '.join(created.get('scopes') or [])}")
+    print(
+        f"  expires {_stamp(created.get('expires_at')) if created.get('expires_at') else 'never'}"
+    )
+    print()
+    print(created["secret"])
+    print()
+    # Said plainly because it is true: the server stores only a hash, so there is
+    # no path by which this can be shown again.
+    print("This is the only time the secret is shown. Store it now; it cannot be recovered.")
+    return 0
+
+
+def run_keys_revoke(args: Any) -> int:
+    client = CoreThinkClient(api_url=getattr(args, "api_url", None))
+    revoked = client.call("DELETE", f"/v1/account/keys/{urllib.parse.quote(args.key_id)}")
+    print(f"revoked {revoked['id']} ({revoked.get('name', '')})")
+    return 0
+
+
+def register(commands: Any) -> None:
+    """Add the account commands to the CLI's subparsers."""
+
+    whoami = commands.add_parser("whoami", help="the CoreThink account this CLI is signed in as")
+    whoami.add_argument("--api-url", help="the CoreThink API to ask (default: the stored one)")
+    whoami.add_argument("--json", action="store_true")
+    whoami.set_defaults(handler=run_whoami)
+
+    keys = commands.add_parser("keys", help="API keys for scripts and integrations")
+    key_commands = keys.add_subparsers(dest="keys_command", required=True)
+
+    listing = key_commands.add_parser("list", help="every key on this account")
+    listing.add_argument("--api-url")
+    listing.add_argument("--json", action="store_true")
+    listing.set_defaults(handler=run_keys_list)
+
+    create = key_commands.add_parser("create", help="create a key; the secret is shown once")
+    create.add_argument("--name", required=True, help="what this key is for")
+    create.add_argument(
+        "--scope",
+        action="append",
+        help="one access scope; repeatable. Defaults to your own access, and can never exceed it.",
+    )
+    create.add_argument(
+        "--expires-in-days",
+        type=int,
+        help="how long the key lives. A key that never expires is the one nobody "
+        "remembers to revoke.",
+    )
+    create.add_argument("--api-url")
+    create.add_argument("--json", action="store_true")
+    create.set_defaults(handler=run_keys_create)
+
+    revoke = key_commands.add_parser("revoke", help="revoke a key, effective immediately")
+    revoke.add_argument("key_id")
+    revoke.add_argument("--api-url")
+    revoke.set_defaults(handler=run_keys_revoke)