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.
Files changed (80) hide show
  1. jstdata-0.4.0/PKG-INFO +285 -0
  2. jstdata-0.4.0/README.md +248 -0
  3. {jstdata-0.2.0 → jstdata-0.4.0}/jstdata/__init__.py +2 -2
  4. jstdata-0.4.0/jstdata/actions/__init__.py +49 -0
  5. jstdata-0.4.0/jstdata/actions/base.py +298 -0
  6. {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/chart.py +18 -9
  7. {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/console.py +57 -69
  8. {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/discover.py +242 -88
  9. jstdata-0.4.0/jstdata/actions/drill.py +137 -0
  10. jstdata-0.4.0/jstdata/actions/entity_view.py +580 -0
  11. jstdata-0.4.0/jstdata/actions/help.py +103 -0
  12. jstdata-0.4.0/jstdata/actions/metric_view.py +536 -0
  13. jstdata-0.4.0/jstdata/actions/metrics_view.py +530 -0
  14. jstdata-0.4.0/jstdata/actions/pagination.py +24 -0
  15. jstdata-0.4.0/jstdata/actions/query_view.py +1465 -0
  16. {jstdata-0.2.0/jstdata/workflows → jstdata-0.4.0/jstdata/actions}/rank.py +144 -74
  17. jstdata-0.4.0/jstdata/actions/release_view.py +334 -0
  18. jstdata-0.4.0/jstdata/actions/screen.py +82 -0
  19. jstdata-0.4.0/jstdata/actions/table.py +790 -0
  20. jstdata-0.4.0/jstdata/add_options.py +89 -0
  21. jstdata-0.4.0/jstdata/agent/__init__.py +1 -0
  22. jstdata-0.4.0/jstdata/agent/install.py +55 -0
  23. jstdata-0.4.0/jstdata/agent/skills/jst/SKILL.md +34 -0
  24. jstdata-0.4.0/jstdata/agent_guide.py +632 -0
  25. jstdata-0.4.0/jstdata/cli.py +1183 -0
  26. {jstdata-0.2.0 → jstdata-0.4.0}/jstdata/client.py +210 -28
  27. jstdata-0.4.0/jstdata/investigation/__init__.py +104 -0
  28. jstdata-0.4.0/jstdata/investigation/active.py +98 -0
  29. jstdata-0.4.0/jstdata/investigation/api.py +477 -0
  30. jstdata-0.4.0/jstdata/investigation/bootstrap.py +96 -0
  31. jstdata-0.4.0/jstdata/investigation/browsers.py +945 -0
  32. jstdata-0.4.0/jstdata/investigation/bundled/__init__.py +1 -0
  33. jstdata-0.4.0/jstdata/investigation/bundled/plain-bagel.yaml +77 -0
  34. jstdata-0.4.0/jstdata/investigation/bundled/tutorial.yaml +17 -0
  35. jstdata-0.4.0/jstdata/investigation/command_palette.py +438 -0
  36. jstdata-0.4.0/jstdata/investigation/commands.py +502 -0
  37. jstdata-0.4.0/jstdata/investigation/home.py +1320 -0
  38. jstdata-0.4.0/jstdata/investigation/host.py +1812 -0
  39. jstdata-0.4.0/jstdata/investigation/model.py +1071 -0
  40. jstdata-0.4.0/jstdata/investigation/nav.py +617 -0
  41. jstdata-0.4.0/jstdata/investigation/publish_screens.py +242 -0
  42. jstdata-0.4.0/jstdata/investigation/search_drawer.py +467 -0
  43. jstdata-0.4.0/jstdata/investigation/store.py +116 -0
  44. jstdata-0.4.0/jstdata/investigation/workspace_drawer.py +199 -0
  45. jstdata-0.4.0/jstdata/models.py +320 -0
  46. jstdata-0.4.0/jstdata/onboarding/__init__.py +35 -0
  47. jstdata-0.4.0/jstdata/onboarding/tips.py +172 -0
  48. jstdata-0.4.0/jstdata/onboarding/tutorials/big-tech-gross-profit.yaml +70 -0
  49. jstdata-0.4.0/jstdata/onboarding/tutorials/g7-government-debt.yaml +38 -0
  50. jstdata-0.4.0/jstdata/onboarding/tutorials/gulf-oil-exports.yaml +59 -0
  51. jstdata-0.4.0/jstdata/onboarding/tutorials.py +310 -0
  52. jstdata-0.4.0/jstdata/onboarding/ui.py +419 -0
  53. jstdata-0.4.0/jstdata/preview/__init__.py +74 -0
  54. jstdata-0.4.0/jstdata/preview/data.py +523 -0
  55. jstdata-0.4.0/jstdata/preview/progress.py +124 -0
  56. jstdata-0.4.0/jstdata/preview/render.py +965 -0
  57. jstdata-0.4.0/jstdata/publish.py +238 -0
  58. jstdata-0.4.0/jstdata/publish_draft.py +166 -0
  59. jstdata-0.4.0/jstdata/resource_cache.py +206 -0
  60. {jstdata-0.2.0 → jstdata-0.4.0}/pyproject.toml +19 -5
  61. jstdata-0.2.0/PKG-INFO +0 -227
  62. jstdata-0.2.0/README.md +0 -196
  63. jstdata-0.2.0/jstdata/agent_guide.py +0 -530
  64. jstdata-0.2.0/jstdata/cli.py +0 -682
  65. jstdata-0.2.0/jstdata/models.py +0 -161
  66. jstdata-0.2.0/jstdata/session.py +0 -251
  67. jstdata-0.2.0/jstdata/workflows/__init__.py +0 -88
  68. jstdata-0.2.0/jstdata/workflows/base.py +0 -356
  69. jstdata-0.2.0/jstdata/workflows/bundled/__init__.py +0 -1
  70. jstdata-0.2.0/jstdata/workflows/bundled/tutorial.yaml +0 -14
  71. jstdata-0.2.0/jstdata/workflows/bundled/tutorial_script.yaml +0 -45
  72. jstdata-0.2.0/jstdata/workflows/export.py +0 -171
  73. jstdata-0.2.0/jstdata/workflows/find.py +0 -386
  74. jstdata-0.2.0/jstdata/workflows/host.py +0 -255
  75. jstdata-0.2.0/jstdata/workflows/session_manager.py +0 -277
  76. jstdata-0.2.0/jstdata/workflows/store.py +0 -308
  77. jstdata-0.2.0/jstdata/workflows/tutorial.py +0 -163
  78. jstdata-0.2.0/jstdata/workflows/tutorial_host.py +0 -178
  79. {jstdata-0.2.0 → jstdata-0.4.0}/LICENSE +0 -0
  80. {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
+
@@ -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 .session import Session
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
- "Session",
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
+ ]