Metadata-Version: 2.4
Name: cpe-data-cli
Version: 0.4.0
Summary: Read-only CLI for a research data API (wiki, graph, memos, raw, coverage, eval). Self-documenting; an agent can drive it without a skill.
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: monitoring
Requires-Dist: sentry-sdk>=2.0; extra == 'monitoring'
Description-Content-Type: text/markdown

# data-cli

CLI for a research data API. Gives an agent (or you) access to every research
surface — memos, company wiki, knowledge graph, raw primary-source files,
coverage, and eval — to **analyze a stock**, and can trigger research (gather a
ticker, refetch a source, comment on a memo) through one self-documenting tool.

The key grants read access to every surface plus a small set of action POSTs
(gather/new symbol, re-run a phase, refetch/repair/fetch-missing a source,
refresh people radar, comment on a memo). It **cannot** upload externally-built
content, edit events, run model bakeoffs/simulations, or run grounded chat —
those return 403. It is an actions API, not a content writer.

This tool talks to a private data API. You need two values, **provided to you
separately**: the API base URL and a key. Without both, the tool does nothing.

## Install

```bash
pip install cpe-data-cli
# or, isolated:
pipx install cpe-data-cli
```

### Upgrade

```bash
pip install --upgrade cpe-data-cli
# or, with pipx:
pipx upgrade cpe-data-cli
```

## Configure

```bash
export CPE_API_BASE=<base url you were given>
export CPE_API_KEY=<key you were given>
data-cli auth check              # verify base + key + connectivity
```

Both are required. The tool makes no network call until both are set.

## Version & completion

```bash
data-cli --version               # or -V
data-cli --install-completion    # install shell completion (bash/zsh/fish)
```

## Analyze a stock

Read the synthesized dossier, then pull the specific primary-source figures you
want to cite. Every command prints the next commands to run.

```bash
data-cli memo get NVDA                  # START HERE: the full verified dossier (markdown)
data-cli wiki get NVDA                  # synthesized company page (business, segments, model)
data-cli ticker NVDA                    # one-line orientation (latest run, coverage%, raw count)
data-cli raw NVDA source_map.json       # provenance map: read FIRST to find Tier-1 files
data-cli raw NVDA latest_10k.json       # a specific primary source (10-K, financials, ...)
data-cli graph ticker NVDA              # supply/customer/competitor/segment web
```

More surfaces:

```bash
data-cli memo list NVDA                 # other runs/dossiers for the ticker
data-cli wiki list                      # all covered companies
data-cli raw NVDA                       # list every primary-source file
data-cli coverage NVDA                  # source-completeness (check before quoting a number)
data-cli eval NVDA                      # quality verdict + contradiction tally
data-cli graph search "TSMC"            # find nodes by NAME (companies/people, not concepts)
data-cli graph all                      # the full knowledge graph
data-cli guide                          # this workflow, any time
```

Read the trust layer as a **citation check, not the story**: build the analysis
from the memo + Tier-1 sources, glance at coverage/eval before quoting a specific
number, and don't lead with contradicted claims.

## Trigger research

These spend real compute; use them deliberately.

```bash
data-cli gather NVDA                     # gather/refresh a ticker (works for a new symbol too)
data-cli gather NVDA --model opus        # pick a model
data-cli gather NVDA --phase analyze     # re-run a single pipeline phase
data-cli refetch NVDA financials         # refetch one source category
data-cli fetch-missing NVDA              # fetch all missing sources
data-cli repair <source_name>            # repair a specific source
data-cli people-radar refresh            # refresh the people radar
data-cli comment <RUN_ID> --section <s> --issue-type <t> --note "..."   # comment on a memo
```

## Output

- Markdown-native surfaces (`wiki`, `memo`, raw `.md`) print **markdown** by
  default. `coverage` and `eval` print a **human-readable summary** by default
  (the trust layer, scannable at a glance); add `--json` for the full payload.
  Other structured surfaces (`ticker`, `graph`, lists) print **JSON**.
- `--json` on any data command for structured output (with `_next` breadcrumbs
  in the body).
- `-o FILE` writes the content to a file (confirmation goes to stderr). Plain
  `> file.md` works too — diagnostics and breadcrumbs go to stderr, so a
  redirected or `-o` file holds only clean content. (`auth check` and `guide`
  are diagnostics and ignore `-o`.)

## For AI agents

This tool ships with an agent skill that teaches the right way to drive it
(analyze a stock from the memo + Tier-1 sources, read the trust layer as a
citation check, and the common pitfalls):

```bash
data-cli skill          # print the skill
data-cli skill --path   # print its path — point your agent's skills dir at it
```
