portico-cli 0.1.0__tar.gz

portico_cli-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.3
+Name: portico-cli
+Version: 0.1.0
+Summary: Render any input as a portico – a three-layer ASCII visualization.
+Author: Tomás Ravalli
+Author-email: Tomás Ravalli <tomravalli@gmail.com>
+Requires-Dist: anthropic>=0.100.0
+Requires-Dist: openai>=2.36.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: trafilatura>=2.0.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# portico
+
+Render any input -- text, code, URL, repo -- as a **portico**: a three-layer ASCII visualization (`roof` / `pillars` / `base`).
+
+Always lowercase. The brand mark is `_ii^`.
+
+## Status
+
+Phase 0 (bootstrap) complete. The package skeleton compiles; no functionality is wired up yet. See the phased roadmap for what lands when.
+
+## Develop
+
+```bash
+uv sync                         # install dev deps
+uv run ruff check .             # lint
+uv run pyright                  # type-check
+uv run pytest                   # mocked tests; smoke eval auto-skips
+```
+
+The smoke eval (10 live Claude calls + rendered porticoes in `tests/eval/smoke/report/`) needs `ANTHROPIC_API_KEY`. With the key in 1Password CLI, run via:
+
+```bash
+op run --env-file=.env -- arch -arm64 uv run pytest
+```
+
+The `arch -arm64` is required because the 1Password CLI is x86_64 and would otherwise force a Rosetta child.

portico_cli-0.1.0/README.md

@@ -0,0 +1,26 @@
+# portico
+
+Render any input -- text, code, URL, repo -- as a **portico**: a three-layer ASCII visualization (`roof` / `pillars` / `base`).
+
+Always lowercase. The brand mark is `_ii^`.
+
+## Status
+
+Phase 0 (bootstrap) complete. The package skeleton compiles; no functionality is wired up yet. See the phased roadmap for what lands when.
+
+## Develop
+
+```bash
+uv sync                         # install dev deps
+uv run ruff check .             # lint
+uv run pyright                  # type-check
+uv run pytest                   # mocked tests; smoke eval auto-skips
+```
+
+The smoke eval (10 live Claude calls + rendered porticoes in `tests/eval/smoke/report/`) needs `ANTHROPIC_API_KEY`. With the key in 1Password CLI, run via:
+
+```bash
+op run --env-file=.env -- arch -arm64 uv run pytest
+```
+
+The `arch -arm64` is required because the 1Password CLI is x86_64 and would otherwise force a Rosetta child.

portico_cli-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "portico-cli"
+version = "0.1.0"
+description = "Render any input as a portico – a three-layer ASCII visualization."
+readme = "README.md"
+authors = [
+    { name = "Tomás Ravalli", email = "tomravalli@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "anthropic>=0.100.0",
+    "openai>=2.36.0",
+    "pydantic>=2.13.4",
+    "trafilatura>=2.0.0",
+]
+
+[project.scripts]
+portico = "portico.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "portico"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.7.0",
+    "pyright>=1.1.380",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+reportMissingImports = "error"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: tests that hit a real LLM provider or network (deselect with '-m \"not live\"')",
+]

portico_cli-0.1.0/src/portico/__init__.py

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

portico_cli-0.1.0/src/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_cli-0.1.0/src/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)