ceorater 0.1.0__tar.gz

ceorater-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: ceorater
+Version: 0.1.0
+Summary: CLI for CEORater — institutional-grade CEO performance analytics
+Author-email: Jon Maietta <support@ceorater.com>
+License: Proprietary
+Project-URL: Homepage, https://www.ceorater.com
+Project-URL: Documentation, https://www.ceorater.com/api-docs.html
+Project-URL: Support, https://www.ceorater.com/support.html
+Keywords: ceo,finance,investing,analytics,sec
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+
+# CEORater CLI
+
+Command-line interface for [CEORater](https://www.ceorater.com) — institutional-grade CEO performance analytics covering 500+ S&P 500 CEOs.
+
+## Install
+
+```bash
+pip install ceorater
+```
+
+## Setup
+
+Get your API key at [ceorater.com/api-docs.html](https://www.ceorater.com/api-docs.html), then:
+
+```bash
+ceorater configure
+```
+
+Or set the `CEORATER_API_KEY` environment variable.
+
+## Commands
+
+### Look up a CEO by ticker
+
+```bash
+ceorater lookup NVDA
+```
+
+```
+  NVIDIA (NVDA)
+  CEO: Jensen Huang  |  Founder: Yes  |  Tenure: 27.3 yrs
+  Sector: Technology  |  Industry: Semiconductors
+
+  Metric                  Value
+  CEORaterScore              99
+  AlphaScore                100
+  RevCAGR Score             100
+  CompScore                   A
+
+  TSR Multiple         589,250%
+  Avg Annual TSR        21,578%
+  TSR vs SPY           588,370%
+  Avg Annual vs SPY     21,546%
+
+  Compensation ($M)      $49.9M
+  Cost/1% TSR ($M)        $0.0M
+  Revenue CAGR            69.3%
+```
+
+### Search by company, CEO, sector, or industry
+
+```bash
+ceorater search "technology"
+```
+
+### List all CEOs (paginated)
+
+```bash
+ceorater list --limit 50
+```
+
+### Check data freshness
+
+```bash
+ceorater meta
+```
+
+### JSON output for agents and scripts
+
+Every data command supports `--json` for raw, machine-readable output:
+
+```bash
+ceorater lookup AAPL --json
+```
+
+```json
+{
+  "companyName": "Apple Inc.",
+  "ticker": "AAPL",
+  "ceoraterScore": 76.2,
+  "alphaScore": 93.9,
+  "compScore": "C",
+  ...
+}
+```
+
+## Metrics
+
+| Metric | Description |
+|--------|-------------|
+| CEORaterScore | Composite CEO effectiveness rating (0-100) |
+| AlphaScore | Market outperformance score (0-100) |
+| RevCAGR Score | Tenure-adjusted revenue growth percentile (0-100) |
+| CompScore | Compensation efficiency grade (A-F) |
+| TSR Multiple | Total Shareholder Return during tenure |
+| Cost/1% TSR | CEO compensation cost per 1% of average annual TSR |
+
+## Requirements
+
+- Python 3.9+
+- CEORater API subscription ($99/month) — [subscribe here](https://www.ceorater.com/api-docs.html)
+
+## License
+
+Proprietary. See [terms of service](https://www.ceorater.com/terms.html).

ceorater-0.1.0/README.md

@@ -0,0 +1,105 @@
+# CEORater CLI
+
+Command-line interface for [CEORater](https://www.ceorater.com) — institutional-grade CEO performance analytics covering 500+ S&P 500 CEOs.
+
+## Install
+
+```bash
+pip install ceorater
+```
+
+## Setup
+
+Get your API key at [ceorater.com/api-docs.html](https://www.ceorater.com/api-docs.html), then:
+
+```bash
+ceorater configure
+```
+
+Or set the `CEORATER_API_KEY` environment variable.
+
+## Commands
+
+### Look up a CEO by ticker
+
+```bash
+ceorater lookup NVDA
+```
+
+```
+  NVIDIA (NVDA)
+  CEO: Jensen Huang  |  Founder: Yes  |  Tenure: 27.3 yrs
+  Sector: Technology  |  Industry: Semiconductors
+
+  Metric                  Value
+  CEORaterScore              99
+  AlphaScore                100
+  RevCAGR Score             100
+  CompScore                   A
+
+  TSR Multiple         589,250%
+  Avg Annual TSR        21,578%
+  TSR vs SPY           588,370%
+  Avg Annual vs SPY     21,546%
+
+  Compensation ($M)      $49.9M
+  Cost/1% TSR ($M)        $0.0M
+  Revenue CAGR            69.3%
+```
+
+### Search by company, CEO, sector, or industry
+
+```bash
+ceorater search "technology"
+```
+
+### List all CEOs (paginated)
+
+```bash
+ceorater list --limit 50
+```
+
+### Check data freshness
+
+```bash
+ceorater meta
+```
+
+### JSON output for agents and scripts
+
+Every data command supports `--json` for raw, machine-readable output:
+
+```bash
+ceorater lookup AAPL --json
+```
+
+```json
+{
+  "companyName": "Apple Inc.",
+  "ticker": "AAPL",
+  "ceoraterScore": 76.2,
+  "alphaScore": 93.9,
+  "compScore": "C",
+  ...
+}
+```
+
+## Metrics
+
+| Metric | Description |
+|--------|-------------|
+| CEORaterScore | Composite CEO effectiveness rating (0-100) |
+| AlphaScore | Market outperformance score (0-100) |
+| RevCAGR Score | Tenure-adjusted revenue growth percentile (0-100) |
+| CompScore | Compensation efficiency grade (A-F) |
+| TSR Multiple | Total Shareholder Return during tenure |
+| Cost/1% TSR | CEO compensation cost per 1% of average annual TSR |
+
+## Requirements
+
+- Python 3.9+
+- CEORater API subscription ($99/month) — [subscribe here](https://www.ceorater.com/api-docs.html)
+
+## License
+
+Proprietary. See [terms of service](https://www.ceorater.com/terms.html).

ceorater-0.1.0/ceorater/__init__.py

@@ -0,0 +1,3 @@
+"""CEORater CLI — institutional-grade CEO performance analytics."""
+
+__version__ = "0.1.0"

ceorater-0.1.0/ceorater/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m ceorater`."""
+
+from ceorater.cli import main
+
+main()

ceorater-0.1.0/ceorater/cli.py

@@ -0,0 +1,262 @@
+"""CEORater CLI — command definitions."""
+
+import json
+import math
+import sys
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ceorater.client import CEORaterError, Client
+from ceorater.config import load_key, save_key
+
+console = Console()
+
+SCORE_FIELDS = [
+    ("ceoraterScore", "CEORaterScore", "0-100"),
+    ("alphaScore", "AlphaScore", "0-100"),
+    ("revenueCagrScore", "RevCAGR Score", "0-100"),
+    ("compScore", "CompScore", "A-F"),
+]
+
+PERF_FIELDS = [
+    ("tsrMultiple", "TSR Multiple"),
+    ("avgAnnualTsrRatio", "Avg Annual TSR"),
+    ("tsrVsSpyRatio", "TSR vs SPY"),
+    ("avgAnnualVsSpyRatio", "Avg Annual vs SPY"),
+]
+
+COMP_FIELDS = [
+    ("compensationMM", "Compensation ($M)"),
+    ("compPer1PctTsrMM", "Cost/1% TSR ($M)"),
+]
+
+
+def _get_client() -> Client:
+    key = load_key()
+    if not key:
+        console.print(
+            "[red]No API key configured.[/red] Run [bold]ceorater configure[/bold] first."
+        )
+        sys.exit(1)
+    return Client(key)
+
+
+def _handle_error(e: CEORaterError) -> None:
+    if e.status == 401:
+        console.print("[red]Unauthorized.[/red] Check your API key with [bold]ceorater configure[/bold].")
+    elif e.status == 403:
+        console.print(f"[red]Subscription required.[/red] {e}")
+    elif e.status == 404:
+        console.print(f"[yellow]Not found.[/yellow] {e}")
+    else:
+        console.print(f"[red]Error {e.status}:[/red] {e}")
+    sys.exit(1)
+
+
+def _fmt_pct(val) -> str:
+    if val is None:
+        return "-"
+    return f"{val * 100:,.0f}%"
+
+
+def _fmt_score(val) -> str:
+    if val is None:
+        return "-"
+    if isinstance(val, str):
+        return val
+    return str(math.floor(val + 0.5))
+
+
+def _fmt_money(val) -> str:
+    if val is None:
+        return "-"
+    return f"${val:,.1f}M"
+
+
+def _fmt_years(val) -> str:
+    if val is None:
+        return "-"
+    return f"{val:.1f} yrs"
+
+
+def _print_ceo_card(ceo: dict) -> None:
+    console.print()
+    console.print(f"  [bold]{ceo.get('companyName', '')}[/bold] ({ceo.get('ticker', '')})")
+    console.print(f"  CEO: {ceo.get('ceo', '')}  |  Founder: {'Yes' if ceo.get('founderCEO') else 'No'}  |  Tenure: {_fmt_years(ceo.get('tenureYears'))}")
+    console.print(f"  Sector: {ceo.get('sector', '')}  |  Industry: {ceo.get('industry', '')}")
+    console.print()
+
+    t = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    t.add_column("Metric")
+    t.add_column("Value", justify="right")
+
+    for key, label, _ in SCORE_FIELDS:
+        t.add_row(label, _fmt_score(ceo.get(key)))
+
+    t.add_row("", "")
+    for key, label in PERF_FIELDS:
+        t.add_row(label, _fmt_pct(ceo.get(key)))
+
+    t.add_row("", "")
+    for key, label in COMP_FIELDS:
+        t.add_row(label, _fmt_money(ceo.get(key)))
+
+    rev_cagr = ceo.get("revenueCagr")
+    if rev_cagr is not None:
+        t.add_row("Revenue CAGR", f"{rev_cagr * 100:.1f}%")
+
+    console.print(t)
+    console.print()
+
+
+def _print_ceo_table(items: list[dict]) -> None:
+    t = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+    t.add_column("Ticker", style="bold")
+    t.add_column("Company")
+    t.add_column("CEO")
+    t.add_column("Score", justify="right")
+    t.add_column("Alpha", justify="right")
+    t.add_column("RevCAGR", justify="right")
+    t.add_column("Comp", justify="center")
+    t.add_column("Tenure", justify="right")
+
+    for ceo in items:
+        t.add_row(
+            ceo.get("ticker", ""),
+            (ceo.get("companyName") or "")[:30],
+            (ceo.get("ceo") or "")[:25],
+            _fmt_score(ceo.get("ceoraterScore")),
+            _fmt_score(ceo.get("alphaScore")),
+            _fmt_score(ceo.get("revenueCagrScore")),
+            ceo.get("compScore") or "-",
+            _fmt_years(ceo.get("tenureYears")),
+        )
+
+    console.print()
+    console.print(t)
+    console.print()
+
+
+# ── CLI Group ────────────────────────────────────────────────────────────────
+
+
+@click.group()
+@click.version_option(package_name="ceorater")
+def main():
+    """CEORater — CEO performance analytics from the command line."""
+    pass
+
+
+@main.command()
+def configure():
+    """Save your CEORater API key."""
+    key = click.prompt("Enter your CEORater API key", hide_input=True)
+    key = key.strip()
+
+    if not key:
+        console.print("[red]No key entered.[/red]")
+        return
+
+    console.print("Testing connection...", end=" ")
+    try:
+        client = Client(key)
+        meta = client.meta()
+        save_key(key)
+        count = meta.get("count", "?")
+        version = meta.get("api_version", "?")
+        console.print(f"[green]Connected.[/green] {count} CEOs available. API v{version}.")
+    except CEORaterError as e:
+        console.print(f"[red]Failed.[/red] {e}")
+    except Exception as e:
+        console.print(f"[red]Connection error.[/red] {e}")
+
+
+@main.command()
+@click.argument("ticker")
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON")
+def lookup(ticker: str, as_json: bool):
+    """Look up a CEO by ticker symbol."""
+    client = _get_client()
+    try:
+        data = client.lookup(ticker.upper())
+    except CEORaterError as e:
+        _handle_error(e)
+
+    if as_json:
+        click.echo(json.dumps(data, indent=2))
+        return
+
+    if isinstance(data, list):
+        for ceo in data:
+            _print_ceo_card(ceo)
+    else:
+        _print_ceo_card(data)
+
+
+@main.command()
+@click.argument("query")
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON")
+def search(query: str, as_json: bool):
+    """Search by company name, ticker, CEO, sector, or industry."""
+    client = _get_client()
+    try:
+        data = client.search(query)
+    except CEORaterError as e:
+        _handle_error(e)
+
+    if as_json:
+        click.echo(json.dumps(data, indent=2))
+        return
+
+    items = data.get("items", [])
+    count = data.get("count", len(items))
+    console.print(f"\n  [bold]{count}[/bold] result(s) for \"{query}\"")
+    if items:
+        _print_ceo_table(items)
+
+
+@main.command("list")
+@click.option("--limit", default=20, show_default=True, help="Number of results")
+@click.option("--offset", default=0, show_default=True, help="Starting position")
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON")
+def list_ceos(limit: int, offset: int, as_json: bool):
+    """List CEOs (paginated)."""
+    client = _get_client()
+    try:
+        data = client.list_ceos(limit=limit, offset=offset)
+    except CEORaterError as e:
+        _handle_error(e)
+
+    if as_json:
+        click.echo(json.dumps(data, indent=2))
+        return
+
+    items = data.get("items", [])
+    total = data.get("total", "?")
+    console.print(f"\n  Showing {offset + 1}-{offset + len(items)} of [bold]{total}[/bold]")
+    if items:
+        _print_ceo_table(items)
+
+
+@main.command()
+@click.option("--json", "as_json", is_flag=True, help="Output raw JSON")
+def meta(as_json: bool):
+    """Show API metadata and data freshness."""
+    client = _get_client()
+    try:
+        data = client.meta()
+    except CEORaterError as e:
+        _handle_error(e)
+
+    if as_json:
+        click.echo(json.dumps(data, indent=2))
+        return
+
+    console.print()
+    console.print(f"  CEOs available : [bold]{data.get('count', '?')}[/bold]")
+    console.print(f"  Last updated   : {data.get('last_loaded', '?')}")
+    console.print(f"  API version    : {data.get('api_version', '?')}")
+    console.print(f"  Base URL       : {data.get('base_url', '?')}")
+    console.print()

ceorater-0.1.0/ceorater/client.py

@@ -0,0 +1,52 @@
+"""HTTP client for the CEORater API."""
+
+import sys
+
+import requests
+
+from ceorater import __version__
+
+BASE_URL = "https://api.ceorater.com"
+TIMEOUT = 15
+
+
+class CEORaterError(Exception):
+    def __init__(self, status: int, code: str, message: str):
+        self.status = status
+        self.code = code
+        super().__init__(message)
+
+
+class Client:
+    def __init__(self, api_key: str):
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "User-Agent": f"ceorater-cli/{__version__}",
+        })
+
+    def _get(self, path: str, params: dict | None = None) -> dict | list:
+        resp = self.session.get(f"{BASE_URL}{path}", params=params, timeout=TIMEOUT)
+        if not resp.ok:
+            try:
+                body = resp.json()
+                raise CEORaterError(
+                    resp.status_code,
+                    body.get("code", "UNKNOWN"),
+                    body.get("error", resp.text),
+                )
+            except (ValueError, KeyError):
+                raise CEORaterError(resp.status_code, "UNKNOWN", resp.text)
+        return resp.json()
+
+    def meta(self) -> dict:
+        return self._get("/v1/meta")
+
+    def lookup(self, ticker: str, fmt: str = "raw") -> dict | list:
+        return self._get(f"/v1/ceo/{ticker}", {"format": fmt})
+
+    def search(self, query: str, fmt: str = "raw") -> dict:
+        return self._get("/v1/search", {"q": query, "format": fmt})
+
+    def list_ceos(self, limit: int = 50, offset: int = 0, fmt: str = "raw") -> dict:
+        return self._get("/v1/ceos", {"limit": limit, "offset": offset, "format": fmt})

ceorater-0.1.0/ceorater/config.py

@@ -0,0 +1,31 @@
+"""API key storage and retrieval."""
+
+import json
+import os
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".ceorater"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+ENV_VAR = "CEORATER_API_KEY"
+
+
+def save_key(api_key: str) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(
+        json.dumps({"api_key": api_key}, indent=2),
+        encoding="utf-8",
+    )
+
+
+def load_key() -> str | None:
+    key = os.environ.get(ENV_VAR)
+    if key:
+        return key
+    if not CONFIG_FILE.exists():
+        return None
+    try:
+        data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+        return data.get("api_key") or None
+    except (json.JSONDecodeError, OSError):
+        return None

ceorater-0.1.0/ceorater.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: ceorater
+Version: 0.1.0
+Summary: CLI for CEORater — institutional-grade CEO performance analytics
+Author-email: Jon Maietta <support@ceorater.com>
+License: Proprietary
+Project-URL: Homepage, https://www.ceorater.com
+Project-URL: Documentation, https://www.ceorater.com/api-docs.html
+Project-URL: Support, https://www.ceorater.com/support.html
+Keywords: ceo,finance,investing,analytics,sec
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+
+# CEORater CLI
+
+Command-line interface for [CEORater](https://www.ceorater.com) — institutional-grade CEO performance analytics covering 500+ S&P 500 CEOs.
+
+## Install
+
+```bash
+pip install ceorater
+```
+
+## Setup
+
+Get your API key at [ceorater.com/api-docs.html](https://www.ceorater.com/api-docs.html), then:
+
+```bash
+ceorater configure
+```
+
+Or set the `CEORATER_API_KEY` environment variable.
+
+## Commands
+
+### Look up a CEO by ticker
+
+```bash
+ceorater lookup NVDA
+```
+
+```
+  NVIDIA (NVDA)
+  CEO: Jensen Huang  |  Founder: Yes  |  Tenure: 27.3 yrs
+  Sector: Technology  |  Industry: Semiconductors
+
+  Metric                  Value
+  CEORaterScore              99
+  AlphaScore                100
+  RevCAGR Score             100
+  CompScore                   A
+
+  TSR Multiple         589,250%
+  Avg Annual TSR        21,578%
+  TSR vs SPY           588,370%
+  Avg Annual vs SPY     21,546%
+
+  Compensation ($M)      $49.9M
+  Cost/1% TSR ($M)        $0.0M
+  Revenue CAGR            69.3%
+```
+
+### Search by company, CEO, sector, or industry
+
+```bash
+ceorater search "technology"
+```
+
+### List all CEOs (paginated)
+
+```bash
+ceorater list --limit 50
+```
+
+### Check data freshness
+
+```bash
+ceorater meta
+```
+
+### JSON output for agents and scripts
+
+Every data command supports `--json` for raw, machine-readable output:
+
+```bash
+ceorater lookup AAPL --json
+```
+
+```json
+{
+  "companyName": "Apple Inc.",
+  "ticker": "AAPL",
+  "ceoraterScore": 76.2,
+  "alphaScore": 93.9,
+  "compScore": "C",
+  ...
+}
+```
+
+## Metrics
+
+| Metric | Description |
+|--------|-------------|
+| CEORaterScore | Composite CEO effectiveness rating (0-100) |
+| AlphaScore | Market outperformance score (0-100) |
+| RevCAGR Score | Tenure-adjusted revenue growth percentile (0-100) |
+| CompScore | Compensation efficiency grade (A-F) |
+| TSR Multiple | Total Shareholder Return during tenure |
+| Cost/1% TSR | CEO compensation cost per 1% of average annual TSR |
+
+## Requirements
+
+- Python 3.9+
+- CEORater API subscription ($99/month) — [subscribe here](https://www.ceorater.com/api-docs.html)
+
+## License
+
+Proprietary. See [terms of service](https://www.ceorater.com/terms.html).

ceorater-0.1.0/ceorater.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+ceorater/__init__.py
+ceorater/__main__.py
+ceorater/cli.py
+ceorater/client.py
+ceorater/config.py
+ceorater.egg-info/PKG-INFO
+ceorater.egg-info/SOURCES.txt
+ceorater.egg-info/dependency_links.txt
+ceorater.egg-info/entry_points.txt
+ceorater.egg-info/requires.txt
+ceorater.egg-info/top_level.txt

ceorater-0.1.0/ceorater.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ceorater-0.1.0/ceorater.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ceorater = ceorater.cli:main

ceorater-0.1.0/ceorater.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.0
+requests>=2.28
+rich>=13.0

ceorater-0.1.0/ceorater.egg-info/top_level.txt

@@ -0,0 +1 @@
+ceorater

ceorater-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ceorater"
+version = "0.1.0"
+description = "CLI for CEORater — institutional-grade CEO performance analytics"
+readme = "README.md"
+license = {text = "Proprietary"}
+requires-python = ">=3.9"
+authors = [{name = "Jon Maietta", email = "support@ceorater.com"}]
+keywords = ["ceo", "finance", "investing", "analytics", "sec"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "click>=8.0",
+    "requests>=2.28",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://www.ceorater.com"
+Documentation = "https://www.ceorater.com/api-docs.html"
+Support = "https://www.ceorater.com/support.html"
+
+[project.scripts]
+ceorater = "ceorater.cli:main"

ceorater-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+