akta-pro-cli 0.3.0__py3-none-any.whl

akta_pro_cli/commands/config.py

@@ -0,0 +1,54 @@
+"""`akta-pro config` — view and change stored settings without re-entering the key."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from akta_pro_cli.client import DEFAULT_BASE_URL
+from akta_pro_cli.config import credentials_path, load_credentials, save_credentials
+from akta_pro_cli.console import err, out
+from akta_pro_cli.runtime import EXIT_BAD_INPUT
+
+config_app = typer.Typer(no_args_is_help=True, help="View or change stored settings (offline).")
+
+
+def _mask(key: str | None) -> str:
+    if not key:
+        return "(not set)"
+    return f"{key[:5]}…{key[-4:]}" if len(key) > 12 else "…"
+
+
+@config_app.command("show")
+def show() -> None:
+    """Show the stored credentials/config (offline; API key masked)."""
+    creds = load_credentials()
+    base = creds.get("base_url")
+    out.print(f"config file : {credentials_path()}")
+    out.print(f"api key     : {_mask(creds.get('api_key'))}")
+    out.print(f"base url    : {base or f'(not set → default {DEFAULT_BASE_URL})'}")
+
+
+@config_app.command("base-url")
+def base_url(
+    url: Annotated[str | None, typer.Argument(help="New base URL. Omit and pass --reset to restore the default.")] = None,
+    reset: Annotated[bool, typer.Option("--reset", help="Reset to the default (api.akta.pro).")] = False,
+) -> None:
+    """Change or reset the stored base URL, keeping the stored API key."""
+    creds = load_credentials()
+    if reset:
+        creds.pop("base_url", None)
+        save_credentials(creds)
+        out.print(f"[green]✓[/] base url reset → default ({DEFAULT_BASE_URL})")
+        return
+    if not url:
+        err.print("[red]Provide a URL, or pass --reset.[/]")
+        raise typer.Exit(code=EXIT_BAD_INPUT)
+    creds["base_url"] = url
+    save_credentials(creds)
+    out.print(f"[green]✓[/] base url set → {url}")
+
+
+def register(app: typer.Typer) -> None:
+    app.add_typer(config_app, name="config")

akta_pro_cli/commands/industry.py

@@ -0,0 +1,46 @@
+"""`akta-pro industry` — resolve free-text industries to akta.pro codes."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.table import Table
+
+from akta_pro_cli.options import JsonOpt, OutOpt
+from akta_pro_cli.runtime import emit, fetch
+
+app = typer.Typer(no_args_is_help=True, help="Industry search.")
+
+
+def _industry_table(result: object) -> Table | None:
+    rows = result.get("data") if isinstance(result, dict) else None
+    if not rows:
+        return None
+    table = Table(title="Industry matches")
+    table.add_column("Code")
+    table.add_column("Industry", overflow="fold")
+    table.add_column("Similarity", justify="right")
+    for row in rows:
+        sim = row.get("similarity")
+        table.add_row(
+            str(row.get("code", "")),
+            str(row.get("industry_name", "")),
+            f"{sim:.3f}" if isinstance(sim, (int, float)) else str(sim or ""),
+        )
+    return table
+
+
+@app.command("search")
+def search(
+    ctx: typer.Context,
+    query: Annotated[str, typer.Argument(help="Free-text industry or topic, e.g. 'warehouse automation'.")],
+    json_out: JsonOpt = False,
+    output: OutOpt = None,
+) -> None:
+    """Resolve a free-text industry to akta.pro industry codes (free).
+
+    Use the returned `code` values as `--industry` in `akta-pro news`.
+    """
+    result = fetch(ctx.obj, "/industry/search", {"query": query})
+    emit(ctx.obj, result, json_out=json_out, output=output, renderer=_industry_table)

akta_pro_cli/commands/news.py

@@ -0,0 +1,232 @@
+"""`akta-pro news` — signals (list), detail (full bodies), and the type taxonomy."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated
+
+import typer
+from rich.console import Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from akta_pro_cli.console import err
+from akta_pro_cli.news_tags import NEWS_CATEGORIES, NEWS_TAGS
+from akta_pro_cli.options import JsonOpt, OutOpt
+from akta_pro_cli.runtime import EXIT_BAD_INPUT, emit, fetch
+
+app = typer.Typer(no_args_is_help=True, help="News signals, article detail, and the type taxonomy.")
+
+# Compact list fields (mirrors the MCP's news_signals shaping); `id` feeds `detail`.
+_STRIPPED_FIELDS = ("id", "title", "ai_summary", "url", "published_date", "publisher")
+
+
+class Sentiment(str, Enum):
+    positive = "positive"
+    negative = "negative"
+    neutral = "neutral"
+    all = "all"
+
+
+class NewsScore(str, Enum):
+    high = "High"
+    medium = "Medium"
+    low = "Low"
+    all = "all"
+
+
+def _shape(article: dict, *, full: bool) -> dict:
+    if full:
+        return {k: v for k, v in article.items() if k != "full_text"}
+    return {k: article.get(k) for k in _STRIPPED_FIELDS}
+
+
+def _csv(values: list[str] | None) -> str | None:
+    """Join repeatable-option values into the comma-separated string the API
+    expects (or None when nothing was passed)."""
+    if not values:
+        return None
+    return ",".join(v.strip() for v in values if v.strip()) or None
+
+
+def _signals_table(result: object) -> Table | None:
+    rows = result.get("data") if isinstance(result, dict) else None
+    if not rows:
+        return None
+    table = Table(title=f"News ({result.get('count', '?')} of {result.get('total', '?')})")
+    for col in ("Id", "Date", "Publisher", "Title", "AI summary", "URL"):
+        table.add_column(col, overflow="fold")
+    for row in rows:
+        table.add_row(
+            str(row.get("id", "") or ""),
+            str(row.get("published_date", "") or ""),
+            str(row.get("publisher", "") or ""),
+            str(row.get("title", "") or ""),
+            str(row.get("ai_summary", "") or ""),
+            str(row.get("url", "") or ""),
+        )
+    return table
+
+
+@app.command("signals")
+def signals(
+    ctx: typer.Context,
+    company: Annotated[str | None, typer.Option("--company", help="Company website or akta.pro UUID.")] = None,
+    industry: Annotated[str | None, typer.Option("--industry", help="Comma-separated industry codes (from `akta-pro industry search`) — preferred for sector/market topics.")] = None,
+    query: Annotated[str | None, typer.Option("--query", help="Open-ended topic, e.g. 'crude oil prices' (last resort; prefer --company/--industry).")] = None,
+    title: Annotated[str | None, typer.Option("--title", help="Search by text in the article title.")] = None,
+    start_date: Annotated[str | None, typer.Option("--start-date", help="Start of range, YYYY-MM-DD. Non-enterprise limited to ~6 months back.")] = None,
+    end_date: Annotated[str | None, typer.Option("--end-date", help="End of range, YYYY-MM-DD. Default today.")] = None,
+    type_codes: Annotated[list[str] | None, typer.Option("--type-code", "-t", help="News-type tag code(s) from `akta-pro news types`, e.g. SD01, CM03 (repeatable).")] = None,
+    sentiment: Annotated[Sentiment, typer.Option("--sentiment", help="Filter by article sentiment.")] = Sentiment.all,
+    news_score: Annotated[NewsScore, typer.Option("--news-score", help="Filter by relevance/quality tier.")] = NewsScore.all,
+    countries: Annotated[list[str] | None, typer.Option("--country", help="Filter by the event's country — ISO codes, e.g. USA, GBR (repeatable).")] = None,
+    blacklisted: Annotated[list[str] | None, typer.Option("--blacklist", help="Publisher domain(s) to exclude, e.g. example.com (repeatable).")] = None,
+    entity_person: Annotated[list[str] | None, typer.Option("--entity-person", help="Only articles mentioning these people, by name (repeatable).")] = None,
+    entity_location: Annotated[list[str] | None, typer.Option("--entity-location", help="Only articles mentioning these locations (repeatable).")] = None,
+    entity_product: Annotated[list[str] | None, typer.Option("--entity-product", help="Only articles mentioning these product names (repeatable).")] = None,
+    entity_event: Annotated[list[str] | None, typer.Option("--entity-event", help="Only articles mentioning these event names (repeatable).")] = None,
+    naics_codes: Annotated[list[str] | None, typer.Option("--naics", help="Filter by NAICS industry classification code(s) (repeatable).")] = None,
+    sic_codes: Annotated[list[str] | None, typer.Option("--sic", help="Filter by SIC industry classification code(s) (repeatable).")] = None,
+    iptc_codes: Annotated[list[str] | None, typer.Option("--iptc", help="Filter by IPTC media topic code(s) (repeatable).")] = None,
+    iab_codes: Annotated[list[str] | None, typer.Option("--iab", help="Filter by IAB content taxonomy code(s) (repeatable).")] = None,
+    group_articles: Annotated[bool, typer.Option("--group-articles", help="Group near-duplicate articles from the same event.")] = False,
+    limit: Annotated[int, typer.Option("-n", "--limit", min=1, max=1000, help="Max articles (max 1000).")] = 10,
+    offset: Annotated[int, typer.Option("--offset", min=0, help="Pagination offset.")] = 0,
+    full: Annotated[bool, typer.Option("--full", help="Return all per-article fields (industries, types, entities, mentions) except body text.")] = False,
+    json_out: JsonOpt = False,
+    output: OutOpt = None,
+) -> None:
+    """List news signals. Typically anchor the search with one of
+    --company/--industry/--query/--title (all optional).
+
+    The list is compact and never includes article bodies; each result carries an
+    `id` — pass those to `akta-pro news detail` for full text. Cost: 0.1/call +
+    0.01/article. Filter by type with `-t` codes from `akta-pro news types`.
+    """
+    params = {
+        "company": company,
+        "industry": industry,
+        "query": query,
+        "title": title,
+        "start_date": start_date,
+        "end_date": end_date,
+        "sentiment_list": None if sentiment == Sentiment.all else sentiment.value,
+        "news_score_list": None if news_score == NewsScore.all else news_score.value,
+        "type_list": _csv(type_codes),
+        "countries": _csv(countries),
+        "blacklisted": _csv(blacklisted),
+        "entity_person_list": _csv(entity_person),
+        "entity_location_list": _csv(entity_location),
+        "entity_product_list": _csv(entity_product),
+        "entity_event_list": _csv(entity_event),
+        "naics_code_list": _csv(naics_codes),
+        "sic_code_list": _csv(sic_codes),
+        "iptc_code_list": _csv(iptc_codes),
+        "iab_code_list": _csv(iab_codes),
+        "group_articles": True if group_articles else None,
+        "limit": limit,
+        "offset": offset,
+        "full_text": False,  # list stays compact; bodies via `news detail`
+    }
+    resp = fetch(ctx.obj, "/news", params)
+    articles = (resp.get("data") if isinstance(resp, dict) else None) or []
+    shaped = [_shape(a, full=full) for a in articles]
+    result = {
+        "total": resp.get("total") if isinstance(resp, dict) else None,
+        "count": len(shaped),
+        "credits_consumed": resp.get("credits_consumed") if isinstance(resp, dict) else None,
+        "data": shaped,
+    }
+    emit(ctx.obj, result, json_out=json_out, output=output, renderer=_signals_table)
+
+
+def _detail_view(result: object) -> Group | None:
+    """Readable reader view for `news detail`: title + meta + article body.
+
+    Puts `full_text` front and centre (the whole point of `detail`); when the
+    body is empty, falls back to the AI summary and points at the source URL so
+    the output is still useful. Use --json for the full enrichment payload.
+    """
+    rows = result.get("data") if isinstance(result, dict) else None
+    if not rows:
+        return None
+    panels = []
+    for a in rows:
+        meta_bits = [str(a.get(k)) for k in ("publisher", "published_date") if a.get(k)]
+        meta = "  ·  ".join(meta_bits)
+        url = a.get("url") or ""
+        body = (a.get("full_text") or "").strip()
+        if body:
+            content = Text(body)
+        else:
+            summary = (a.get("ai_summary") or "").strip()
+            content = Text()
+            content.append("Full article text is unavailable for this article.\n", style="yellow")
+            if summary:
+                content.append("\nAI summary:\n", style="bold")
+                content.append(summary + "\n")
+            if url:
+                content.append("\nRead the source: ", style="dim")
+                content.append(url, style="cyan underline")
+        header = Text(str(a.get("title") or f"#{a.get('id')}"), style="bold")
+        if meta:
+            header.append(f"\n{meta}", style="dim")
+        if body and url:
+            header.append(f"\n{url}", style="cyan")
+        panels.append(Panel(content, title=header, title_align="left",
+                            subtitle=f"id {a.get('id')}", subtitle_align="right"))
+    return Group(*panels)
+
+
+@app.command("detail")
+def detail(
+    ctx: typer.Context,
+    news_ids: Annotated[list[int], typer.Argument(help="News id(s) from `akta-pro news signals` (max 10).")],
+    json_out: JsonOpt = False,
+    output: OutOpt = None,
+) -> None:
+    """Fetch full article bodies for specific news id(s). Cost: 0.1/call + 0.01/article.
+
+    In a terminal this renders a readable reader view — the article `full_text`
+    up top, falling back to the AI summary + source URL when a body isn't
+    available. Pass --json for the complete enrichment payload.
+    """
+    if not news_ids:
+        err.print("[red]Provide at least one news id[/] (from `akta-pro news signals`).")
+        raise typer.Exit(code=EXIT_BAD_INPUT)
+    ids_csv = ",".join(str(i) for i in news_ids[:10])
+    result = fetch(ctx.obj, "/news/by-id/", {"news_ids": ids_csv})
+    emit(ctx.obj, result, json_out=json_out, output=output, renderer=_detail_view)
+
+
+def _types_table(_: object) -> Table:
+    table = Table(title=f"News types ({len(NEWS_TAGS)} tags)")
+    table.add_column("Code", style="bold cyan")
+    table.add_column("Category")
+    table.add_column("Type", overflow="fold")
+    for code, name in NEWS_TAGS:
+        table.add_row(code, NEWS_CATEGORIES.get(code[:2], ""), name)
+    return table
+
+
+@app.command("types")
+def types(
+    ctx: typer.Context,
+    json_out: JsonOpt = False,
+    output: OutOpt = None,
+) -> None:
+    """List the news-type tag codes for `--type-code` filtering (free, offline)."""
+    categories = []
+    for prefix, cat_name in NEWS_CATEGORIES.items():
+        tags = [{"code": c, "name": n} for c, n in NEWS_TAGS if c.startswith(prefix)]
+        if tags:
+            categories.append({"category": cat_name, "codes": tags})
+    result = {
+        "count": len(NEWS_TAGS),
+        "usage": "Pass matching code(s) to `akta-pro news signals --type-code CODE`.",
+        "categories": categories,
+    }
+    # No network/credits — flat table in a TTY, structured JSON otherwise.
+    emit(ctx.obj, result, json_out=json_out, output=output, renderer=_types_table)

akta_pro_cli/commands/update.py

@@ -0,0 +1,64 @@
+"""`akta-pro update` — check for a newer release and update the CLI in place."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Annotated
+
+import typer
+
+from akta_pro_cli import __version__
+from akta_pro_cli import update as _u
+from akta_pro_cli.console import err, out
+from akta_pro_cli.runtime import EXIT_API
+
+
+def update(
+    check: Annotated[bool, typer.Option("--check", help="Only report whether an update exists; don't install.")] = False,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip the confirmation prompt and update.")] = False,
+) -> None:
+    """Check for a newer release and, if found, reinstall it via pipx.
+
+    Discovers the latest version from PyPI and upgrades the installed package.
+    """
+    current = __version__
+    latest = _u.cached_latest(timeout=8.0, force=True)
+    if latest is None:
+        err.print(
+            f"[yellow]Couldn't reach PyPI to check for updates[/] (network?). "
+            f"You're on v{current}."
+        )
+        err.print(f"See {_u.PROJECT_URL}, or upgrade manually.")
+        raise typer.Exit(code=EXIT_API)
+
+    if not _u.is_newer(latest, current):
+        out.print(f"[green]✓ up to date[/] — v{current} is the latest.")
+        return
+
+    cmd = ["pipx", "upgrade", _u.PACKAGE]
+    out.print(f"Update available: [bold]v{current}[/] → [bold green]v{latest}[/]")
+
+    if check:
+        out.print("Run to update:  " + " ".join(cmd))
+        return
+
+    if shutil.which("pipx") is None:
+        err.print("[yellow]pipx not found on PATH.[/] Update manually:  " + " ".join(cmd))
+        raise typer.Exit(code=EXIT_API)
+
+    if not yes and not typer.confirm(f"Update to v{latest} now?", default=True):
+        out.print("Skipped. Run when ready:  " + " ".join(cmd))
+        return
+
+    err.print(f"Updating to v{latest} via pipx…")
+    rc = subprocess.run(cmd).returncode
+    if rc == 0:
+        out.print(f"[green]✓ updated to v{latest}[/]")
+    else:
+        err.print(f"[red]pipx exited {rc}.[/] Try manually:  " + " ".join(cmd))
+        raise typer.Exit(code=EXIT_API)
+
+
+def register(app: typer.Typer) -> None:
+    app.command("update")(update)

akta_pro_cli/config.py

@@ -0,0 +1,71 @@
+"""Local credential + config storage for the akta.pro CLI.
+
+Credentials live in a JSON file under the user's config dir
+(`$XDG_CONFIG_HOME/akta-pro` or `~/.config/akta-pro` on Unix, `%APPDATA%\\akta-pro`
+on Windows), written 0600. Only the API key path is used in v1.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+
+APP_NAME = "akta-pro"
+
+
+def config_dir() -> Path:
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / APP_NAME
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / APP_NAME
+
+
+def credentials_path() -> Path:
+    return config_dir() / "credentials.json"
+
+
+def load_credentials() -> dict:
+    path = credentials_path()
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+        return data if isinstance(data, dict) else {}
+    except (ValueError, OSError):
+        return {}
+
+
+def save_credentials(data: dict) -> Path:
+    directory = config_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(directory, 0o700)
+    except OSError:
+        pass  # best-effort (e.g. Windows)
+    path = credentials_path()
+    path.write_text(json.dumps(data, indent=2))
+    try:
+        os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+    except OSError:
+        pass
+    return path
+
+
+def clear_credentials() -> bool:
+    """Delete the stored credentials file. Returns True if a file was removed."""
+    path = credentials_path()
+    if path.exists():
+        path.unlink()
+        return True
+    return False
+
+
+def stored_api_key() -> str | None:
+    return load_credentials().get("api_key")
+
+
+def stored_base_url() -> str | None:
+    return load_credentials().get("base_url")

akta_pro_cli/console.py

@@ -0,0 +1,10 @@
+"""Shared Rich consoles.
+
+`out` writes machine/primary output to stdout; `err` writes human status,
+credit lines, and errors to stderr — so `akta-pro ... --json | jq` stays clean.
+"""
+
+from rich.console import Console
+
+out = Console()
+err = Console(stderr=True)

akta_pro_cli/news_tags.py

@@ -0,0 +1,102 @@
+"""akta.pro news-type taxonomy — a static snapshot of the published `news-tags.csv`.
+
+Kept in the CLI so the package is fully independent of the MCP. The MCP has its
+own copy (`akta_mcp/tools/news_tags.py`); keep both in sync if the CSV changes:
+https://delightful-beach-02437b20f.7.azurestaticapps.net/news-tags.csv
+"""
+
+# Leaf-tag category prefixes → human category names.
+NEWS_CATEGORIES = {
+    "OT": "Others",
+    "SD": "Strategic Developments",
+    "CM": "Capital Markets & Transactions",
+    "LG": "Leadership & Governance",
+    "WT": "Workforce & Talent",
+    "FR": "Financial Results & Performance",
+    "RC": "Regulatory & Compliance",
+    "MM": "Macro & Market Environment",
+    "MD": "Market Dynamics",
+    "II": "Industry Disruption & Innovation",
+    "RK": "Risk & Crisis Events",
+}
+
+# (code, name) leaf tags. `news signals --type-code …` sends these as `type_list`.
+NEWS_TAGS = [
+    ("OT01", "Others"),
+    ("SD01", "Product Launches & Enhancements"),
+    ("SD02", "Partnerships & Alliances"),
+    ("SD03", "Geographic Expansion"),
+    ("SD04", "Operational Milestones"),
+    ("SD05", "Market Share & Positioning"),
+    ("SD06", "Digital Transformation"),
+    ("SD07", "Brand & Marketing Initiatives"),
+    ("SD08", "Research, Development & Innovation"),
+    ("SD09", "Sustainability & ESG"),
+    ("SD10", "Pricing & Commercial Strategy"),
+    ("SD11", "Awards, Rankings & Recognitions"),
+    ("CM01", "Equity Fund-Raising"),
+    ("CM02", "Debt Financing"),
+    ("CM03", "Mergers & Acquisitions"),
+    ("CM04", "Divestitures & Asset Sales"),
+    ("CM05", "IPOs & Follow-on Offerings"),
+    ("CM06", "SPAC Deals & De-SPACs"),
+    ("CM07", "Secondary Transactions"),
+    ("CM08", "Shareholder Returns (Buybacks & Dividends)"),
+    ("CM09", "Valuation Events"),
+    ("CM10", "Deal Flow & Volume Statistics"),
+    ("CM11", "Public-to-Private/Take-Private"),
+    ("CM12", "Daily Stock Market News"),
+    ("LG01", "C-Suite Appointments & Departures"),
+    ("LG02", "Board Composition & Changes"),
+    ("LG03", "Succession Planning"),
+    ("LG04", "Organisational Restructuring"),
+    ("LG05", "Executive Commentary & Interviews"),
+    ("LG06", "Conflicts of Interest & Related-Party Transactions"),
+    ("WT01", "Strategic Hiring"),
+    ("WT02", "Workforce Reductions"),
+    ("WT03", "Compensation & Benefits"),
+    ("WT04", "Culture & Workplace Practices"),
+    ("WT05", "Talent-Market Dynamics"),
+    ("FR01", "Earnings Releases"),
+    ("FR02", "Revenue & Growth Metrics"),
+    ("FR03", "Profitability & Margins"),
+    ("FR04", "Cash Flow & Capital Expenditure"),
+    ("FR05", "Guidance & Forecast Revisions"),
+    ("FR06", "Credit-Rating Actions"),
+    ("FR07", "Sector Performance Dashboards"),
+    ("RC01", "Regulatory Approvals & Certifications"),
+    ("RC02", "Policy & Legislative Changes"),
+    ("RC03", "Legal Proceedings & Litigation"),
+    ("RC04", "Compliance & Reporting Updates"),
+    ("RC05", "Intellectual Property"),
+    ("RC06", "Antitrust & Competition"),
+    ("RC07", "Data Privacy & Cybersecurity Regulation"),
+    ("RC08", "Tax & Accounting Rules"),
+    ("MM01", "Economic Indicators"),
+    ("MM02", "Monetary Policy"),
+    ("MM03", "Fiscal Policy"),
+    ("MM04", "Trade, Tariffs & Sanctions"),
+    ("MM05", "Consumer Behaviour & Spending"),
+    ("MM06", "Labor-Market Statistics"),
+    ("MM07", "Sector Outlook & Forecasts"),
+    ("MD01", "Market Indices Performance"),
+    ("MD02", "Institutional Flows & Positioning"),
+    ("MD03", "Sector Rotation"),
+    ("MD04", "Volatility & Risk Appetite"),
+    ("MD05", "FX & Commodity Pricing"),
+    ("MD06", "Liquidity Conditions"),
+    ("MD07", "Investor Sentiment"),
+    ("II01", "Emerging Technologies"),
+    ("II02", "Technology Adoption & Disruption"),
+    ("II03", "Business-Model Evolution"),
+    ("II04", "Competitive Threats"),
+    ("II05", "Market-Structure Changes"),
+    ("RK01", "Geopolitical Risk"),
+    ("RK02", "Public-Health Crises"),
+    ("RK03", "Natural Disasters"),
+    ("RK04", "Operational Disruptions"),
+    ("RK05", "Cybersecurity Incidents"),
+    ("RK06", "Reputational Damage"),
+    ("RK07", "Financial Distress & Restructuring"),
+    ("RK08", "Supply-Chain Disruptions"),
+]

akta_pro_cli/options.py

@@ -0,0 +1,21 @@
+"""Reusable Typer option/argument annotations shared across command modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+CompanyArg = Annotated[str, typer.Argument(help="Company website (e.g. 'canva.com') or akta.pro UUID.")]
+
+JsonOpt = Annotated[bool, typer.Option("--json", help="Emit raw JSON to stdout (clean for pipes).")]
+
+OutOpt = Annotated[
+    Path | None,
+    typer.Option("-o", "--output", help="Write the raw JSON/text payload to a file.", show_default=False),
+]
+
+LimitOpt = Annotated[int, typer.Option("-n", "--limit", help="Max items to return.")]
+
+OffsetOpt = Annotated[int, typer.Option("--offset", help="Pagination offset.")]