jstdata 0.2.0__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- jstdata-0.4.0/PKG-INFO +285 -0
- jstdata-0.4.0/README.md +248 -0
- {jstdata-0.2.0 → jstdata-0.4.0}/jstdata/__init__.py +2 -2
- jstdata-0.4.0/jstdata/actions/__init__.py +49 -0
- jstdata-0.4.0/jstdata/actions/base.py +298 -0
- {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/chart.py +18 -9
- {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/console.py +57 -69
- {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/discover.py +242 -88
- jstdata-0.4.0/jstdata/actions/drill.py +137 -0
- jstdata-0.4.0/jstdata/actions/entity_view.py +580 -0
- jstdata-0.4.0/jstdata/actions/help.py +103 -0
- jstdata-0.4.0/jstdata/actions/metric_view.py +536 -0
- jstdata-0.4.0/jstdata/actions/metrics_view.py +530 -0
- jstdata-0.4.0/jstdata/actions/pagination.py +24 -0
- jstdata-0.4.0/jstdata/actions/query_view.py +1465 -0
- {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/rank.py +144 -74
- jstdata-0.4.0/jstdata/actions/release_view.py +334 -0
- jstdata-0.4.0/jstdata/actions/screen.py +82 -0
- jstdata-0.4.0/jstdata/actions/table.py +790 -0
- jstdata-0.4.0/jstdata/add_options.py +89 -0
- jstdata-0.4.0/jstdata/agent/__init__.py +1 -0
- jstdata-0.4.0/jstdata/agent/install.py +55 -0
- jstdata-0.4.0/jstdata/agent/skills/jst/SKILL.md +34 -0
- jstdata-0.4.0/jstdata/agent_guide.py +632 -0
- jstdata-0.4.0/jstdata/cli.py +1183 -0
- {jstdata-0.2.0 → jstdata-0.4.0}/jstdata/client.py +210 -28
- jstdata-0.4.0/jstdata/investigation/__init__.py +104 -0
- jstdata-0.4.0/jstdata/investigation/active.py +98 -0
- jstdata-0.4.0/jstdata/investigation/api.py +477 -0
- jstdata-0.4.0/jstdata/investigation/bootstrap.py +96 -0
- jstdata-0.4.0/jstdata/investigation/browsers.py +945 -0
- jstdata-0.4.0/jstdata/investigation/bundled/__init__.py +1 -0
- jstdata-0.4.0/jstdata/investigation/bundled/plain-bagel.yaml +77 -0
- jstdata-0.4.0/jstdata/investigation/bundled/tutorial.yaml +17 -0
- jstdata-0.4.0/jstdata/investigation/command_palette.py +438 -0
- jstdata-0.4.0/jstdata/investigation/commands.py +502 -0
- jstdata-0.4.0/jstdata/investigation/home.py +1320 -0
- jstdata-0.4.0/jstdata/investigation/host.py +1812 -0
- jstdata-0.4.0/jstdata/investigation/model.py +1071 -0
- jstdata-0.4.0/jstdata/investigation/nav.py +617 -0
- jstdata-0.4.0/jstdata/investigation/publish_screens.py +242 -0
- jstdata-0.4.0/jstdata/investigation/search_drawer.py +467 -0
- jstdata-0.4.0/jstdata/investigation/store.py +116 -0
- jstdata-0.4.0/jstdata/investigation/workspace_drawer.py +199 -0
- jstdata-0.4.0/jstdata/models.py +320 -0
- jstdata-0.4.0/jstdata/onboarding/__init__.py +35 -0
- jstdata-0.4.0/jstdata/onboarding/tips.py +172 -0
- jstdata-0.4.0/jstdata/onboarding/tutorials/big-tech-gross-profit.yaml +70 -0
- jstdata-0.4.0/jstdata/onboarding/tutorials/g7-government-debt.yaml +38 -0
- jstdata-0.4.0/jstdata/onboarding/tutorials/gulf-oil-exports.yaml +59 -0
- jstdata-0.4.0/jstdata/onboarding/tutorials.py +310 -0
- jstdata-0.4.0/jstdata/onboarding/ui.py +419 -0
- jstdata-0.4.0/jstdata/preview/__init__.py +74 -0
- jstdata-0.4.0/jstdata/preview/data.py +523 -0
- jstdata-0.4.0/jstdata/preview/progress.py +124 -0
- jstdata-0.4.0/jstdata/preview/render.py +965 -0
- jstdata-0.4.0/jstdata/publish.py +238 -0
- jstdata-0.4.0/jstdata/publish_draft.py +166 -0
- jstdata-0.4.0/jstdata/resource_cache.py +206 -0
- {jstdata-0.2.0 → jstdata-0.4.0}/pyproject.toml +19 -5
- jstdata-0.2.0/PKG-INFO +0 -227
- jstdata-0.2.0/README.md +0 -196
- jstdata-0.2.0/jstdata/agent_guide.py +0 -530
- jstdata-0.2.0/jstdata/cli.py +0 -682
- jstdata-0.2.0/jstdata/models.py +0 -161
- jstdata-0.2.0/jstdata/session.py +0 -251
- jstdata-0.2.0/jstdata/workflows/__init__.py +0 -88
- jstdata-0.2.0/jstdata/workflows/base.py +0 -356
- jstdata-0.2.0/jstdata/workflows/bundled/__init__.py +0 -1
- jstdata-0.2.0/jstdata/workflows/bundled/tutorial.yaml +0 -14
- jstdata-0.2.0/jstdata/workflows/bundled/tutorial_script.yaml +0 -45
- jstdata-0.2.0/jstdata/workflows/export.py +0 -171
- jstdata-0.2.0/jstdata/workflows/find.py +0 -386
- jstdata-0.2.0/jstdata/workflows/host.py +0 -255
- jstdata-0.2.0/jstdata/workflows/session_manager.py +0 -277
- jstdata-0.2.0/jstdata/workflows/store.py +0 -308
- jstdata-0.2.0/jstdata/workflows/tutorial.py +0 -163
- jstdata-0.2.0/jstdata/workflows/tutorial_host.py +0 -178
- {jstdata-0.2.0 → jstdata-0.4.0}/LICENSE +0 -0
- {jstdata-0.2.0 → jstdata-0.4.0}/jstdata/utils.py +0 -0
jstdata-0.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: jstdata
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Python API, CLI, and investigation TUI for Jefferson Street financial and economic data.
|
|
5
|
+
License: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Keywords: api,cli,data,jefferson street,economics,finance
|
|
8
|
+
Author: Mahfuj Ahbab
|
|
9
|
+
Requires-Python: >=3.10,<4.0
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
21
|
+
Requires-Dist: bokeh (>=3.8.0,<4.0.0)
|
|
22
|
+
Requires-Dist: certifi (>=2026.10.19)
|
|
23
|
+
Requires-Dist: click (>=8.2.1,<9.0.0)
|
|
24
|
+
Requires-Dist: idna (>=3.15)
|
|
25
|
+
Requires-Dist: pandas (>=2.3.1,<3.0.0)
|
|
26
|
+
Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
|
|
27
|
+
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
|
|
28
|
+
Requires-Dist: requests (>=2.31.0,<3.0.0)
|
|
29
|
+
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
|
|
30
|
+
Requires-Dist: textual (>=1.0.0,<2.0.0)
|
|
31
|
+
Requires-Dist: textual-plotext (>=1.0.1,<2.0.0)
|
|
32
|
+
Requires-Dist: urllib3 (>=2.8.0)
|
|
33
|
+
Project-URL: Homepage, https://github.com/Jefferson-Street-Technologies/jstdata
|
|
34
|
+
Project-URL: Repository, https://github.com/Jefferson-Street-Technologies/jstdata
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# Jefferson Street Data (jstdata)
|
|
38
|
+
|
|
39
|
+
A Python interface and Investigation IDE for the Jefferson Street financial and
|
|
40
|
+
economic data API.
|
|
41
|
+
|
|
42
|
+
## Design Philosophy: From Filing Cabinet to Knowledge Graph
|
|
43
|
+
|
|
44
|
+
`jstdata` is built to minimize the friction between human thought and actionable data.
|
|
45
|
+
|
|
46
|
+
- **Series-First**: The individual data series is the primary resource, carrying its own metadata (frequency, units, source).
|
|
47
|
+
- **Entity Graph**: Entities are nodes in a relational graph — walk from a company to its SIC, a security ticker, or a geography.
|
|
48
|
+
- **Taxonomies**: Named populations (`country`, `sec-central-index-key`, …) scope search, query, and ranking.
|
|
49
|
+
- **Intent over IDs**: CLI and Python favor fuzzy search over memorizing slugs; always resolve before querying.
|
|
50
|
+
- **Investigations**: Durable research artifacts — one workspace (staged ids), saved queries (cartesian metric × entity), and a tree of actions (analytical TUIs).
|
|
51
|
+
- **Reproducible Discovery**: High-speed discovery in the TUI transitions into immutable Python / CLI snippets.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Using poetry
|
|
59
|
+
poetry install
|
|
60
|
+
|
|
61
|
+
# Manual install
|
|
62
|
+
pip install .
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Authentication & Configuration
|
|
66
|
+
|
|
67
|
+
### Quick Start (CLI)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
jst login
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Credentials are saved to `~/.jstdata/config.json` with secure permissions.
|
|
74
|
+
|
|
75
|
+
### Environment Variables
|
|
76
|
+
|
|
77
|
+
These take precedence over the config file:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
export JSTDATA_API_KEY="your-api-key-here"
|
|
81
|
+
# Optional: export JSTDATA_BASE_URL="https://api.jeffersonst.io"
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Managing Configuration
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
jst config show
|
|
88
|
+
jst config show --verbose
|
|
89
|
+
jst config set api_key XXX
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Investigations
|
|
93
|
+
|
|
94
|
+
An **investigation** is the durable research unit: YAML under
|
|
95
|
+
`~/.jstdata/investigations/` with one **workspace** (staged metrics / entities /
|
|
96
|
+
series), saved **queries** (cartesian metric × entity against `GET /query`), and
|
|
97
|
+
a tree of **actions** (reusable TUI screens).
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
jst new --id housing-slowdown
|
|
101
|
+
jst open housing-slowdown
|
|
102
|
+
jst ls
|
|
103
|
+
jst # reopen the active investigation (Untitled if none)
|
|
104
|
+
|
|
105
|
+
# Saved queries (cartesian metric × entity)
|
|
106
|
+
jst query add --metric gdp --entity france --entity usa --name "FR vs US"
|
|
107
|
+
jst query inspect 1
|
|
108
|
+
jst query run 1 --format json
|
|
109
|
+
|
|
110
|
+
# Add actions (children of the active action unless --parent is set)
|
|
111
|
+
jst action add console --args '{"taxonomy":"country","resource_type":"entity"}'
|
|
112
|
+
jst action add discover --args '{"mode":"union"}' --activate
|
|
113
|
+
jst action add rank --args '{"taxonomy":"country"}'
|
|
114
|
+
jst action rm 2 --force
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Built-in actions:
|
|
118
|
+
|
|
119
|
+
| Action | Role |
|
|
120
|
+
|--------|------|
|
|
121
|
+
| `console` | Search catalog; stage into the workspace |
|
|
122
|
+
| `discover` | Find metrics for workspace entities; preview coverage |
|
|
123
|
+
| `rank` | Leaderboard entities for a workspace metric |
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
jst action ls
|
|
127
|
+
jst action show console
|
|
128
|
+
jst action show rank --json
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Inside the TUI: `g` returns Home (Recent / Search / Actions / Workspace /
|
|
132
|
+
Queries). `esc` goes back one level. `:` opens the command palette (fuzzy
|
|
133
|
+
destinations and saved queries, plus `:workspace`, `:search metric gdp`,
|
|
134
|
+
`:query`, `:rename`, `:publish`, `:add`, `:rm`, `:tutorial`) · `n`/`p` (↑/↓) siblings ·
|
|
135
|
+
`N`/`P` (→/←) depth · space collects into the workspace · `t` tutorials ·
|
|
136
|
+
`?` help · `q` quit.
|
|
137
|
+
|
|
138
|
+
Active context lives in `~/.jstdata/.active.yaml`.
|
|
139
|
+
|
|
140
|
+
### Publish and clone
|
|
141
|
+
|
|
142
|
+
Publishing turns an investigation into a web page that anyone with the link
|
|
143
|
+
can open: its queries, annotations and results, with each observation's
|
|
144
|
+
provenance and a CSV download. Signed-in visitors can refresh the results with
|
|
145
|
+
their own API key. The website runs the queries with yours when you publish.
|
|
146
|
+
|
|
147
|
+
When you publish, a **draft of the page** opens first: the title, a one-line
|
|
148
|
+
description, an overview, and a note under each query's charts, all in one
|
|
149
|
+
Markdown document laid out like the page. Fill it in and press `Ctrl+S`; the
|
|
150
|
+
text is saved to the investigation, and you confirm before anything is shared.
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
jst publish # the active investigation: draft, confirm, publish
|
|
154
|
+
jst publish plain-bagel --no-edit # skip the draft, use the saved text
|
|
155
|
+
jst publish plain-bagel --yes # no draft, no confirmation (scripts)
|
|
156
|
+
jst clone https://www.jeffersonst.io/p/AbCdEf1234 # copy one into your environment
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
In the TUI, `:publish` does the same and shows the link, with `c` to copy it
|
|
160
|
+
and `o` to open it. Each publish makes a new link with the results as of then;
|
|
161
|
+
earlier links don't change. `jst clone` saves the published queries and
|
|
162
|
+
annotations as a new local investigation (adding `-clone` if the id is taken)
|
|
163
|
+
and needs no API key.
|
|
164
|
+
|
|
165
|
+
Annotations (investigation and query) are Markdown; see
|
|
166
|
+
[docs/annotations.md](docs/annotations.md) for the format and what's planned.
|
|
167
|
+
|
|
168
|
+
The website defaults to `https://www.jeffersonst.io`; point at another with
|
|
169
|
+
`JSTDATA_SITE_URL` or `jst config set site_url <url>`.
|
|
170
|
+
|
|
171
|
+
### Tutorials
|
|
172
|
+
|
|
173
|
+
The first time you open the TUI, a tutorial menu appears. Pick one, or press
|
|
174
|
+
`esc` to explore on your own; `t` (or `:tutorial`) brings the menu back any
|
|
175
|
+
time. A coach bar docked at the top explains each step and names the exact
|
|
176
|
+
keys to press, and advances as you do them. Each tutorial runs in its own
|
|
177
|
+
investigation (`tutorial-<id>`); leaving it reopens yours.
|
|
178
|
+
|
|
179
|
+
| Tutorial | Level | What you do |
|
|
180
|
+
|----------|-------|-------------|
|
|
181
|
+
| `big-tech-gross-profit` | Beginner · guided | Compare Apple, Microsoft, Amazon: Home → Search → collect → metric view → Workspace → Query → chart |
|
|
182
|
+
| `gulf-oil-exports` | Intermediate · assisted | Metric-first: collect the oil metrics, open one to see which countries report it, collect the Gulf, chart the query |
|
|
183
|
+
| `g7-government-debt` | Advanced · open | Research question on G7 government debt vs inflation; the coach only checks progress |
|
|
184
|
+
|
|
185
|
+
A **tip** box across the top of each screen tells you what to press there
|
|
186
|
+
(e.g. *Press "2" to open Search*). Hide it with its "✕ hide tips" or `:tips off`; `:tips on`
|
|
187
|
+
brings it back.
|
|
188
|
+
|
|
189
|
+
Progress (menu seen, tutorials completed, tips on/off) lives in
|
|
190
|
+
`~/.jstdata/onboarding.json`.
|
|
191
|
+
First `jst` / `jst new` / `jst open` also bootstraps the bundled `tutorial`
|
|
192
|
+
(welcome) and `plain-bagel` demo investigations when none exist.
|
|
193
|
+
|
|
194
|
+
### Agents
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
jst agent-guide
|
|
198
|
+
jst agent install # Codex, Claude Code, Cursor (~/.agents, ~/.claude, ~/.cursor)
|
|
199
|
+
jst agent install cursor
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`jst agent-guide` is the versioned operating manual (hard rules, modes, recipes,
|
|
203
|
+
and the live CLI/action reference). Prefer it over guessing command shapes or
|
|
204
|
+
inventing ids. `jst agent install` copies a tiny pointer skill (`run jst
|
|
205
|
+
agent-guide`) into user-level skill directories. Discovery is not guaranteed —
|
|
206
|
+
if the agent does not pick it up, say: *Use the jst skill. Then run `jst
|
|
207
|
+
agent-guide` and follow it.*
|
|
208
|
+
|
|
209
|
+
## The Scriptable API CLI (`jst api`)
|
|
210
|
+
|
|
211
|
+
Pipe-friendly resource commands for automation and quick extraction. Nested
|
|
212
|
+
under `jst api` so they stay distinct from investigation commands.
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
# Fuzzy / set search (omit QUERY to list the matching set)
|
|
216
|
+
jst api metric search "defense spending" --taxonomy country --limit 20 --format json
|
|
217
|
+
jst api entity search --relation classified_as:sic:3674 --limit 50 --format json
|
|
218
|
+
jst api entity search --metric gdp --metric cpi --mode intersect --format json
|
|
219
|
+
|
|
220
|
+
# Taxonomies
|
|
221
|
+
jst api taxonomy ls --format json
|
|
222
|
+
jst api taxonomy entities country --limit 20 --format json
|
|
223
|
+
|
|
224
|
+
# Bounded cross-sectional query (head/tail per series)
|
|
225
|
+
jst api query --metric inflation --entity "United States" --frequency Monthly --tail 20
|
|
226
|
+
jst api query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json
|
|
227
|
+
|
|
228
|
+
# Deep history for one known series
|
|
229
|
+
jst api series observations ABC123 --start-date 2000-01-01 --limit 1000
|
|
230
|
+
|
|
231
|
+
# Entity graph
|
|
232
|
+
jst api entity relations cik:1045810 --format pretty
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## The Python API
|
|
236
|
+
|
|
237
|
+
```python
|
|
238
|
+
from jstdata import JSTDataClient
|
|
239
|
+
from jstdata.investigation import Workspace
|
|
240
|
+
|
|
241
|
+
client = JSTDataClient()
|
|
242
|
+
|
|
243
|
+
# Cross-sectional observations (bounded per series)
|
|
244
|
+
df = client.query_df(
|
|
245
|
+
metric="gross-domestic-product",
|
|
246
|
+
entity=["usa", "gbr"],
|
|
247
|
+
tail=20,
|
|
248
|
+
)
|
|
249
|
+
|
|
250
|
+
# Rank a taxonomy population by latest value
|
|
251
|
+
top = client.query(
|
|
252
|
+
metric="gross-domestic-product",
|
|
253
|
+
taxonomy="country",
|
|
254
|
+
frequency="Annual",
|
|
255
|
+
tail=1,
|
|
256
|
+
sort_by="value",
|
|
257
|
+
limit=50,
|
|
258
|
+
)
|
|
259
|
+
|
|
260
|
+
# Relation-scoped entity search (OR when multiple)
|
|
261
|
+
entities = client.search_entities(
|
|
262
|
+
relation=["classified_as:sic:7372", "classified_as:sic:5961"],
|
|
263
|
+
taxonomy="sec-central-index-key",
|
|
264
|
+
limit=50,
|
|
265
|
+
)
|
|
266
|
+
|
|
267
|
+
# Deep history for one series
|
|
268
|
+
obs = client.get_series_observations("ABC123", start_date="2000-01-01")
|
|
269
|
+
|
|
270
|
+
# Workspace helpers project the same selectors as jst api query
|
|
271
|
+
ws = Workspace(
|
|
272
|
+
metric=["gross-domestic-product"],
|
|
273
|
+
taxonomy="country",
|
|
274
|
+
tail=1,
|
|
275
|
+
sort_by="value",
|
|
276
|
+
)
|
|
277
|
+
print(ws.to_cli())
|
|
278
|
+
df = ws.execute_df(client)
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
## Extending the product
|
|
282
|
+
|
|
283
|
+
See [AGENTS.md](AGENTS.md) for how investigations, workspaces, and actions are
|
|
284
|
+
structured when adding new interactive surface area.
|
|
285
|
+
|
jstdata-0.4.0/README.md
ADDED
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
# Jefferson Street Data (jstdata)
|
|
2
|
+
|
|
3
|
+
A Python interface and Investigation IDE for the Jefferson Street financial and
|
|
4
|
+
economic data API.
|
|
5
|
+
|
|
6
|
+
## Design Philosophy: From Filing Cabinet to Knowledge Graph
|
|
7
|
+
|
|
8
|
+
`jstdata` is built to minimize the friction between human thought and actionable data.
|
|
9
|
+
|
|
10
|
+
- **Series-First**: The individual data series is the primary resource, carrying its own metadata (frequency, units, source).
|
|
11
|
+
- **Entity Graph**: Entities are nodes in a relational graph — walk from a company to its SIC, a security ticker, or a geography.
|
|
12
|
+
- **Taxonomies**: Named populations (`country`, `sec-central-index-key`, …) scope search, query, and ranking.
|
|
13
|
+
- **Intent over IDs**: CLI and Python favor fuzzy search over memorizing slugs; always resolve before querying.
|
|
14
|
+
- **Investigations**: Durable research artifacts — one workspace (staged ids), saved queries (cartesian metric × entity), and a tree of actions (analytical TUIs).
|
|
15
|
+
- **Reproducible Discovery**: High-speed discovery in the TUI transitions into immutable Python / CLI snippets.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
# Using poetry
|
|
23
|
+
poetry install
|
|
24
|
+
|
|
25
|
+
# Manual install
|
|
26
|
+
pip install .
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Authentication & Configuration
|
|
30
|
+
|
|
31
|
+
### Quick Start (CLI)
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
jst login
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Credentials are saved to `~/.jstdata/config.json` with secure permissions.
|
|
38
|
+
|
|
39
|
+
### Environment Variables
|
|
40
|
+
|
|
41
|
+
These take precedence over the config file:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
export JSTDATA_API_KEY="your-api-key-here"
|
|
45
|
+
# Optional: export JSTDATA_BASE_URL="https://api.jeffersonst.io"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Managing Configuration
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
jst config show
|
|
52
|
+
jst config show --verbose
|
|
53
|
+
jst config set api_key XXX
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Investigations
|
|
57
|
+
|
|
58
|
+
An **investigation** is the durable research unit: YAML under
|
|
59
|
+
`~/.jstdata/investigations/` with one **workspace** (staged metrics / entities /
|
|
60
|
+
series), saved **queries** (cartesian metric × entity against `GET /query`), and
|
|
61
|
+
a tree of **actions** (reusable TUI screens).
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
jst new --id housing-slowdown
|
|
65
|
+
jst open housing-slowdown
|
|
66
|
+
jst ls
|
|
67
|
+
jst # reopen the active investigation (Untitled if none)
|
|
68
|
+
|
|
69
|
+
# Saved queries (cartesian metric × entity)
|
|
70
|
+
jst query add --metric gdp --entity france --entity usa --name "FR vs US"
|
|
71
|
+
jst query inspect 1
|
|
72
|
+
jst query run 1 --format json
|
|
73
|
+
|
|
74
|
+
# Add actions (children of the active action unless --parent is set)
|
|
75
|
+
jst action add console --args '{"taxonomy":"country","resource_type":"entity"}'
|
|
76
|
+
jst action add discover --args '{"mode":"union"}' --activate
|
|
77
|
+
jst action add rank --args '{"taxonomy":"country"}'
|
|
78
|
+
jst action rm 2 --force
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Built-in actions:
|
|
82
|
+
|
|
83
|
+
| Action | Role |
|
|
84
|
+
|--------|------|
|
|
85
|
+
| `console` | Search catalog; stage into the workspace |
|
|
86
|
+
| `discover` | Find metrics for workspace entities; preview coverage |
|
|
87
|
+
| `rank` | Leaderboard entities for a workspace metric |
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
jst action ls
|
|
91
|
+
jst action show console
|
|
92
|
+
jst action show rank --json
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Inside the TUI: `g` returns Home (Recent / Search / Actions / Workspace /
|
|
96
|
+
Queries). `esc` goes back one level. `:` opens the command palette (fuzzy
|
|
97
|
+
destinations and saved queries, plus `:workspace`, `:search metric gdp`,
|
|
98
|
+
`:query`, `:rename`, `:publish`, `:add`, `:rm`, `:tutorial`) · `n`/`p` (↑/↓) siblings ·
|
|
99
|
+
`N`/`P` (→/←) depth · space collects into the workspace · `t` tutorials ·
|
|
100
|
+
`?` help · `q` quit.
|
|
101
|
+
|
|
102
|
+
Active context lives in `~/.jstdata/.active.yaml`.
|
|
103
|
+
|
|
104
|
+
### Publish and clone
|
|
105
|
+
|
|
106
|
+
Publishing turns an investigation into a web page that anyone with the link
|
|
107
|
+
can open: its queries, annotations and results, with each observation's
|
|
108
|
+
provenance and a CSV download. Signed-in visitors can refresh the results with
|
|
109
|
+
their own API key. The website runs the queries with yours when you publish.
|
|
110
|
+
|
|
111
|
+
When you publish, a **draft of the page** opens first: the title, a one-line
|
|
112
|
+
description, an overview, and a note under each query's charts, all in one
|
|
113
|
+
Markdown document laid out like the page. Fill it in and press `Ctrl+S`; the
|
|
114
|
+
text is saved to the investigation, and you confirm before anything is shared.
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
jst publish # the active investigation: draft, confirm, publish
|
|
118
|
+
jst publish plain-bagel --no-edit # skip the draft, use the saved text
|
|
119
|
+
jst publish plain-bagel --yes # no draft, no confirmation (scripts)
|
|
120
|
+
jst clone https://www.jeffersonst.io/p/AbCdEf1234 # copy one into your environment
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
In the TUI, `:publish` does the same and shows the link, with `c` to copy it
|
|
124
|
+
and `o` to open it. Each publish makes a new link with the results as of then;
|
|
125
|
+
earlier links don't change. `jst clone` saves the published queries and
|
|
126
|
+
annotations as a new local investigation (adding `-clone` if the id is taken)
|
|
127
|
+
and needs no API key.
|
|
128
|
+
|
|
129
|
+
Annotations (investigation and query) are Markdown; see
|
|
130
|
+
[docs/annotations.md](docs/annotations.md) for the format and what's planned.
|
|
131
|
+
|
|
132
|
+
The website defaults to `https://www.jeffersonst.io`; point at another with
|
|
133
|
+
`JSTDATA_SITE_URL` or `jst config set site_url <url>`.
|
|
134
|
+
|
|
135
|
+
### Tutorials
|
|
136
|
+
|
|
137
|
+
The first time you open the TUI, a tutorial menu appears. Pick one, or press
|
|
138
|
+
`esc` to explore on your own; `t` (or `:tutorial`) brings the menu back any
|
|
139
|
+
time. A coach bar docked at the top explains each step and names the exact
|
|
140
|
+
keys to press, and advances as you do them. Each tutorial runs in its own
|
|
141
|
+
investigation (`tutorial-<id>`); leaving it reopens yours.
|
|
142
|
+
|
|
143
|
+
| Tutorial | Level | What you do |
|
|
144
|
+
|----------|-------|-------------|
|
|
145
|
+
| `big-tech-gross-profit` | Beginner · guided | Compare Apple, Microsoft, Amazon: Home → Search → collect → metric view → Workspace → Query → chart |
|
|
146
|
+
| `gulf-oil-exports` | Intermediate · assisted | Metric-first: collect the oil metrics, open one to see which countries report it, collect the Gulf, chart the query |
|
|
147
|
+
| `g7-government-debt` | Advanced · open | Research question on G7 government debt vs inflation; the coach only checks progress |
|
|
148
|
+
|
|
149
|
+
A **tip** box across the top of each screen tells you what to press there
|
|
150
|
+
(e.g. *Press "2" to open Search*). Hide it with its "✕ hide tips" or `:tips off`; `:tips on`
|
|
151
|
+
brings it back.
|
|
152
|
+
|
|
153
|
+
Progress (menu seen, tutorials completed, tips on/off) lives in
|
|
154
|
+
`~/.jstdata/onboarding.json`.
|
|
155
|
+
First `jst` / `jst new` / `jst open` also bootstraps the bundled `tutorial`
|
|
156
|
+
(welcome) and `plain-bagel` demo investigations when none exist.
|
|
157
|
+
|
|
158
|
+
### Agents
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
jst agent-guide
|
|
162
|
+
jst agent install # Codex, Claude Code, Cursor (~/.agents, ~/.claude, ~/.cursor)
|
|
163
|
+
jst agent install cursor
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
`jst agent-guide` is the versioned operating manual (hard rules, modes, recipes,
|
|
167
|
+
and the live CLI/action reference). Prefer it over guessing command shapes or
|
|
168
|
+
inventing ids. `jst agent install` copies a tiny pointer skill (`run jst
|
|
169
|
+
agent-guide`) into user-level skill directories. Discovery is not guaranteed —
|
|
170
|
+
if the agent does not pick it up, say: *Use the jst skill. Then run `jst
|
|
171
|
+
agent-guide` and follow it.*
|
|
172
|
+
|
|
173
|
+
## The Scriptable API CLI (`jst api`)
|
|
174
|
+
|
|
175
|
+
Pipe-friendly resource commands for automation and quick extraction. Nested
|
|
176
|
+
under `jst api` so they stay distinct from investigation commands.
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
# Fuzzy / set search (omit QUERY to list the matching set)
|
|
180
|
+
jst api metric search "defense spending" --taxonomy country --limit 20 --format json
|
|
181
|
+
jst api entity search --relation classified_as:sic:3674 --limit 50 --format json
|
|
182
|
+
jst api entity search --metric gdp --metric cpi --mode intersect --format json
|
|
183
|
+
|
|
184
|
+
# Taxonomies
|
|
185
|
+
jst api taxonomy ls --format json
|
|
186
|
+
jst api taxonomy entities country --limit 20 --format json
|
|
187
|
+
|
|
188
|
+
# Bounded cross-sectional query (head/tail per series)
|
|
189
|
+
jst api query --metric inflation --entity "United States" --frequency Monthly --tail 20
|
|
190
|
+
jst api query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json
|
|
191
|
+
|
|
192
|
+
# Deep history for one known series
|
|
193
|
+
jst api series observations ABC123 --start-date 2000-01-01 --limit 1000
|
|
194
|
+
|
|
195
|
+
# Entity graph
|
|
196
|
+
jst api entity relations cik:1045810 --format pretty
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
## The Python API
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
from jstdata import JSTDataClient
|
|
203
|
+
from jstdata.investigation import Workspace
|
|
204
|
+
|
|
205
|
+
client = JSTDataClient()
|
|
206
|
+
|
|
207
|
+
# Cross-sectional observations (bounded per series)
|
|
208
|
+
df = client.query_df(
|
|
209
|
+
metric="gross-domestic-product",
|
|
210
|
+
entity=["usa", "gbr"],
|
|
211
|
+
tail=20,
|
|
212
|
+
)
|
|
213
|
+
|
|
214
|
+
# Rank a taxonomy population by latest value
|
|
215
|
+
top = client.query(
|
|
216
|
+
metric="gross-domestic-product",
|
|
217
|
+
taxonomy="country",
|
|
218
|
+
frequency="Annual",
|
|
219
|
+
tail=1,
|
|
220
|
+
sort_by="value",
|
|
221
|
+
limit=50,
|
|
222
|
+
)
|
|
223
|
+
|
|
224
|
+
# Relation-scoped entity search (OR when multiple)
|
|
225
|
+
entities = client.search_entities(
|
|
226
|
+
relation=["classified_as:sic:7372", "classified_as:sic:5961"],
|
|
227
|
+
taxonomy="sec-central-index-key",
|
|
228
|
+
limit=50,
|
|
229
|
+
)
|
|
230
|
+
|
|
231
|
+
# Deep history for one series
|
|
232
|
+
obs = client.get_series_observations("ABC123", start_date="2000-01-01")
|
|
233
|
+
|
|
234
|
+
# Workspace helpers project the same selectors as jst api query
|
|
235
|
+
ws = Workspace(
|
|
236
|
+
metric=["gross-domestic-product"],
|
|
237
|
+
taxonomy="country",
|
|
238
|
+
tail=1,
|
|
239
|
+
sort_by="value",
|
|
240
|
+
)
|
|
241
|
+
print(ws.to_cli())
|
|
242
|
+
df = ws.execute_df(client)
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
## Extending the product
|
|
246
|
+
|
|
247
|
+
See [AGENTS.md](AGENTS.md) for how investigations, workspaces, and actions are
|
|
248
|
+
structured when adding new interactive surface area.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
from .client import JSTDataClient
|
|
2
2
|
from .models import Entity, Metric, Series, Observation, Taxonomy
|
|
3
|
-
from .
|
|
3
|
+
from .investigation.model import Workspace
|
|
4
4
|
|
|
5
5
|
__all__ = [
|
|
6
6
|
"JSTDataClient",
|
|
@@ -9,5 +9,5 @@ __all__ = [
|
|
|
9
9
|
"Series",
|
|
10
10
|
"Observation",
|
|
11
11
|
"Taxonomy",
|
|
12
|
-
"
|
|
12
|
+
"Workspace",
|
|
13
13
|
]
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"""Reusable investigation actions (analytical TUI screens).
|
|
2
|
+
|
|
3
|
+
::
|
|
4
|
+
|
|
5
|
+
jst action ls
|
|
6
|
+
jst action show console
|
|
7
|
+
jst action add console --args '{"taxonomy":"country"}'
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from .base import (
|
|
11
|
+
ActionArgument,
|
|
12
|
+
ActionBinding,
|
|
13
|
+
ActionSpec,
|
|
14
|
+
format_action_help,
|
|
15
|
+
get_action,
|
|
16
|
+
hydrate_labels,
|
|
17
|
+
label_for,
|
|
18
|
+
list_actions,
|
|
19
|
+
parse_action_kwargs,
|
|
20
|
+
register,
|
|
21
|
+
resource_type_for_id,
|
|
22
|
+
)
|
|
23
|
+
from .help import HelpScreen
|
|
24
|
+
from .screen import BaseScreen
|
|
25
|
+
from . import console as _console # noqa: F401
|
|
26
|
+
from . import discover as _discover # noqa: F401
|
|
27
|
+
from . import entity_view as _entity_view # noqa: F401
|
|
28
|
+
from . import metric_view as _metric_view # noqa: F401
|
|
29
|
+
from . import metrics_view as _metrics_view # noqa: F401
|
|
30
|
+
from . import query_view as _query_view # noqa: F401
|
|
31
|
+
from . import rank as _rank # noqa: F401
|
|
32
|
+
from . import release_view as _release_view # noqa: F401
|
|
33
|
+
from . import table as _table # noqa: F401
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"ActionArgument",
|
|
37
|
+
"ActionBinding",
|
|
38
|
+
"ActionSpec",
|
|
39
|
+
"BaseScreen",
|
|
40
|
+
"HelpScreen",
|
|
41
|
+
"format_action_help",
|
|
42
|
+
"get_action",
|
|
43
|
+
"hydrate_labels",
|
|
44
|
+
"label_for",
|
|
45
|
+
"list_actions",
|
|
46
|
+
"parse_action_kwargs",
|
|
47
|
+
"register",
|
|
48
|
+
"resource_type_for_id",
|
|
49
|
+
]
|