typesafe-unofficial-cli 1.0.1__py3-none-any.whl

typesafe_unofficial_cli/__init__.py

@@ -0,0 +1,3 @@
+from typesafe_unofficial_cli._version import __version__
+
+__all__ = ["__version__"]

typesafe_unofficial_cli/__main__.py

@@ -0,0 +1,3 @@
+from typesafe_unofficial_cli.main import run
+
+run()

typesafe_unofficial_cli/_version.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("typesafe-unofficial-cli")

typesafe_unofficial_cli/auth/credentials.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+from typing import Final
+from typing import Literal
+from typing import Protocol
+
+if TYPE_CHECKING:
+    from typesafe_unofficial_cli.config.providers import Provider
+
+_VISIBLE_SUFFIX: Final = 4
+
+
+class CredentialSource(StrEnum):
+    ENVIRONMENT = "environment"
+    KEYRING = "keyring"
+    FILE = "file"
+
+
+# Both providers authenticate with a bearer API key. The tagged encoding leaves room for another
+# credential kind without migrating what is already stored.
+@dataclass(frozen=True, slots=True)
+class ApiKeyCredential:
+    api_key: str
+    kind: Literal["api_key"] = "api_key"
+
+    def masked(self) -> str:
+        if len(self.api_key) <= _VISIBLE_SUFFIX:
+            return "*" * len(self.api_key)
+        return "*" * 8 + self.api_key[-_VISIBLE_SUFFIX:]
+
+
+type Credential = ApiKeyCredential  # pylint: disable=gajaguar-module-const-naming
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedCredential:
+    credential: Credential
+    source: CredentialSource
+
+
+def encode(credential: Credential) -> str:
+    return json.dumps({"kind": credential.kind, "api_key": credential.api_key})
+
+
+def decode(raw: str) -> Credential | None:
+    try:
+        payload: object = json.loads(raw)
+    except ValueError:
+        return None
+    if not isinstance(payload, dict) or payload.get("kind") != "api_key":
+        return None
+    api_key = payload.get("api_key")
+    if not isinstance(api_key, str) or not api_key:
+        return None
+    return ApiKeyCredential(api_key=api_key)
+
+
+# `provider` only matters to the environment store, which reads a different variable per provider.
+class CredentialStore(Protocol):
+    @property
+    def source(self) -> CredentialSource: ...
+
+    def get(self, profile: str, provider: Provider) -> Credential | None: ...
+
+
+class WritableCredentialStore(CredentialStore, Protocol):
+    def available(self) -> bool: ...
+
+    def set(self, profile: str, credential: Credential) -> None: ...
+
+    def delete(self, profile: str) -> bool: ...

typesafe_unofficial_cli/auth/env_store.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typesafe_unofficial_cli.auth.credentials import ApiKeyCredential
+from typesafe_unofficial_cli.auth.credentials import CredentialSource
+from typesafe_unofficial_cli.config.providers import spec_for
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from typesafe_unofficial_cli.config.providers import Provider
+
+
+# The environment key is profile-agnostic: it overrides whatever profile is selected, for CI. It is
+# looked up by the profile's provider, so each host only ever receives its own key.
+class EnvCredentialStore:
+    def __init__(self, environ: Mapping[str, str]) -> None:
+        self._environ = environ
+
+    @property
+    def source(self) -> CredentialSource:
+        return CredentialSource.ENVIRONMENT
+
+    def get(self, profile: str, provider: Provider) -> ApiKeyCredential | None:
+        del profile
+        api_key = self._environ.get(spec_for(provider).api_key_env_var, "").strip()
+        return ApiKeyCredential(api_key=api_key) if api_key else None

typesafe_unofficial_cli/auth/file_store.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typesafe_unofficial_cli.auth.credentials import CredentialSource
+from typesafe_unofficial_cli.auth.credentials import decode
+from typesafe_unofficial_cli.auth.credentials import encode
+from typesafe_unofficial_cli.config.store import read_toml
+from typesafe_unofficial_cli.config.store import write_private_toml
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from typesafe_unofficial_cli.auth.credentials import Credential
+    from typesafe_unofficial_cli.config.providers import Provider
+
+
+# Plaintext fallback for hosts without a keyring backend; only written on explicit opt-in.
+class FileCredentialStore:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    @property
+    def source(self) -> CredentialSource:
+        return CredentialSource.FILE
+
+    @staticmethod
+    def available() -> bool:
+        return True
+
+    def get(self, profile: str, provider: Provider) -> Credential | None:
+        del provider
+        raw = self._entries().get(profile)
+        return decode(raw) if isinstance(raw, str) else None
+
+    def set(self, profile: str, credential: Credential) -> None:
+        entries = self._entries()
+        entries[profile] = encode(credential)
+        write_private_toml(self.path, {"profiles": entries})
+
+    def delete(self, profile: str) -> bool:
+        entries = self._entries()
+        if profile not in entries:
+            return False
+        del entries[profile]
+        write_private_toml(self.path, {"profiles": entries})
+        return True
+
+    def _entries(self) -> dict[str, object]:
+        profiles = read_toml(self.path).get("profiles")
+        return dict(profiles) if isinstance(profiles, dict) else {}

typesafe_unofficial_cli/auth/keyring_store.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Final
+
+import keyring
+from keyring.backends.fail import Keyring as FailKeyring
+from keyring.errors import KeyringError
+from keyring.errors import PasswordDeleteError
+
+from typesafe_unofficial_cli.auth.credentials import CredentialSource
+from typesafe_unofficial_cli.auth.credentials import decode
+from typesafe_unofficial_cli.auth.credentials import encode
+from typesafe_unofficial_cli.runtime.errors import CliError
+from typesafe_unofficial_cli.runtime.exit_codes import ExitCode
+
+if TYPE_CHECKING:
+    from typesafe_unofficial_cli.auth.credentials import Credential
+    from typesafe_unofficial_cli.config.providers import Provider
+
+SERVICE_NAME: Final = "typesafe-cli"
+
+
+class KeyringCredentialStore:
+    def __init__(self, service: str = SERVICE_NAME) -> None:
+        self._service = service
+
+    @property
+    def source(self) -> CredentialSource:
+        return CredentialSource.KEYRING
+
+    @staticmethod
+    def available() -> bool:
+        return not isinstance(keyring.get_keyring(), FailKeyring)
+
+    def get(self, profile: str, provider: Provider) -> Credential | None:
+        del provider
+        if not self.available():
+            return None
+        try:
+            raw = keyring.get_password(self._service, profile)
+        except KeyringError:
+            return None
+        return decode(raw) if raw else None
+
+    def set(self, profile: str, credential: Credential) -> None:
+        try:
+            keyring.set_password(self._service, profile, encode(credential))
+        except KeyringError as error:
+            message = f"Could not write to the system keyring: {error}"
+            raise CliError(
+                message,
+                exit_code=ExitCode.CONFIGURATION,
+                hint="Retry with --insecure-storage to use a 0600 file instead.",
+            ) from error
+
+    def delete(self, profile: str) -> bool:
+        if not self.available():
+            return False
+        try:
+            keyring.delete_password(self._service, profile)
+        except PasswordDeleteError:
+            return False
+        return True

typesafe_unofficial_cli/auth/resolver.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from typesafe_unofficial_cli.auth.credentials import ResolvedCredential
+
+if TYPE_CHECKING:
+    from typesafe_unofficial_cli.auth.credentials import CredentialStore
+    from typesafe_unofficial_cli.auth.credentials import WritableCredentialStore
+    from typesafe_unofficial_cli.auth.env_store import EnvCredentialStore
+    from typesafe_unofficial_cli.auth.file_store import FileCredentialStore
+    from typesafe_unofficial_cli.auth.keyring_store import KeyringCredentialStore
+    from typesafe_unofficial_cli.config.providers import Provider
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialStores:
+    environment: EnvCredentialStore
+    keyring: KeyringCredentialStore
+    file: FileCredentialStore
+
+    # Precedence order: the first store holding a credential for the profile wins.
+    def chain(self) -> tuple[CredentialStore, ...]:
+        return (self.environment, self.keyring, self.file)
+
+    def writable(self) -> tuple[WritableCredentialStore, ...]:
+        return (self.keyring, self.file)
+
+    def resolve(self, profile: str, provider: Provider) -> ResolvedCredential | None:
+        for store in self.chain():
+            credential = store.get(profile, provider)
+            if credential is not None:
+                return ResolvedCredential(credential=credential, source=store.source)
+        return None

typesafe_unofficial_cli/commands/ask.py

@@ -0,0 +1,149 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Annotated
+from typing import Final
+from typing import cast
+
+import typer
+
+from typesafe_unofficial_cli.output.columns import ANSWERS
+from typesafe_unofficial_cli.output.columns import ANSWERS_BATCH
+from typesafe_unofficial_cli.output.renderer import Dataset
+from typesafe_unofficial_cli.runtime.context import get_app_context
+from typesafe_unofficial_cli.runtime.errors import CliError
+from typesafe_unofficial_cli.runtime.errors import exit_code_for
+from typesafe_unofficial_cli.runtime.errors import handle_errors
+from typesafe_unofficial_cli.runtime.errors import report
+from typesafe_unofficial_cli.runtime.exit_codes import ExitCode
+from typesafe_unofficial_cli.runtime.params import options_from
+from typesafe_unofficial_cli.runtime.request_options import RequestOptions
+from typesafe_unofficial_cli.services.answers import answer_records
+from typesafe_unofficial_cli.services.answers import batch_usage_line
+from typesafe_unofficial_cli.services.answers import usage_line
+from typesafe_unofficial_cli.services.batch import BatchRequest
+from typesafe_unofficial_cli.services.batch import run_batch
+from typesafe_unofficial_cli.services.inputs import STDIN_MARKER
+from typesafe_unofficial_cli.services.inputs import StateFormat
+from typesafe_unofficial_cli.services.inputs import read_extra_body
+from typesafe_unofficial_cli.services.inputs import read_questions
+from typesafe_unofficial_cli.services.inputs import read_state
+from typesafe_unofficial_cli.services.inputs import read_states
+
+if TYPE_CHECKING:
+    from typesafe_sdk import JSONValue
+    from typesafe_sdk import QuestionModel
+    from typesafe_sdk import TypeSafeError
+
+    from typesafe_unofficial_cli.runtime.context import AppContext
+    from typesafe_unofficial_cli.runtime.request_options import RequestOverrides
+
+APP: Final = typer.Typer()
+
+
+@dataclass(frozen=True, slots=True)
+class _AskOptions(RequestOptions):
+    state: Annotated[str | None, typer.Option("--state", help="The text to evaluate.")] = None
+    state_file: Annotated[
+        Path | None,
+        typer.Option("--state-file", help="Read the state from a file; `-` reads standard input."),
+    ] = None
+    state_format: Annotated[
+        StateFormat,
+        typer.Option(
+            "--state-format", case_sensitive=False, help="Parse the state as plain text or as a JSON object/array."
+        ),
+    ] = StateFormat.TEXT
+    questions_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--questions-file",
+            help='JSON object of named questions, each {"type": "noul|choice|score", ...}; `-` reads standard input.',
+        ),
+    ] = None
+    states_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--states-file",
+            help="Batch mode: one JSON state (string, object or array) per line; `-` reads standard input.",
+        ),
+    ] = None
+    concurrency: Annotated[
+        int, typer.Option("--concurrency", min=1, help="Batch mode: requests in flight at once.")
+    ] = 4
+    extra_body: Annotated[
+        Path | None,
+        typer.Option("--extra-body", help="JSON object of extra top-level request fields; `-` reads standard input."),
+    ] = None
+    model: Annotated[
+        str | None, typer.Option("--model", help="Model name; defaults to the profile's, else jev-latest.")
+    ] = None
+
+
+@APP.command(help="Answer named questions (noul, choice, score) about a state with a System One model.")
+@handle_errors
+@options_from(_AskOptions)
+def ask(ctx: typer.Context, options: _AskOptions) -> None:
+    if options.questions_file is None:
+        message = "--questions-file is required."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    stdin_sources = [
+        flag
+        for flag, source in (
+            ("--state-file", options.state_file),
+            ("--states-file", options.states_file),
+            ("--questions-file", options.questions_file),
+            ("--extra-body", options.extra_body),
+        )
+        if str(source) == STDIN_MARKER
+    ]
+    if len(stdin_sources) > 1:
+        message = f"Only one of {', '.join(stdin_sources)} can read standard input."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    if options.states_file is not None and (options.state is not None or options.state_file is not None):
+        message = "--states-file cannot be combined with --state or --state-file."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    app_context = get_app_context(ctx)
+    overrides = options.overrides()
+    questions = read_questions(options.questions_file)
+    extra_body = None if options.extra_body is None else read_extra_body(options.extra_body)
+    if options.states_file is not None:
+        _ask_batch(app_context, options, overrides, questions, extra_body)
+        return
+    content = read_state(text=options.state, file=options.state_file, state_format=options.state_format)
+    response = app_context.client(overrides).system_one(content, questions, model=options.model, extra_body=extra_body)
+    app_context.notify(usage_line(response))
+    app_context.render(Dataset(records=answer_records(response), columns=ANSWERS, id_key="question"))
+
+
+# Answers are rendered first, then each failed state is reported and the first failure sets the exit code.
+def _ask_batch(
+    app_context: AppContext,
+    options: _AskOptions,
+    overrides: RequestOverrides,
+    questions: dict[str, QuestionModel],
+    extra_body: dict[str, JSONValue | None] | None,
+) -> None:
+    request = BatchRequest(
+        states=read_states(cast("Path", options.states_file)),
+        questions=questions,
+        model=options.model,
+        extra_body=extra_body,
+        concurrency=options.concurrency,
+    )
+    items = run_batch(app_context.async_client(overrides), request)
+    answered = [item.response for item in items if item.response is not None]
+    records = [
+        record
+        for item in items
+        if item.response is not None
+        for record in answer_records(item.response, index=item.index)
+    ]
+    app_context.notify(batch_usage_line(answered))
+    app_context.render(Dataset(records=records, columns=ANSWERS_BATCH, id_key="question"))
+    failures = [item for item in items if item.error is not None]
+    for item in failures:
+        report(f"state {item.index}: {item.error}")
+    if failures:
+        message = f"{len(failures)} of {len(items)} states failed."
+        raise CliError(message, exit_code=exit_code_for(cast("TypeSafeError", failures[0].error)))

typesafe_unofficial_cli/commands/auth.py

@@ -0,0 +1,193 @@
+import sys
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+from typing import Annotated
+from typing import Final
+
+import typer
+from pydantic import ValidationError
+
+from typesafe_unofficial_cli.auth.credentials import ApiKeyCredential
+from typesafe_unofficial_cli.config.providers import Provider
+from typesafe_unofficial_cli.config.providers import spec_for
+from typesafe_unofficial_cli.config.settings import Profile
+from typesafe_unofficial_cli.output.columns import AUTH_STATUS
+from typesafe_unofficial_cli.output.renderer import single
+from typesafe_unofficial_cli.runtime.client_factory import ClientRequest
+from typesafe_unofficial_cli.runtime.context import get_app_context
+from typesafe_unofficial_cli.runtime.errors import CliError
+from typesafe_unofficial_cli.runtime.errors import handle_errors
+from typesafe_unofficial_cli.runtime.exit_codes import ExitCode
+from typesafe_unofficial_cli.runtime.params import options_from
+from typesafe_unofficial_cli.services.validation import verify_key
+
+if TYPE_CHECKING:
+    from typesafe_unofficial_cli.auth.credentials import WritableCredentialStore
+    from typesafe_unofficial_cli.auth.resolver import CredentialStores
+
+APP: Final = typer.Typer(help="Log in, inspect, and remove API credentials.", no_args_is_help=True)
+
+
+def _read_api_key(provider: Provider, *, with_token: bool) -> str:
+    # No --api-key flag on purpose: a key passed as an argument ends up in shell history.
+    raw = (
+        sys.stdin.read()
+        if with_token
+        else typer.prompt(f"{spec_for(provider).display_name} API key", hide_input=True, err=True)
+    )
+    api_key = str(raw).strip()
+    if not api_key:
+        message = "The API key is empty."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    return api_key
+
+
+def _select_store(stores: CredentialStores, *, insecure_storage: bool) -> WritableCredentialStore:
+    if insecure_storage:
+        return stores.file
+    if stores.keyring.available():
+        return stores.keyring
+    message = "No system keyring backend is available."
+    raise CliError(
+        message,
+        exit_code=ExitCode.CONFIGURATION,
+        hint="Retry with --insecure-storage, or set the provider's API key variable in the environment.",
+    )
+
+
+def _status_record(profile_name: str, profile: Profile, source: str, masked_key: str) -> dict[str, object]:
+    return {
+        "profile": profile_name,
+        "provider": profile.provider,
+        "base_url": profile.effective_base_url(),
+        "model": profile.model,
+        "source": source,
+        "api_key": masked_key,
+    }
+
+
+@dataclass(frozen=True, slots=True)
+class _LoginOptions:
+    provider: Annotated[
+        Provider | None,
+        typer.Option(
+            "--provider",
+            case_sensitive=False,
+            help="Where the key is valid; defaults to the profile's, else typesafe.",
+        ),
+    ] = None
+    base_url: Annotated[
+        str | None,
+        typer.Option("--base-url", help="Override the provider's API root, e.g. for a proxy."),
+    ] = None
+    with_token: Annotated[bool, typer.Option("--with-token", help="Read the API key from standard input.")] = False
+    insecure_storage: Annotated[
+        bool,
+        typer.Option("--insecure-storage", help="Store the key in a 0600 plaintext file instead of the keyring."),
+    ] = False
+    skip_validation: Annotated[
+        bool,
+        typer.Option("--skip-validation", help="Store the key without calling the provider."),
+    ] = False
+
+
+@APP.command(
+    help=(
+        "Validate an API key and store it for the selected profile. "
+        "A TypeSafe key is checked for free; an OpenRouter key needs one minimal billed request "
+        "(skip it with --skip-validation). Environment variables for automation: "
+        "TYPESAFE_API_KEY (provider typesafe) and OPENROUTER_API_KEY (provider openrouter)."
+    ),
+)
+@handle_errors
+@options_from(_LoginOptions)
+def login(ctx: typer.Context, options: _LoginOptions) -> None:
+    app_context = get_app_context(ctx)
+    stores = app_context.services.credentials
+    profile_name = app_context.options.profile_name
+    current = app_context.options.profile
+    resolved_provider = options.provider or current.provider
+    # A different provider invalidates the old override and default model, which belong to the old host.
+    keeps_settings = resolved_provider is current.provider
+    try:
+        profile = Profile(
+            provider=resolved_provider,
+            base_url=options.base_url or (current.base_url if keeps_settings else None),
+            model=current.model if keeps_settings else None,
+        )
+    except ValidationError as error:
+        message = error.errors()[0]["msg"].removeprefix("Value error, ")
+        raise CliError(message, exit_code=ExitCode.USAGE) from error
+    credential = ApiKeyCredential(api_key=_read_api_key(resolved_provider, with_token=options.with_token))
+    if not options.skip_validation:
+        request = ClientRequest(
+            credential=credential,
+            base_url=profile.effective_base_url(),
+            model=profile.model,
+            verbose=app_context.options.verbose,
+        )
+        with app_context.services.clients(request) as client:
+            verify_key(client, resolved_provider)
+    store = _select_store(stores, insecure_storage=options.insecure_storage)
+    store.set(profile_name, credential)
+    for other in stores.writable():
+        if other is not store:
+            other.delete(profile_name)
+    settings = app_context.services.settings.load()
+    if not settings.profiles:
+        settings = settings.model_copy(update={"default_profile": profile_name})
+    app_context.services.settings.save(settings.with_profile(profile_name, profile))
+    app_context.notify(
+        f"Logged in to profile '{profile_name}' ({spec_for(resolved_provider).display_name}, {store.source})."
+    )
+    app_context.render(single(_status_record(profile_name, profile, store.source, credential.masked()), AUTH_STATUS))
+
+
+@APP.command(help="Show the active credential; --check also validates it with the provider.")
+@handle_errors
+def status(
+    ctx: typer.Context,
+    *,
+    check: Annotated[
+        bool, typer.Option("--check", help="Validate the key with the provider (OpenRouter bills one request).")
+    ] = False,
+) -> None:
+    app_context = get_app_context(ctx)
+    resolved = app_context.credential()
+    if check:
+        verify_key(app_context.client(), app_context.options.profile.provider)
+    record = _status_record(
+        app_context.options.profile_name,
+        app_context.options.profile,
+        resolved.source,
+        resolved.credential.masked(),
+    )
+    app_context.render(single(record, AUTH_STATUS))
+
+
+@APP.command(help="Remove the stored credential and profile.")
+@handle_errors
+def logout(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    services = app_context.services
+    profile_name = app_context.options.profile_name
+    removed = [store.source for store in services.credentials.writable() if store.delete(profile_name)]
+    settings = services.settings.load()
+    had_profile = profile_name in settings.profiles
+    if had_profile:
+        services.settings.save(settings.without_profile(profile_name))
+    if not removed and not had_profile:
+        message = f"No stored credentials for profile '{profile_name}'."
+        raise CliError(message, exit_code=ExitCode.CONFIGURATION)
+    app_context.notify(f"Logged out of profile '{profile_name}'.")
+    provider = app_context.options.profile.provider
+    if services.credentials.environment.get(profile_name, provider) is not None:
+        variable = spec_for(provider).api_key_env_var
+        app_context.notify(f"{variable} is still set in the environment and will keep being used.")
+
+
+@APP.command(help="Print the raw API key of the active credential.")
+@handle_errors
+def token(ctx: typer.Context) -> None:
+    resolved = get_app_context(ctx).credential()
+    typer.echo(resolved.credential.api_key)