portico-cli 0.1.0__py3-none-any.whl

portico/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

portico/analyzer.py

@@ -0,0 +1,213 @@
+import json
+import re
+from dataclasses import dataclass
+
+from pydantic import ValidationError
+
+from portico.providers.base import LLMProvider
+from portico.providers.claude import DEFAULT_MODEL
+from portico.schema import PorticoJSON
+
+PROMPT_TEMPLATE = """\
+You are portico. You decompose any input into a three-layer "portico": a roof \
+(the unifying idea), pillars (the load-bearing components), and a base (the foundation \
+everything rests on).
+
+Read the input below and emit STRICTLY VALID JSON matching the schema.
+
+The JSON is a SINGLE FLAT OBJECT with these top-level keys, in this exact order. None \
+of the keys nest under category headers; do not introduce wrapper objects like \
+"reasoning" or "output".
+
+Top-level keys:
+
+1. "input_type": string. What kind of artifact this is (essay, codebase, business plan, ...).
+2. "type_rationale": string. One sentence on why you classified it that way.
+3. "decomposition_strategy": string. One sentence on how you'll split it into roof / pillars / base.
+4. "scratch_outline": array of 3-7 short strings capturing the load-bearing parts before you label.
+5. "mece_check": string. One sentence: are the pillars mutually exclusive and collectively \
+exhaustive at the same level of abstraction?
+6. "theme": string. A short free-form label for the input type ("essay", "codebase", ...).
+7. "title": string. The input's title or a 1-3 word identifier.
+8. "roof": object {"label": string, "summary": string}. The unifying idea on top.
+9. "pillars": array of 2-9 objects, each {"label": string, "summary": string}. STRONGLY PREFER 3-5.
+10. "base": object {"labels": array of 1-4 strings, "summary": string}. The foundation that \
+everything rests on. Use 1 label for a single foundation; add a 2nd/3rd/4th ONLY when each \
+names a distinct foundational course that earns its place. Redundancy is noise.
+11. "fit_quality": one of "good", "stretched", "forced", "not_applicable".
+12. "notes_on_fit": string. If not "good", explain why in one sentence.
+
+Concrete example of the exact shape (illustrative content; do not copy the values):
+
+{
+  "input_type": "essay",
+  "type_rationale": "Argumentative prose with thesis and supporting reasoning.",
+  "decomposition_strategy": "Thesis on top; two arguments as pillars; evidence at base.",
+  "scratch_outline": ["Sub-linear trust ...", "Feedback loops ...", "Dunbar ...", "Evidence ..."],
+  "mece_check": "Two pillars are non-overlapping causal mechanisms.",
+  "theme": "essay",
+  "title": "trust at scale",
+  "roof": {"label": "Sub-linear Trust", "summary": "Trust scales sub-linearly with size."},
+  "pillars": [
+    {"label": "Feedback loops", "summary": "Smaller groups close feedback faster."},
+    {"label": "Dunbar limit", "summary": "Diffusion of responsibility past ~150."}
+  ],
+  "base": {"labels": ["Empirical evidence"], "summary": "Observed work on team size and trust."},
+  "fit_quality": "good",
+  "notes_on_fit": "Essay decomposes cleanly into thesis / arguments / evidence."
+}
+
+Notice the roof uses "Sub-linear Trust" (the actual claim from the input), NOT a generic \
+"Thesis". This is the most important rule below.
+
+Rules:
+
+LABELS (calibrate between two failure modes):
+
+Failure mode A -- TOO GENERIC: labels that could apply to any input of the same type \
+("Hypothesis", "Methodology", "Findings", "Seed Thesis", "Central Claim"). These add no \
+value because they describe the slot, not the contents.
+
+Failure mode B -- TOO CRYPTIC: labels so specific they need the input to decode \
+("5→15→30→60", "Gini-NIAH Tie", "Re-found Each Doubling"). These add no value because the \
+reader has to consult the source to make sense of them.
+
+The sweet spot: short noun phrases that are *recognizable from the input* but *readable on \
+their own*. Bias slightly toward the abstract side -- when in doubt between "too specific \
+to read at a glance" and "a bit generic but clear", choose clear.
+
+Concrete rules:
+- USE THE INPUT'S OWN VOCABULARY: when the input names a concept ("Dunbar limit", \
+  "tragedy of the commons", "loaders"), reuse those terms. Don't invent synonyms.
+- ROOF MUST NOT EQUAL THE TITLE: the banner above the portico already names the input \
+  (e.g. "── software README: httpx ──"). The roof must do different work -- name the \
+  central claim, the unifying idea, what the input is *about* one rung up from what it \
+  *is*. Title `httpx` + roof `Modern HTTP Client` is correct; title `httpx` + roof \
+  `httpx` is wrong. EXCEPTION: codebase inputs where the repo/module name is the \
+  natural roof and no higher abstraction is available.
+- READABLE AT A GLANCE: every label should make sense to a reader who has not seen the \
+  input. If a pillar label is a numerical range, an abbreviation, a coined phrase, or \
+  requires recall of a specific passage to decode -- abstract one rung up.
+- NO INVENTED ADJECTIVES: do not modify a noun with an adjective unless that adjective \
+  appears in the input or is directly entailed. "Resilient", "Modern", "Robust", \
+  "Comprehensive", "Strategic" are red flags -- if the input does not use them, drop them.
+- NO HALLUCINATED CONCEPTS: every label and every summary clause must trace back to \
+  language or ideas in the input. Do not extend the author's metaphors or coin new ones.
+- Plain language: when the input uses everyday words, prefer everyday words in the labels. \
+  Reach for jargon only if the input itself does.
+- Length: target <= 16 characters per label. Concise noun phrases. Summaries are one sentence.
+
+PORTICO:
+- MECE: pillars must NOT overlap; together they must cover the load-bearing parts.
+- Same abstraction level: roof, each pillar, and base operate at one consistent level.
+- Load-bearing test: if you remove a pillar, the input's central purpose collapses.
+- Pillars are not steps: if the input has temporal/sequential structure (recipes, \
+  walkthroughs, ordered instructions), the portico is the wrong metaphor -- set \
+  fit_quality to "stretched" or worse rather than forcing steps into pillars.
+- Pillar-base separation: pillars and base must not overlap. A core ingredient of the input \
+  belongs in the base, not also as a pillar.
+- Pillar count: 2-9 allowed; STRONGLY PREFER 3-5 (Minto's Rule of 3, working memory).
+
+FIT (push back when the metaphor does not earn its keep):
+- "good" -- the metaphor lands cleanly.
+- "stretched" -- the metaphor is forced but still informative.
+- "forced" -- you had to invent structure that is not really there.
+- "not_applicable" -- nothing to decompose. Use for: gibberish, random words, flat lists \
+  with no organizing principle, single sentences with no internal structure, very short \
+  conventional inputs (greetings, idioms), or any content that lacks the kind of \
+  structural decomposition the portico models.
+- POETRY ALWAYS REFUSES: lyric and narrative poems do not admit portico decomposition. \
+  Poems work through image, rhythm, and meaning-by-accumulation -- they have no \
+  load-bearing pillars in the architectural sense. Set fit_quality to "not_applicable" \
+  for any poem and explain briefly in notes_on_fit.
+- FLAT LISTS REFUSE: simple lists (shopping lists, word lists, enumerations) lack the \
+  structural decomposition the portico models. Set fit_quality to "not_applicable" rather \
+  than inventing categorical pillars.
+- When torn between "forced" and "not_applicable", choose "not_applicable" and explain \
+  briefly in notes_on_fit. Refusing is a feature; the portico is not for everything.
+
+Emit ONLY the JSON object. No markdown fences. No commentary. No preamble.
+
+Input to analyze:
+
+{input}
+"""
+
+RETRY_FEEDBACK_HEADER = """\
+Your previous response could not be parsed: {error}
+
+Re-emit the JSON object correctly. Output ONLY the JSON object, no fences, no prose.
+Schema and input below remain the same.
+
+"""
+
+_FENCE_RE = re.compile(r"^```(?:json)?\s*(.*?)\s*```\s*$", re.DOTALL)
+
+
+class AnalyzerError(Exception):
+    """Base for analyzer failures."""
+
+
+class F4MalformedJSON(AnalyzerError):
+    """LLM produced unparseable / schema-invalid JSON after the retry budget (F4)."""
+
+
+@dataclass
+class AnalyzeResult:
+    data: PorticoJSON
+    raw_response: str
+    attempts: int
+
+
+def build_prompt(text: str) -> str:
+    return PROMPT_TEMPLATE.replace("{input}", text)
+
+
+def build_retry_prompt(base_prompt: str, error: str) -> str:
+    header = RETRY_FEEDBACK_HEADER.format(error=error)
+    return header + base_prompt
+
+
+def _strip_fence(s: str) -> str:
+    s = s.strip()
+    m = _FENCE_RE.match(s)
+    if m:
+        return m.group(1).strip()
+    return s
+
+
+def _parse_and_validate(raw: str) -> PorticoJSON:
+    cleaned = _strip_fence(raw)
+    data = json.loads(cleaned)
+    return PorticoJSON.model_validate(data)
+
+
+def analyze(
+    text: str,
+    *,
+    provider: LLMProvider,
+    model: str = DEFAULT_MODEL,
+    max_retries: int = 2,
+) -> AnalyzeResult:
+    """Send `text` to the LLM, parse + validate JSON, retry on malformed output.
+
+    Raises F4MalformedJSON after `max_retries` retries (so up to 1 + max_retries calls).
+    Provider-side errors (auth, transport) propagate unchanged from the provider.
+    """
+    base_prompt = build_prompt(text)
+    prompt = base_prompt
+    last_error: Exception | None = None
+    last_raw = ""
+
+    for attempt in range(max_retries + 1):
+        last_raw = provider.generate(prompt, model=model)
+        try:
+            data = _parse_and_validate(last_raw)
+            return AnalyzeResult(data=data, raw_response=last_raw, attempts=attempt + 1)
+        except (json.JSONDecodeError, ValidationError) as e:
+            last_error = e
+            prompt = build_retry_prompt(base_prompt, str(e))
+
+    raise F4MalformedJSON(
+        f"LLM returned unusable output after {max_retries + 1} attempts: {last_error}"
+    )

portico/cache.py

@@ -0,0 +1,46 @@
+"""Content-hashed cache for analyzer outputs.
+
+The cache is keyed on (text, provider, model) -- the same input through the
+same model returns the same JSON. Per the failure taxonomy, F3 refusals are
+cached (the input genuinely doesn't fit); F1/F2/F4 failures are not (re-run
+may succeed). Caching policy is enforced by the caller, not this module.
+"""
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from portico.schema import PorticoJSON
+
+DEFAULT_CACHE_DIR = Path.home() / ".cache" / "portico"
+
+
+def cache_key(text: str, *, provider: str, model: str) -> str:
+    payload = f"{provider}|{model}|{text}".encode()
+    return hashlib.sha256(payload).hexdigest()
+
+
+@dataclass
+class Cache:
+    root: Path = DEFAULT_CACHE_DIR
+
+    def _path(self, key: str) -> Path:
+        return self.root / f"{key}.json"
+
+    def get(self, key: str) -> PorticoJSON | None:
+        path = self._path(key)
+        if not path.exists():
+            return None
+        try:
+            return PorticoJSON.model_validate_json(path.read_text())
+        except Exception:
+            # Corrupt cache entry: drop it and miss.
+            path.unlink(missing_ok=True)
+            return None
+
+    def put(self, key: str, data: PorticoJSON) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._path(key).write_text(data.model_dump_json(indent=2))
+
+    def invalidate(self, key: str) -> None:
+        self._path(key).unlink(missing_ok=True)

portico/cli.py

@@ -0,0 +1,346 @@
+"""portico CLI -- single entry point that wires the pipeline together.
+
+Loader -> Summarizer (if oversized) -> Cache check -> Analyzer -> Renderer.
+Failure classes route to exit codes per the spec failure taxonomy.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from portico import __version__
+from portico.analyzer import F4MalformedJSON, analyze
+from portico.cache import Cache, cache_key
+from portico.config import (
+    get_anthropic_api_key,
+    get_default_model,
+    get_default_provider,
+)
+from portico.loaders.base import (
+    F1NetworkUnavailable,
+    F1NotFound,
+    F1RemoteInaccessible,
+    F2NotParseable,
+    F2TooLarge,
+    LoadedInput,
+)
+from portico.loaders.dir import load_dir
+from portico.loaders.file import load_file
+from portico.loaders.repo import load_repo
+from portico.loaders.text import load_stdin, load_text
+from portico.loaders.url import load_url
+from portico.providers.base import (
+    LLMProvider,
+    ProviderAuthError,
+    ProviderTransportError,
+)
+from portico.providers.claude import DEFAULT_MODEL, ClaudeProvider
+from portico.providers.gemini import GeminiProvider
+from portico.providers.openai import OpenAIProvider
+from portico.render import MAX_WIDTH, render
+from portico.render.apex import generate_apex
+from portico.render.color import ColorMode
+from portico.schema import FitQuality, PorticoJSON
+from portico.summarize import summarize
+
+REFUSAL_TEMPLATE = """\
+portico could not build a portico for this input.
+
+reason: {reason}
+
+input type detected: {theme}
+
+what you can try:
+  • run with --force to render anyway
+  • narrow the input and try again
+  • verify the input is what you intended
+"""
+
+
+# --- Exit codes ---
+EXIT_OK = 0
+EXIT_F1_NOT_FOUND = 2
+EXIT_F1_REMOTE = 3
+EXIT_F1_NETWORK = 4
+EXIT_F2_NOT_PARSEABLE = 5
+EXIT_F2_TOO_LARGE = 6
+EXIT_F4_MALFORMED = 7
+EXIT_F4_TRANSPORT = 8
+EXIT_F4_AUTH = 9
+
+
+@dataclass
+class Args:
+    input_value: str | None
+    input_type: str | None
+    style: str
+    color: ColorMode
+    verbose: bool
+    width: int
+    json_out: bool
+    provider: str
+    model: str
+    no_cache: bool
+    diagnose: bool
+    force: bool
+    strict: bool
+    reapex: bool
+    reapex_seed: int | None
+
+
+def make_provider(name: str) -> LLMProvider:
+    if name == "claude":
+        return ClaudeProvider(api_key=get_anthropic_api_key())
+    if name == "openai":
+        return OpenAIProvider()
+    if name == "gemini":
+        return GeminiProvider()
+    raise ValueError(f"unknown provider: {name}")
+
+
+# Bare filenames like `essay.md` look like file paths even without a slash.
+# Listing common extensions stops the heuristic from misreading "Trust scales..."
+# (period + word) as a file path.
+_FILE_EXTENSIONS = frozenset(
+    {
+        ".txt", ".md", ".rst", ".log", ".csv", ".tsv", ".json", ".yaml", ".yml",
+        ".toml", ".ini", ".conf", ".xml", ".html", ".htm", ".css", ".js", ".ts",
+        ".tsx", ".jsx", ".py", ".rb", ".go", ".rs", ".java", ".c", ".h", ".cpp",
+        ".hpp", ".cs", ".php", ".lua", ".sh", ".bash", ".zsh", ".sql", ".lock",
+    }
+)
+
+
+def _looks_like_path(value: str) -> bool:
+    if "/" in value or "\\" in value:
+        return True
+    if " " in value or "\n" in value:
+        return False
+    suffix = Path(value).suffix.lower()
+    return suffix in _FILE_EXTENSIONS
+
+
+def detect_input_type(value: str) -> str:
+    if value.startswith(("http://", "https://")):
+        return "url"
+    p = Path(value)
+    if p.exists():
+        return "dir" if p.is_dir() else "file"
+    if _looks_like_path(value):
+        # Path-shaped but missing -- let the file loader surface the F1 instead
+        # of silently treating the string as raw text.
+        return "file"
+    return "text"
+
+
+def load(value: str | None, *, input_type: str | None) -> LoadedInput:
+    if value is None:
+        if sys.stdin.isatty():
+            raise F2NotParseable(
+                "no input provided. Pass a path, URL, raw text, or pipe via stdin "
+                "(e.g. `echo 'hello' | portico -`). See `portico --help`."
+            )
+        return load_stdin()
+    if value == "-":
+        return load_stdin()
+    t = input_type or detect_input_type(value)
+    if t == "url":
+        return load_url(value)
+    if t == "file":
+        return load_file(value)
+    if t == "dir":
+        return load_dir(value)
+    if t == "repo":
+        return load_repo(value)
+    return load_text(value)
+
+
+def resolve_width(arg_width: int | None) -> int:
+    if arg_width is not None:
+        return arg_width
+    return min(shutil.get_terminal_size((MAX_WIDTH, 24)).columns, MAX_WIDTH)
+
+
+def render_refusal(data: PorticoJSON) -> str:
+    return REFUSAL_TEMPLATE.format(reason=data.notes_on_fit, theme=data.theme)
+
+
+def render_diagnostics(
+    loaded: LoadedInput, data: PorticoJSON, *, model: str, provider_name: str
+) -> str:
+    return (
+        f"input:        {loaded.source}\n"
+        f"type:         {loaded.input_type}\n"
+        f"chars:        {loaded.metadata.get('chars', len(loaded.text))}\n"
+        f"summarized:   {loaded.metadata.get('summarized', False)}\n"
+        f"provider:     {provider_name}\n"
+        f"model:        {model}\n"
+        f"fit_quality:  {data.fit_quality.value}\n"
+        f"notes_on_fit: {data.notes_on_fit}\n"
+    )
+
+
+def run(args: Args, *, provider: LLMProvider | None = None) -> int:
+    """The pipeline. `provider` injection is for tests."""
+    try:
+        loaded = load(args.input_value, input_type=args.input_type)
+    except F1NotFound as e:
+        print(f"portico: {e}", file=sys.stderr)
+        return EXIT_F1_NOT_FOUND
+    except F1RemoteInaccessible as e:
+        print(f"portico: {e}", file=sys.stderr)
+        return EXIT_F1_REMOTE
+    except F1NetworkUnavailable as e:
+        print(f"portico: {e}", file=sys.stderr)
+        return EXIT_F1_NETWORK
+    except F2NotParseable as e:
+        print(f"portico: {e}", file=sys.stderr)
+        return EXIT_F2_NOT_PARSEABLE
+
+    prov = provider or make_provider(args.provider)
+
+    try:
+        loaded = summarize(loaded, provider=prov, model=args.model)
+    except F2TooLarge as e:
+        print(f"portico: {e}", file=sys.stderr)
+        return EXIT_F2_TOO_LARGE
+    except ProviderAuthError as e:
+        print(f"portico: {e}", file=sys.stderr)
+        return EXIT_F4_AUTH
+    except ProviderTransportError as e:
+        print(f"portico: {e}", file=sys.stderr)
+        return EXIT_F4_TRANSPORT
+
+    cache = Cache()
+    key = cache_key(loaded.text, provider=args.provider, model=args.model)
+    data: PorticoJSON | None = None
+    if not args.no_cache:
+        data = cache.get(key)
+
+    if data is None:
+        try:
+            result = analyze(loaded.text, provider=prov, model=args.model)
+        except F4MalformedJSON as e:
+            print(f"portico: {e}", file=sys.stderr)
+            return EXIT_F4_MALFORMED
+        except ProviderAuthError as e:
+            print(f"portico: {e}", file=sys.stderr)
+            return EXIT_F4_AUTH
+        except ProviderTransportError as e:
+            print(f"portico: {e}", file=sys.stderr)
+            return EXIT_F4_TRANSPORT
+        data = result.data
+        if not args.no_cache:
+            cache.put(key, data)
+
+    if args.diagnose:
+        print(render_diagnostics(loaded, data, model=args.model, provider_name=args.provider))
+        return EXIT_OK
+
+    if args.json_out:
+        print(json.dumps(data.model_dump(mode="json"), indent=2))
+        return EXIT_OK
+
+    # F3 routing -- abstain when fit_quality demands it.
+    fq = data.fit_quality
+    if fq == FitQuality.NOT_APPLICABLE:
+        print(render_refusal(data))
+        return EXIT_OK
+    if fq == FitQuality.FORCED and not args.force:
+        print(render_refusal(data))
+        return EXIT_OK
+    if fq == FitQuality.STRETCHED and args.strict:
+        print(render_refusal(data))
+        return EXIT_OK
+
+    apex_override: tuple[str, str] | None = None
+    apex_seed_label: str | None = None
+    if args.reapex:
+        finial, keystone, used_seed = generate_apex(args.reapex_seed)
+        apex_override = (finial, keystone)
+        apex_seed_label = f"apex seed: {used_seed}"
+
+    print(
+        render(
+            data,
+            width=args.width,
+            color=args.color,
+            verbose=args.verbose,
+            apex_override=apex_override,
+            apex_seed_label=apex_seed_label,
+        ),
+        end="",
+    )
+    return EXIT_OK
+
+
+def parse_args(argv: list[str] | None = None) -> Args:
+    parser = argparse.ArgumentParser(prog="portico", description="Render any input as a portico.")
+    parser.add_argument("input", nargs="?", help="Path, URL, raw text, or '-' for stdin.")
+    parser.add_argument("--type", dest="input_type", choices=["text", "file", "dir", "url", "repo"])
+    parser.add_argument("--style", default="default")
+    parser.add_argument(
+        "--color",
+        choices=[c.value for c in ColorMode],
+        default=ColorMode.NEVER.value,
+    )
+    parser.add_argument("--verbose", "-v", action="store_true")
+    parser.add_argument("--width", type=int, default=None)
+    parser.add_argument("--json", dest="json_out", action="store_true")
+    parser.add_argument(
+        "--provider",
+        choices=["claude", "openai", "gemini"],
+        default=get_default_provider(),
+    )
+    parser.add_argument("--model", default=get_default_model() or DEFAULT_MODEL)
+    parser.add_argument("--no-cache", action="store_true")
+    parser.add_argument("--diagnose", action="store_true")
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--strict", action="store_true")
+    parser.add_argument(
+        "--reapex",
+        nargs="?",
+        const="__random__",
+        default=None,
+        help="Roll a random symmetric apex ornament. Pass --reapex=SEED to pin one.",
+    )
+    parser.add_argument("--version", action="version", version=f"portico {__version__}")
+    parsed = parser.parse_args(argv)
+
+    reapex = parsed.reapex is not None
+    reapex_seed: int | None = None
+    if reapex and parsed.reapex != "__random__":
+        try:
+            reapex_seed = int(parsed.reapex)
+        except ValueError:
+            parser.error(
+                f"--reapex value must be an integer seed, got {parsed.reapex!r}"
+            )
+
+    return Args(
+        input_value=parsed.input,
+        input_type=parsed.input_type,
+        style=parsed.style,
+        color=ColorMode(parsed.color),
+        verbose=parsed.verbose,
+        width=resolve_width(parsed.width),
+        json_out=parsed.json_out,
+        provider=parsed.provider,
+        model=parsed.model,
+        no_cache=parsed.no_cache,
+        diagnose=parsed.diagnose,
+        force=parsed.force,
+        strict=parsed.strict,
+        reapex=reapex,
+        reapex_seed=reapex_seed,
+    )
+
+
+def main() -> None:
+    args = parse_args()
+    sys.exit(run(args))

portico/config.py

@@ -0,0 +1,13 @@
+import os
+
+
+def get_anthropic_api_key() -> str | None:
+    return os.environ.get("ANTHROPIC_API_KEY")
+
+
+def get_default_provider() -> str:
+    return os.environ.get("ARQII_PROVIDER", "claude")
+
+
+def get_default_model() -> str | None:
+    return os.environ.get("ARQII_MODEL")

portico/loaders/base.py

@@ -0,0 +1,45 @@
+"""Loader contract and shared exception hierarchy.
+
+Every loader returns a `LoadedInput`. Failure cases map to F1/F2 categories
+per the spec failure taxonomy and surface as specific exception subclasses
+the CLI can route to exit codes 2-6.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class LoadedInput:
+    """Output of a loader -- raw text plus diagnostic metadata."""
+
+    text: str
+    source: str
+    input_type: str  # text | file | dir | url | repo
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class LoaderError(Exception):
+    """Base for all loader-side failures."""
+
+
+# F1: input access (no LLM call)
+class F1NotFound(LoaderError):
+    """Local input does not exist or is unreadable. Exit 2."""
+
+
+class F1RemoteInaccessible(LoaderError):
+    """Remote input returned 4xx/5xx or DNS failed. Exit 3."""
+
+
+class F1NetworkUnavailable(LoaderError):
+    """Network required but unavailable. Exit 4."""
+
+
+# F2: input parsing (no LLM call)
+class F2NotParseable(LoaderError):
+    """Input cannot be parsed as text (binary blob, encrypted, etc.). Exit 5."""
+
+
+class F2TooLarge(LoaderError):
+    """Input exceeds the hard size cap. Exit 6."""