jstdata 0.1.0__tar.gz → 0.3.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.
Files changed (68) hide show
  1. jstdata-0.3.0/PKG-INFO +276 -0
  2. jstdata-0.3.0/README.md +239 -0
  3. jstdata-0.3.0/jstdata/__init__.py +13 -0
  4. jstdata-0.3.0/jstdata/actions/__init__.py +49 -0
  5. jstdata-0.3.0/jstdata/actions/base.py +298 -0
  6. jstdata-0.3.0/jstdata/actions/chart.py +366 -0
  7. jstdata-0.3.0/jstdata/actions/console.py +548 -0
  8. jstdata-0.3.0/jstdata/actions/discover.py +656 -0
  9. jstdata-0.3.0/jstdata/actions/drill.py +137 -0
  10. jstdata-0.3.0/jstdata/actions/entity_view.py +580 -0
  11. jstdata-0.3.0/jstdata/actions/help.py +103 -0
  12. jstdata-0.3.0/jstdata/actions/metric_view.py +536 -0
  13. jstdata-0.3.0/jstdata/actions/metrics_view.py +530 -0
  14. jstdata-0.3.0/jstdata/actions/pagination.py +24 -0
  15. jstdata-0.3.0/jstdata/actions/query_view.py +1465 -0
  16. jstdata-0.3.0/jstdata/actions/rank.py +728 -0
  17. jstdata-0.3.0/jstdata/actions/release_view.py +334 -0
  18. jstdata-0.3.0/jstdata/actions/screen.py +82 -0
  19. jstdata-0.3.0/jstdata/actions/table.py +790 -0
  20. jstdata-0.3.0/jstdata/add_options.py +89 -0
  21. jstdata-0.3.0/jstdata/agent/__init__.py +1 -0
  22. jstdata-0.3.0/jstdata/agent/install.py +55 -0
  23. jstdata-0.3.0/jstdata/agent/skills/jst/SKILL.md +34 -0
  24. jstdata-0.3.0/jstdata/agent_guide.py +632 -0
  25. jstdata-0.3.0/jstdata/cli.py +1157 -0
  26. jstdata-0.3.0/jstdata/client.py +725 -0
  27. jstdata-0.3.0/jstdata/investigation/__init__.py +104 -0
  28. jstdata-0.3.0/jstdata/investigation/active.py +98 -0
  29. jstdata-0.3.0/jstdata/investigation/api.py +477 -0
  30. jstdata-0.3.0/jstdata/investigation/bootstrap.py +96 -0
  31. jstdata-0.3.0/jstdata/investigation/browsers.py +1035 -0
  32. jstdata-0.3.0/jstdata/investigation/bundled/__init__.py +1 -0
  33. jstdata-0.3.0/jstdata/investigation/bundled/plain-bagel.yaml +77 -0
  34. jstdata-0.3.0/jstdata/investigation/bundled/tutorial.yaml +17 -0
  35. jstdata-0.3.0/jstdata/investigation/command_palette.py +438 -0
  36. jstdata-0.3.0/jstdata/investigation/commands.py +502 -0
  37. jstdata-0.3.0/jstdata/investigation/home.py +1320 -0
  38. jstdata-0.3.0/jstdata/investigation/host.py +1757 -0
  39. jstdata-0.3.0/jstdata/investigation/model.py +1071 -0
  40. jstdata-0.3.0/jstdata/investigation/nav.py +617 -0
  41. jstdata-0.3.0/jstdata/investigation/publish_screens.py +145 -0
  42. jstdata-0.3.0/jstdata/investigation/search_drawer.py +467 -0
  43. jstdata-0.3.0/jstdata/investigation/store.py +116 -0
  44. jstdata-0.3.0/jstdata/investigation/workspace_drawer.py +199 -0
  45. jstdata-0.3.0/jstdata/models.py +320 -0
  46. jstdata-0.3.0/jstdata/onboarding/__init__.py +35 -0
  47. jstdata-0.3.0/jstdata/onboarding/tips.py +172 -0
  48. jstdata-0.3.0/jstdata/onboarding/tutorials/big-tech-gross-profit.yaml +70 -0
  49. jstdata-0.3.0/jstdata/onboarding/tutorials/g7-government-debt.yaml +38 -0
  50. jstdata-0.3.0/jstdata/onboarding/tutorials/gulf-oil-exports.yaml +59 -0
  51. jstdata-0.3.0/jstdata/onboarding/tutorials.py +310 -0
  52. jstdata-0.3.0/jstdata/onboarding/ui.py +419 -0
  53. jstdata-0.3.0/jstdata/preview/__init__.py +74 -0
  54. jstdata-0.3.0/jstdata/preview/data.py +523 -0
  55. jstdata-0.3.0/jstdata/preview/progress.py +124 -0
  56. jstdata-0.3.0/jstdata/preview/render.py +965 -0
  57. jstdata-0.3.0/jstdata/publish.py +238 -0
  58. jstdata-0.3.0/jstdata/resource_cache.py +206 -0
  59. jstdata-0.3.0/jstdata/utils.py +103 -0
  60. jstdata-0.3.0/pyproject.toml +60 -0
  61. jstdata-0.1.0/PKG-INFO +0 -60
  62. jstdata-0.1.0/README.md +0 -33
  63. jstdata-0.1.0/jstdata/__init__.py +0 -1
  64. jstdata-0.1.0/jstdata/cli.py +0 -213
  65. jstdata-0.1.0/jstdata/client.py +0 -258
  66. jstdata-0.1.0/jstdata/utils.py +0 -58
  67. jstdata-0.1.0/pyproject.toml +0 -41
  68. {jstdata-0.1.0 → jstdata-0.3.0}/LICENSE +0 -0
jstdata-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,276 @@
1
+ Metadata-Version: 2.4
2
+ Name: jstdata
3
+ Version: 0.3.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
+ ```bash
148
+ jst publish # the active investigation; asks before sharing
149
+ jst publish plain-bagel --yes
150
+ jst clone https://www.jeffersonst.io/p/AbCdEf1234 # copy one into your environment
151
+ ```
152
+
153
+ In the TUI, `:publish` does the same and shows the link, with `c` to copy it
154
+ and `o` to open it. Each publish makes a new link with the results as of then;
155
+ earlier links don't change. `jst clone` saves the published queries and
156
+ annotations as a new local investigation (adding `-clone` if the id is taken)
157
+ and needs no API key.
158
+
159
+ The website defaults to `https://www.jeffersonst.io`; point at another with
160
+ `JSTDATA_SITE_URL` or `jst config set site_url <url>`.
161
+
162
+ ### Tutorials
163
+
164
+ The first time you open the TUI, a tutorial menu appears. Pick one, or press
165
+ `esc` to explore on your own; `t` (or `:tutorial`) brings the menu back any
166
+ time. A coach bar docked at the top explains each step and names the exact
167
+ keys to press, and advances as you do them. Each tutorial runs in its own
168
+ investigation (`tutorial-<id>`); leaving it reopens yours.
169
+
170
+ | Tutorial | Level | What you do |
171
+ |----------|-------|-------------|
172
+ | `big-tech-gross-profit` | Beginner · guided | Compare Apple, Microsoft, Amazon: Home → Search → collect → metric view → Workspace → Query → chart |
173
+ | `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 |
174
+ | `g7-government-debt` | Advanced · open | Research question on G7 government debt vs inflation; the coach only checks progress |
175
+
176
+ A **tip** box across the top of each screen tells you what to press there
177
+ (e.g. *Press "2" to open Search*). Hide it with its "✕ hide tips" or `:tips off`; `:tips on`
178
+ brings it back.
179
+
180
+ Progress (menu seen, tutorials completed, tips on/off) lives in
181
+ `~/.jstdata/onboarding.json`.
182
+ First `jst` / `jst new` / `jst open` also bootstraps the bundled `tutorial`
183
+ (welcome) and `plain-bagel` demo investigations when none exist.
184
+
185
+ ### Agents
186
+
187
+ ```bash
188
+ jst agent-guide
189
+ jst agent install # Codex, Claude Code, Cursor (~/.agents, ~/.claude, ~/.cursor)
190
+ jst agent install cursor
191
+ ```
192
+
193
+ `jst agent-guide` is the versioned operating manual (hard rules, modes, recipes,
194
+ and the live CLI/action reference). Prefer it over guessing command shapes or
195
+ inventing ids. `jst agent install` copies a tiny pointer skill (`run jst
196
+ agent-guide`) into user-level skill directories. Discovery is not guaranteed —
197
+ if the agent does not pick it up, say: *Use the jst skill. Then run `jst
198
+ agent-guide` and follow it.*
199
+
200
+ ## The Scriptable API CLI (`jst api`)
201
+
202
+ Pipe-friendly resource commands for automation and quick extraction. Nested
203
+ under `jst api` so they stay distinct from investigation commands.
204
+
205
+ ```bash
206
+ # Fuzzy / set search (omit QUERY to list the matching set)
207
+ jst api metric search "defense spending" --taxonomy country --limit 20 --format json
208
+ jst api entity search --relation classified_as:sic:3674 --limit 50 --format json
209
+ jst api entity search --metric gdp --metric cpi --mode intersect --format json
210
+
211
+ # Taxonomies
212
+ jst api taxonomy ls --format json
213
+ jst api taxonomy entities country --limit 20 --format json
214
+
215
+ # Bounded cross-sectional query (head/tail per series)
216
+ jst api query --metric inflation --entity "United States" --frequency Monthly --tail 20
217
+ jst api query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json
218
+
219
+ # Deep history for one known series
220
+ jst api series observations ABC123 --start-date 2000-01-01 --limit 1000
221
+
222
+ # Entity graph
223
+ jst api entity relations cik:1045810 --format pretty
224
+ ```
225
+
226
+ ## The Python API
227
+
228
+ ```python
229
+ from jstdata import JSTDataClient
230
+ from jstdata.investigation import Workspace
231
+
232
+ client = JSTDataClient()
233
+
234
+ # Cross-sectional observations (bounded per series)
235
+ df = client.query_df(
236
+ metric="gross-domestic-product",
237
+ entity=["usa", "gbr"],
238
+ tail=20,
239
+ )
240
+
241
+ # Rank a taxonomy population by latest value
242
+ top = client.query(
243
+ metric="gross-domestic-product",
244
+ taxonomy="country",
245
+ frequency="Annual",
246
+ tail=1,
247
+ sort_by="value",
248
+ limit=50,
249
+ )
250
+
251
+ # Relation-scoped entity search (OR when multiple)
252
+ entities = client.search_entities(
253
+ relation=["classified_as:sic:7372", "classified_as:sic:5961"],
254
+ taxonomy="sec-central-index-key",
255
+ limit=50,
256
+ )
257
+
258
+ # Deep history for one series
259
+ obs = client.get_series_observations("ABC123", start_date="2000-01-01")
260
+
261
+ # Workspace helpers project the same selectors as jst api query
262
+ ws = Workspace(
263
+ metric=["gross-domestic-product"],
264
+ taxonomy="country",
265
+ tail=1,
266
+ sort_by="value",
267
+ )
268
+ print(ws.to_cli())
269
+ df = ws.execute_df(client)
270
+ ```
271
+
272
+ ## Extending the product
273
+
274
+ See [AGENTS.md](AGENTS.md) for how investigations, workspaces, and actions are
275
+ structured when adding new interactive surface area.
276
+
@@ -0,0 +1,239 @@
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
+ ```bash
112
+ jst publish # the active investigation; asks before sharing
113
+ jst publish plain-bagel --yes
114
+ jst clone https://www.jeffersonst.io/p/AbCdEf1234 # copy one into your environment
115
+ ```
116
+
117
+ In the TUI, `:publish` does the same and shows the link, with `c` to copy it
118
+ and `o` to open it. Each publish makes a new link with the results as of then;
119
+ earlier links don't change. `jst clone` saves the published queries and
120
+ annotations as a new local investigation (adding `-clone` if the id is taken)
121
+ and needs no API key.
122
+
123
+ The website defaults to `https://www.jeffersonst.io`; point at another with
124
+ `JSTDATA_SITE_URL` or `jst config set site_url <url>`.
125
+
126
+ ### Tutorials
127
+
128
+ The first time you open the TUI, a tutorial menu appears. Pick one, or press
129
+ `esc` to explore on your own; `t` (or `:tutorial`) brings the menu back any
130
+ time. A coach bar docked at the top explains each step and names the exact
131
+ keys to press, and advances as you do them. Each tutorial runs in its own
132
+ investigation (`tutorial-<id>`); leaving it reopens yours.
133
+
134
+ | Tutorial | Level | What you do |
135
+ |----------|-------|-------------|
136
+ | `big-tech-gross-profit` | Beginner · guided | Compare Apple, Microsoft, Amazon: Home → Search → collect → metric view → Workspace → Query → chart |
137
+ | `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 |
138
+ | `g7-government-debt` | Advanced · open | Research question on G7 government debt vs inflation; the coach only checks progress |
139
+
140
+ A **tip** box across the top of each screen tells you what to press there
141
+ (e.g. *Press "2" to open Search*). Hide it with its "✕ hide tips" or `:tips off`; `:tips on`
142
+ brings it back.
143
+
144
+ Progress (menu seen, tutorials completed, tips on/off) lives in
145
+ `~/.jstdata/onboarding.json`.
146
+ First `jst` / `jst new` / `jst open` also bootstraps the bundled `tutorial`
147
+ (welcome) and `plain-bagel` demo investigations when none exist.
148
+
149
+ ### Agents
150
+
151
+ ```bash
152
+ jst agent-guide
153
+ jst agent install # Codex, Claude Code, Cursor (~/.agents, ~/.claude, ~/.cursor)
154
+ jst agent install cursor
155
+ ```
156
+
157
+ `jst agent-guide` is the versioned operating manual (hard rules, modes, recipes,
158
+ and the live CLI/action reference). Prefer it over guessing command shapes or
159
+ inventing ids. `jst agent install` copies a tiny pointer skill (`run jst
160
+ agent-guide`) into user-level skill directories. Discovery is not guaranteed —
161
+ if the agent does not pick it up, say: *Use the jst skill. Then run `jst
162
+ agent-guide` and follow it.*
163
+
164
+ ## The Scriptable API CLI (`jst api`)
165
+
166
+ Pipe-friendly resource commands for automation and quick extraction. Nested
167
+ under `jst api` so they stay distinct from investigation commands.
168
+
169
+ ```bash
170
+ # Fuzzy / set search (omit QUERY to list the matching set)
171
+ jst api metric search "defense spending" --taxonomy country --limit 20 --format json
172
+ jst api entity search --relation classified_as:sic:3674 --limit 50 --format json
173
+ jst api entity search --metric gdp --metric cpi --mode intersect --format json
174
+
175
+ # Taxonomies
176
+ jst api taxonomy ls --format json
177
+ jst api taxonomy entities country --limit 20 --format json
178
+
179
+ # Bounded cross-sectional query (head/tail per series)
180
+ jst api query --metric inflation --entity "United States" --frequency Monthly --tail 20
181
+ jst api query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json
182
+
183
+ # Deep history for one known series
184
+ jst api series observations ABC123 --start-date 2000-01-01 --limit 1000
185
+
186
+ # Entity graph
187
+ jst api entity relations cik:1045810 --format pretty
188
+ ```
189
+
190
+ ## The Python API
191
+
192
+ ```python
193
+ from jstdata import JSTDataClient
194
+ from jstdata.investigation import Workspace
195
+
196
+ client = JSTDataClient()
197
+
198
+ # Cross-sectional observations (bounded per series)
199
+ df = client.query_df(
200
+ metric="gross-domestic-product",
201
+ entity=["usa", "gbr"],
202
+ tail=20,
203
+ )
204
+
205
+ # Rank a taxonomy population by latest value
206
+ top = client.query(
207
+ metric="gross-domestic-product",
208
+ taxonomy="country",
209
+ frequency="Annual",
210
+ tail=1,
211
+ sort_by="value",
212
+ limit=50,
213
+ )
214
+
215
+ # Relation-scoped entity search (OR when multiple)
216
+ entities = client.search_entities(
217
+ relation=["classified_as:sic:7372", "classified_as:sic:5961"],
218
+ taxonomy="sec-central-index-key",
219
+ limit=50,
220
+ )
221
+
222
+ # Deep history for one series
223
+ obs = client.get_series_observations("ABC123", start_date="2000-01-01")
224
+
225
+ # Workspace helpers project the same selectors as jst api query
226
+ ws = Workspace(
227
+ metric=["gross-domestic-product"],
228
+ taxonomy="country",
229
+ tail=1,
230
+ sort_by="value",
231
+ )
232
+ print(ws.to_cli())
233
+ df = ws.execute_df(client)
234
+ ```
235
+
236
+ ## Extending the product
237
+
238
+ See [AGENTS.md](AGENTS.md) for how investigations, workspaces, and actions are
239
+ structured when adding new interactive surface area.
@@ -0,0 +1,13 @@
1
+ from .client import JSTDataClient
2
+ from .models import Entity, Metric, Series, Observation, Taxonomy
3
+ from .investigation.model import Workspace
4
+
5
+ __all__ = [
6
+ "JSTDataClient",
7
+ "Entity",
8
+ "Metric",
9
+ "Series",
10
+ "Observation",
11
+ "Taxonomy",
12
+ "Workspace",
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
+ ]