typesafeai-cli 0.3.1__py3-none-any.whl

typesafe_cli/commands/rank.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from typesafe_cli.commands.eval import call_system_one
+from typesafe_cli.io import emit_success, fail
+from typesafe_cli.questions import QuestionError
+from typesafe_cli.recipes.rank import load_candidates, rank_chunks, rank_questions, sort_ranked
+
+
+def rank(
+    query: str = typer.Option(..., "--query"),
+    candidates_file: Path = typer.Option(..., "--candidates-file", help="JSON array of objects"),
+    id_field: str = typer.Option("id", "--id-field"),
+    text_field: str = typer.Option("text", "--text-field"),
+    model: str | None = typer.Option(None, "--model"),
+    key: str | None = typer.Option(None, "--key"),
+    creds: Path | None = typer.Option(None, "--creds"),
+) -> None:
+    """Rerank a local shortlist with one Score per candidate."""
+    try:
+        items = load_candidates(json.loads(candidates_file.read_text(encoding="utf-8")))
+    except (OSError, json.JSONDecodeError, QuestionError) as exc:
+        fail(code="usage", message=str(exc), exit_code=2)
+
+    answers: dict = {}
+    model_id = None
+    usage = {"input_tokens": 0, "output_tokens": 0}
+    try:
+        for chunk in rank_chunks(items):
+            state, questions = rank_questions(
+                chunk, query=query, id_field=id_field, text_field=text_field
+            )
+            data = call_system_one(state=state, questions=questions, key=key, creds=creds, model=model)
+            answers.update(data["answers"])
+            model_id = data.get("model") or model_id
+            usage["input_tokens"] += int((data.get("usage") or {}).get("input_tokens") or 0)
+            usage["output_tokens"] += int((data.get("usage") or {}).get("output_tokens") or 0)
+        ranked = sort_ranked(items, answers, id_field=id_field)
+    except QuestionError as exc:
+        fail(code="usage", message=str(exc), exit_code=2)
+
+    emit_success(
+        data={"query": query, "ranked": ranked, "model": model_id, "usage": usage},
+        command="rank",
+    )

typesafe_cli/commands/screen.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from typesafe_cli.commands.eval import call_system_one
+from typesafe_cli.io import emit_success, fail
+from typesafe_cli.questions import QuestionError
+from typesafe_cli.recipes.screen import SCREEN_QUESTIONS, interpret_screen
+
+
+def screen(
+    text_file: Path = typer.Option(..., "--text-file"),
+    model: str | None = typer.Option(None, "--model"),
+    key: str | None = typer.Option(None, "--key"),
+    creds: Path | None = typer.Option(None, "--creds"),
+) -> None:
+    """Guardrail pack: jailbreak, injection, sensitive data, harm. Suggested action is policy."""
+    try:
+        text = text_file.read_text(encoding="utf-8")
+        if not text.strip():
+            raise QuestionError("text file is empty")
+    except (OSError, QuestionError) as exc:
+        fail(code="usage", message=str(exc), exit_code=2)
+
+    data = call_system_one(
+        state={"text": text},
+        questions=SCREEN_QUESTIONS,
+        key=key,
+        creds=creds,
+        model=model,
+    )
+    interpreted = interpret_screen(data["answers"])
+    interpreted["model"] = data.get("model")
+    interpreted["usage"] = data.get("usage")
+    interpreted["answers"] = data["answers"]
+    emit_success(data=interpreted, command="screen")

typesafe_cli/commands/skills.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from importlib.resources import files
+from pathlib import Path
+
+import typer
+
+from typesafe_cli.detect import detect_agent_info, resolve_agent
+from typesafe_cli.io import emit_success, fail
+
+OFFICIAL_SKILL_URL = (
+    "https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md"
+)
+
+SKILL_DIR_BY_AGENT = {
+    "claude-code": ".claude/skills",
+    "cursor": ".cursor/skills",
+    "windsurf": ".windsurf/skills",
+    "gemini-code": ".gemini/skills",
+    "codex": ".agents/skills",
+    "opencode": ".agents/skills",
+    "grok": ".agents/skills",
+    "generic-agent": ".agents/skills",
+}
+
+USER_SKILL_DIR_BY_AGENT = {
+    "claude-code": Path.home() / ".claude" / "skills",
+    "cursor": Path.home() / ".cursor" / "skills",
+    "windsurf": Path.home() / ".windsurf" / "skills",
+    "gemini-code": Path.home() / ".gemini" / "skills",
+    "codex": Path.home() / ".agents" / "skills",
+    "opencode": Path.home() / ".agents" / "skills",
+    "grok": Path.home() / ".agents" / "skills",
+    "generic-agent": Path.home() / ".agents" / "skills",
+}
+
+EXISTING_PROJECT_DIRS = (
+    ".agents/skills",
+    ".claude/skills",
+    ".cursor/skills",
+    ".windsurf/skills",
+    ".gemini/skills",
+)
+
+
+def install(
+    target: str = typer.Option("auto", "--target", help="claude, cursor, codex, grok, or auto"),
+    directory: Path | None = typer.Option(None, "--dir", help="Explicit skills directory"),
+    project: bool = typer.Option(True, "--project/--global", help="Install into the current project (default)"),
+    offline: bool = typer.Option(False, "--offline", help="Use the vendored official skill, skip GitHub"),
+) -> None:
+    try:
+        official = load_official_skill(offline=offline)
+        cli_note = _vendored("typesafe-ai", "CLI.md")
+        cli_skill = _vendored("typesafe-cli", "SKILL.md")
+    except OSError as exc:
+        fail(code="request", message=f"could not load skills: {exc}", exit_code=1)
+
+    agent = resolve_agent(target=target)
+    dest_root = directory if directory is not None else _skills_root(agent=agent, project=project)
+    written: list[str] = []
+    try:
+        pairs = [
+            (dest_root / "typesafe-ai" / "SKILL.md", official),
+            (dest_root / "typesafe-ai" / "CLI.md", cli_note),
+            (dest_root / "typesafe-cli" / "SKILL.md", cli_skill),
+        ]
+        for path, body in pairs:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(body, encoding="utf-8")
+            written.append(str(path))
+    except OSError as exc:
+        fail(code="request", message=str(exc), exit_code=1)
+
+    emit_success(
+        data={
+            "agent": agent,
+            "written": written,
+            "source": "offline-vendored" if offline else "github-or-vendored",
+            "note": "Installed typesafe-ai (design) and typesafe-cli (collect state, then typesafe ask). Agents cannot access TYPESAFE_* env vars.",
+        },
+        command="skills install",
+    )
+
+
+def list_skills() -> None:
+    info = detect_agent_info()
+    emit_success(
+        data={
+            "skills": [
+                {
+                    "name": "typesafe-cli",
+                    "description": "Collect local context, then run the typesafe CLI for a Jev judgment.",
+                    "type": "skill",
+                },
+                {
+                    "name": "typesafe-ai",
+                    "description": "Official TypeSafe skill: design typed judgments and compose them in code.",
+                    "type": "skill",
+                },
+            ],
+            "detected_agent": info.name or None,
+        },
+        command="skills list",
+    )
+
+
+def load_official_skill(*, offline: bool = False) -> str:
+    if not offline:
+        try:
+            with urllib.request.urlopen(OFFICIAL_SKILL_URL, timeout=10) as response:
+                text = response.read().decode("utf-8")
+            if text.strip().startswith("---") and "typesafe-ai" in text:
+                return text
+        except (urllib.error.URLError, TimeoutError, OSError):
+            pass
+    return _vendored("typesafe-ai", "SKILL.md")
+
+
+def _vendored(*parts: str) -> str:
+    path = files("typesafe_cli.data")
+    for part in parts:
+        path = path / part
+    return path.read_text(encoding="utf-8")
+
+
+def _skills_root(*, agent: str, project: bool) -> Path:
+    if project:
+        cwd = Path.cwd()
+        for rel in EXISTING_PROJECT_DIRS:
+            candidate = cwd / rel
+            if candidate.is_dir():
+                return candidate
+        rel = SKILL_DIR_BY_AGENT.get(agent, ".agents/skills")
+        return cwd / rel
+    return USER_SKILL_DIR_BY_AGENT.get(agent, Path.home() / ".agents" / "skills")

typesafe_cli/commands/smoke.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from typesafe_cli.commands.ask import run_evaluation
+from typesafe_cli.questions import load_questions
+
+SMOKE_STATE = (
+    "Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. "
+    "I'm losing sales. Please help ASAP."
+)
+SMOKE_QUESTIONS = {
+    "urgency": {
+        "type": "noul",
+        "instructions": "Does this message express urgency?",
+    }
+}
+
+
+def smoke(
+    key: str | None = typer.Option(None, "--key"),
+    creds: Path | None = typer.Option(None, "--creds"),
+    model: str | None = typer.Option(None, "--model"),
+) -> None:
+    questions = load_questions(SMOKE_QUESTIONS)
+    run_evaluation(
+        state=SMOKE_STATE,
+        questions=questions,
+        key=key,
+        creds=creds,
+        model=model,
+        command="smoke",
+    )

typesafe_cli/commands/suggest_skill.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from typesafe_cli.commands.eval import call_system_one
+from typesafe_cli.io import emit_success, fail
+from typesafe_cli.questions import QuestionError
+from typesafe_cli.recipes.skills import (
+    discover_skills,
+    pick_skill,
+    rank_questions,
+    reread_questions,
+    shortlist_from_rank,
+)
+from typesafe_cli.recipes.thresholds import SKILL_TOP_K
+
+
+def suggest_skill(
+    task: str = typer.Option(..., "--task"),
+    skills_dir: Path = typer.Option(..., "--skills-dir"),
+    model: str | None = typer.Option(None, "--model"),
+    key: str | None = typer.Option(None, "--key"),
+    creds: Path | None = typer.Option(None, "--creds"),
+) -> None:
+    """Pick at most one skill: cheap rank, then reread the top three. The agent still decides."""
+    try:
+        skills = discover_skills(skills_dir)
+        rank_state, rank_qs = rank_questions(task, skills)
+    except QuestionError as exc:
+        fail(code="usage", message=str(exc), exit_code=2)
+
+    rank_data = call_system_one(state=rank_state, questions=rank_qs, key=key, creds=creds, model=model)
+    shortlist = shortlist_from_rank(skills, rank_data["answers"], top_k=SKILL_TOP_K)
+    reread_state, reread_qs = reread_questions(task, shortlist)
+    fit_data = call_system_one(state=reread_state, questions=reread_qs, key=key, creds=creds, model=model)
+    chosen = pick_skill(rank_answers=rank_data["answers"], fit_answers=fit_data["answers"], shortlist=shortlist)
+    emit_success(
+        data={
+            "skill": chosen,
+            "shortlist": [skill["name"] for skill in shortlist],
+            "rank": rank_data["answers"],
+            "fits": fit_data["answers"],
+            "model": fit_data.get("model") or rank_data.get("model"),
+        },
+        command="suggest-skill",
+    )

typesafe_cli/commands/verify.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from typesafe_cli.commands.eval import call_system_one
+from typesafe_cli.io import emit_success, fail
+from typesafe_cli.questions import QuestionError
+from typesafe_cli.recipes.verify import interpret_verify, quote_in_source, verify_questions, verify_state
+
+
+def verify(
+    claim: str = typer.Option(..., "--claim"),
+    source_file: Path = typer.Option(..., "--source-file"),
+    quote: str | None = typer.Option(None, "--quote", help="If set, must appear in the source"),
+    model: str | None = typer.Option(None, "--model"),
+    key: str | None = typer.Option(None, "--key"),
+    creds: Path | None = typer.Option(None, "--creds"),
+) -> None:
+    """Check whether a source supports a claim. Missing quotes are fabricated locally."""
+    try:
+        source = source_file.read_text(encoding="utf-8")
+        if not claim.strip() or not source.strip():
+            raise QuestionError("claim and source must be non-empty")
+    except (OSError, QuestionError) as exc:
+        fail(code="usage", message=str(exc), exit_code=2)
+
+    if quote and not quote_in_source(source, quote):
+        emit_success(
+            data={
+                "verdict": "fabricated",
+                "confidence": 1.0,
+                "auto": False,
+                "review": True,
+                "skipped": True,
+            },
+            command="verify",
+        )
+        return
+
+    data = call_system_one(
+        state=verify_state(claim=claim, source=source, quote=quote),
+        questions=verify_questions(claim=claim),
+        key=key,
+        creds=creds,
+        model=model,
+    )
+    interpreted = interpret_verify(data["answers"]["support"])
+    interpreted["skipped"] = False
+    interpreted["model"] = data.get("model")
+    interpreted["usage"] = data.get("usage")
+    emit_success(data=interpreted, command="verify")

typesafe_cli/config.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_BASE_URL = "https://api.typesafe.ai"
+DEFAULT_MODEL = "jev-latest"
+
+
+@dataclass(frozen=True)
+class Config:
+    api_key: str | None
+    base_url: str
+    model: str
+
+
+def load_config(
+    *,
+    key: str | None = None,
+    creds: Path | None = None,
+    model: str | None = None,
+    base_url: str | None = None,
+) -> Config:
+    api_key = key
+    if api_key is None and creds is not None:
+        payload = json.loads(creds.read_text(encoding="utf-8"))
+        if not isinstance(payload, dict) or "api_key" not in payload:
+            raise ValueError("creds file must be JSON with an api_key field")
+        api_key = payload["api_key"]
+    if api_key is None:
+        api_key = os.environ.get("TYPESAFE_API_KEY") or None
+
+    resolved_base = base_url or os.environ.get("TYPESAFE_BASE_URL") or DEFAULT_BASE_URL
+    resolved_model = model or os.environ.get("TYPESAFE_DEFAULT_MODEL") or DEFAULT_MODEL
+    return Config(api_key=api_key, base_url=resolved_base, model=resolved_model)

typesafe_cli/data/typesafe-ai/CLI.md

@@ -0,0 +1,7 @@
+# Using the typesafe CLI
+
+Live evaluations: follow the **typesafe-cli** skill. Prefer `find`, `rank`, `extract`, `verify`, `screen`, `suggest-skill`, and `decide` when those flags fit; otherwise collect local state, write JSON under `${TMPDIR:-/tmp}/codex/<project>/`, then `typesafe ask`. Never drop those files in the git tree. This sidecar does not replace that skill or the official TypeSafe skill.
+
+## Secrets
+
+You cannot read, print, or inspect typesafeai-cli env vars or key files (`TYPESAFE_*`, `~/.config/typesafe/env`, `.env.local`). Run `typesafe auth status` (`has_key` only). If false, ask the human.

typesafe_cli/data/typesafe-ai/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: typesafe-ai
+license: MIT
+description: >
+  Build AI-powered software with TypeSafe: small units of AI intelligence you
+  can use like programming primitives. Its System One models, including Jev,
+  turn natural language and application state into typed judgments and
+  probabilities that code can combine. Use when a feature needs programmable
+  common sense, when brainstorming what AI could make possible in an app, or
+  when an LLM prompt-and-parse step could become a structured decision.
+  Applications include routing, ranking, extraction, verification, and
+  interactive experiences; these are starting points, not the limits.
+  Read live docs and cookbooks to find useful patterns and discover new combinations.
+---
+
+# Build with TypeSafe
+
+TypeSafe makes units of AI intelligence usable like programming primitives: small
+judgments you can compose into larger capabilities. Its **System One models** return
+fast, focused judgments that software can consume directly. **Jev** is TypeSafe's
+flagship and first System One model. It understands natural language and returns
+typed answers and probabilities rather
+than generating text or reasoning explanations. Code owns the workflow; the model
+supplies programmable common sense where ordinary code needs semantic understanding.
+
+## Read the live docs
+
+**The live TypeSafe docs are the source of truth. Read them as part of the task.**
+This skill gives direction; the docs carry current concepts, prompting guidance,
+API contracts, SDK usage, models, limits, and worked examples.
+
+- Start with the [documentation index](https://docs.typesafe.ai/llms.txt) to discover
+  relevant pages and cookbooks. Use targeted reads rather than loading the entire site.
+- Mintlify serves Markdown by appending `.md` to a page path, for example
+  [how to build with TypeSafe](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md).
+  Follow links from the index; convert extensionless documentation page links to
+  `.md` when useful. Resolve relative links against `https://docs.typesafe.ai`.
+- Before writing an integration, read the current API or chosen SDK page and the
+  question guidance relevant to the design. For a new workflow, also inspect the
+  closest cookbook: it often shows a better decomposition than a generic classifier.
+- If the index is unavailable, use the direct links below or the site's navigation.
+  If Markdown fetching fails, try the normal page. If live access is unavailable,
+  use available local docs or installed SDK types, state that limitation, and avoid
+  inventing version-dependent details.
+
+| Task | Start here; follow the relevant details |
+| --- | --- |
+| Understand the programming model | [System One](https://docs.typesafe.ai/concepts/system-one.md), [building guide](https://docs.typesafe.ai/concepts/how-to-build-with-system-one.md) |
+| Explore what to build | [Use-case map](https://docs.typesafe.ai/concepts/use-case-map.md), then relevant cookbooks from the index |
+| Prepare inputs and questions | [State](https://docs.typesafe.ai/concepts/state.md), [primitives](https://docs.typesafe.ai/primitives.md), then the chosen primitive's page |
+| Decide how to handle uncertainty | [Confidence](https://docs.typesafe.ai/confidence.md) |
+| Write API code | [HTTP API](https://docs.typesafe.ai/api.md), [Python SDK](https://docs.typesafe.ai/sdk/python.md), or [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript.md) |
+| Update an older integration | [Migration guide](https://docs.typesafe.ai/migrating-to-v1.md) and the installed SDK's current reference |
+
+## Find the useful shape
+
+Start from the behavior the user wants: what will the application show, select,
+change, or hand off? Work backward to the judgments it needs. Keep known rules,
+calculations, exact lookups, and execution in code. Preserve the user's chosen stack
+and scope; add TypeSafe where semantic understanding helps.
+
+When brainstorming or choosing an architecture, consider more than classification.
+The patterns below are starting points: combine primitives around the user's goal,
+including ideas that do not fit an established recipe.
+
+- **Route and fill known arguments.** A request can select a handler and its typed
+  parameters. Ask useful branch-specific questions up front and consume only the
+  relevant answers. Explore [function calling](https://docs.typesafe.ai/cookbooks/function_calling.md)
+  and [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out.md).
+- **Select instead of generate.** Find candidate values or source spans in code,
+  use a judgment to select the intended one, then copy or normalize it. Code can
+  also assemble source text into a formatted document or reading guide. Explore
+  [value extraction](https://docs.typesafe.ai/cookbooks/pre_parsed_value_extraction_cookbook.md)
+  and [structure recovery](https://docs.typesafe.ai/cookbooks/autoformat.md).
+- **Find and judge evidence.** Retrieve candidates, compare their relevance to a
+  query, and select useful context. Explore [reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe.md)
+  and [hierarchical classification](https://docs.typesafe.ai/cookbooks/hierarchical_classification.md).
+- **Turn judgments into reusable data.** Score dimensions once, then let code or
+  user controls change weights, thresholds, rankings, and views. With labeled
+  outcomes, those signals can become classical ML features. Explore
+  [composite scoring](https://docs.typesafe.ai/patterns/composite-scoring.md) and
+  [feature discovery](https://docs.typesafe.ai/cookbooks/autoresearch_feature_discovery.md).
+- **Verify and escalate.** Check specific claims or fields against their evidence;
+  send uncertain or failing cases to a person or reasoning model. Explore
+  [citation checks](https://docs.typesafe.ai/cookbooks/citation_check.md) and
+  [extraction cascades](https://docs.typesafe.ai/cookbooks/sde_cascade.md).
+- **Respond to changing state.** Code can retain goals and observations while fresh
+  judgments guide the next bounded step. Keep inferred state distinct from observed
+  facts, and check freshness before applying a result to a changed situation.
+
+For open-ended requests, offer the few directions that best serve the user's goal
+and recommend a starting point. For a concrete request, choose the relevant pattern
+and build; a brainstorm is not a mandatory detour.
+
+## Design the judgments
+
+Choose by what the answer means, then read the relevant primitive page:
+
+| Need | Primitive | Important distinction |
+| --- | --- | --- |
+| One of a defined set | [Choice](https://docs.typesafe.ai/primitives/choice.md) | Picks one option; its distribution compares competing options |
+| Whether a condition holds | [Noul](https://docs.typesafe.ai/primitives/noul.md) | Probability of yes; no separate confidence; use one per label when several may apply |
+| Degree along a described dimension | [Score](https://docs.typesafe.ai/primitives/score.md) | Probability-weighted position on ordered levels; use comparable per-item Scores for graded ranking |
+
+Give each question enough relevant **state** to answer: source text, identities,
+relationships, policies, and current facts. Prefer named JSON fields when context
+has several parts. Put the judgment in **instructions** and define its possible
+answers in **criteria**. Question IDs are for code and are not sent to the model;
+include complete meaning in the question. Reference nested state with backticked
+paths such as `ticket.messages[0].text`.
+
+Ask one narrow, coherent judgment per question. Split independently useful dimensions,
+without destroying the relationship being judged. A bounded action selection or
+contextual interpretation is valid; atomic does not mean literal fact extraction
+or a one-sentence limit. Strings work for simple questions. Use structured objects
+or arrays when definitions, contrasts, exclusions, or examples clarify instructions
+or criteria. Score levels must describe concrete situations and stand on their own.
+
+Keep the needed answers available. Include a no-match outcome when nothing may fit;
+use a separate presence judgment when it is independently useful. For source-value
+selection, check candidate coverage: the model cannot choose an omitted value.
+
+## Compose and verify
+
+**Ask independent questions over the same state together**, including useful
+speculative questions. They run in parallel and cannot see one another's answers.
+State each speculative premise explicitly; code consumes the applicable answers.
+A second request is warranted when an earlier answer is needed to fetch evidence,
+construct new state, or determine the next options. Extra questions still use tokens;
+measure actual request budgets, cost, and end-to-end latency.
+
+Use probabilities and confidence to guide behavior, with thresholds evaluated on
+the user's data and consequences. Choice/Score confidence summarizes distribution
+concentration, not overall workflow correctness or permission to act. A Noul near
+0.5 means similar probability for yes and no, not medium intensity. Several
+acceptable alternatives can also spread probability; low confidence need not
+invalidate a harmless preference choice. Ignore uncertainty on unused branches.
+
+Keep policy explicit and raw judgments reusable. Weighted scores suit compensating
+preferences; an “any serious violation” rule needs separate conditions. Changing a
+weight or display filter need not rerun inference when evidence and question meanings
+are unchanged. Typed output guarantees the interface, not truth. System One models
+are trained for calibrated decisions; validate their performance in the target domain.
+
+Test representative cases and the resulting application behavior. For failures,
+inspect the exact state, questions, candidates, answers, composition, and observed
+outcome. Separate missing evidence, model errors, code errors, and service failures.
+Treat cookbook thresholds and demo results as examples to evaluate, not universal
+rules or permanent model limitations. Keep API credentials server-side in web apps.