jstdata 0.1.0__tar.gz → 0.2.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 (33) hide show
  1. jstdata-0.2.0/PKG-INFO +227 -0
  2. jstdata-0.2.0/README.md +196 -0
  3. jstdata-0.2.0/jstdata/__init__.py +13 -0
  4. jstdata-0.2.0/jstdata/agent_guide.py +530 -0
  5. jstdata-0.2.0/jstdata/cli.py +682 -0
  6. jstdata-0.2.0/jstdata/client.py +543 -0
  7. jstdata-0.2.0/jstdata/models.py +161 -0
  8. jstdata-0.2.0/jstdata/session.py +251 -0
  9. jstdata-0.2.0/jstdata/utils.py +103 -0
  10. jstdata-0.2.0/jstdata/workflows/__init__.py +88 -0
  11. jstdata-0.2.0/jstdata/workflows/base.py +356 -0
  12. jstdata-0.2.0/jstdata/workflows/bundled/__init__.py +1 -0
  13. jstdata-0.2.0/jstdata/workflows/bundled/tutorial.yaml +14 -0
  14. jstdata-0.2.0/jstdata/workflows/bundled/tutorial_script.yaml +45 -0
  15. jstdata-0.2.0/jstdata/workflows/chart.py +357 -0
  16. jstdata-0.2.0/jstdata/workflows/console.py +560 -0
  17. jstdata-0.2.0/jstdata/workflows/discover.py +502 -0
  18. jstdata-0.2.0/jstdata/workflows/export.py +171 -0
  19. jstdata-0.2.0/jstdata/workflows/find.py +386 -0
  20. jstdata-0.2.0/jstdata/workflows/host.py +255 -0
  21. jstdata-0.2.0/jstdata/workflows/rank.py +658 -0
  22. jstdata-0.2.0/jstdata/workflows/session_manager.py +277 -0
  23. jstdata-0.2.0/jstdata/workflows/store.py +308 -0
  24. jstdata-0.2.0/jstdata/workflows/tutorial.py +163 -0
  25. jstdata-0.2.0/jstdata/workflows/tutorial_host.py +178 -0
  26. {jstdata-0.1.0 → jstdata-0.2.0}/pyproject.toml +10 -5
  27. jstdata-0.1.0/PKG-INFO +0 -60
  28. jstdata-0.1.0/README.md +0 -33
  29. jstdata-0.1.0/jstdata/__init__.py +0 -1
  30. jstdata-0.1.0/jstdata/cli.py +0 -213
  31. jstdata-0.1.0/jstdata/client.py +0 -258
  32. jstdata-0.1.0/jstdata/utils.py +0 -58
  33. {jstdata-0.1.0 → jstdata-0.2.0}/LICENSE +0 -0
jstdata-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,227 @@
1
+ Metadata-Version: 2.4
2
+ Name: jstdata
3
+ Version: 0.2.0
4
+ Summary: Python API, CLI, and interactive workflows 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: Topic :: Software Development :: Libraries :: Python Modules
20
+ Requires-Dist: click (>=8.2.1,<9.0.0)
21
+ Requires-Dist: pandas (>=2.3.1,<3.0.0)
22
+ Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
23
+ Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
24
+ Requires-Dist: requests (>=2.31.0,<3.0.0)
25
+ Requires-Dist: tabulate (>=0.9.0,<0.10.0)
26
+ Requires-Dist: textual (>=1.0.0,<2.0.0)
27
+ Project-URL: Homepage, https://github.com/Jefferson-Street-Technologies/jstdata
28
+ Project-URL: Repository, https://github.com/Jefferson-Street-Technologies/jstdata
29
+ Description-Content-Type: text/markdown
30
+
31
+ # Jefferson Street Data (jstdata)
32
+
33
+ A Python interface and Research OS for the Jefferson Street financial and economic data API.
34
+
35
+ ## Design Philosophy: From Filing Cabinet to Knowledge Graph
36
+
37
+ `jstdata` is built to minimize the friction between human thought and actionable data.
38
+
39
+ - **Series-First**: The individual data series is the primary resource, carrying its own metadata (frequency, units, source).
40
+ - **Entity Graph**: Entities are nodes in a relational graph — walk from a company to its SIC, a security ticker, or a geography.
41
+ - **Taxonomies**: Named populations (`country`, `sec-central-index-key`, …) scope search, query, and ranking.
42
+ - **Intent over IDs**: CLI and Python favor fuzzy search over memorizing slugs; always resolve before querying.
43
+ - **Sessions & workflows**: Stage resolved ids in a session JSON; compose interactive steps in the shell and save them as named workflows.
44
+ - **Reproducible Discovery**: High-speed discovery in the TUI transitions into immutable Python / CLI snippets.
45
+
46
+ ---
47
+
48
+ ## Installation
49
+
50
+ ```bash
51
+ # Using poetry
52
+ poetry install
53
+
54
+ # Manual install
55
+ pip install .
56
+ ```
57
+
58
+ ## Authentication & Configuration
59
+
60
+ ### Quick Start (CLI)
61
+
62
+ ```bash
63
+ jst login
64
+ ```
65
+
66
+ Credentials are saved to `~/.jstdata/config.json` with secure permissions.
67
+
68
+ ### Environment Variables
69
+
70
+ These take precedence over the config file:
71
+
72
+ ```bash
73
+ export JSTDATA_API_KEY="your-api-key-here"
74
+ # Optional: export JSTDATA_BASE_URL="https://api.jeffersonst.io"
75
+ ```
76
+
77
+ ### Managing Configuration
78
+
79
+ ```bash
80
+ jst config show
81
+ jst config show --verbose
82
+ jst config set api_key XXX
83
+ ```
84
+
85
+ ## Interactive investigation (`jst run`)
86
+
87
+ Compose TUI **steps** in the shell. Steps share one **Session** (staged metrics /
88
+ entities / series + query filters) for the lifetime of the run.
89
+
90
+ ```bash
91
+ # Catalog search → stage entities/metrics/series
92
+ jst run console
93
+
94
+ # Scope to a taxonomy and resource type
95
+ jst run console --taxonomy sec-central-index-key --resource-type entity
96
+
97
+ # Filter entities by typed graph edges (repeatable; OR'd)
98
+ jst run console --relation classified_as:sic:7372 --resource-type entity
99
+
100
+ # Chain steps
101
+ jst run console --taxonomy country : discover --mode union : rank --taxonomy country
102
+
103
+ # Preload a session JSON; set default export path
104
+ jst run --session labor.json --output out.json rank --taxonomy country
105
+ ```
106
+
107
+ Built-in steps:
108
+
109
+ | Step | Role |
110
+ |------|------|
111
+ | `console` | Search catalog; stage into the session |
112
+ | `discover` | Find metrics for session entities; preview coverage |
113
+ | `rank` | Leaderboard entities for a session metric |
114
+
115
+ Host keys (every step): `s` session · `f` find · `e` export · `n`/`p` next/prev · `?` step help · `q` quit.
116
+
117
+ ```bash
118
+ jst steps
119
+ jst step console
120
+ jst step rank --json
121
+ ```
122
+
123
+ ### Saved workflows
124
+
125
+ Persist step pipelines (not session contents) under `~/.jstdata/workflows/`:
126
+
127
+ ```bash
128
+ jst workflow create --id gdp-rank --description "GDP board" -- \
129
+ console --taxonomy country : rank --taxonomy country
130
+
131
+ jst workflow ls
132
+ jst workflow run gdp-rank --session labor.json
133
+ jst workflow rm gdp-rank
134
+ ```
135
+
136
+ (`jst workflows` remains a compatibility alias.)
137
+
138
+ ### Tutorial
139
+
140
+ ```bash
141
+ jst tutorial
142
+ # same as: jst workflow run tutorial
143
+ ```
144
+
145
+ ### Agents
146
+
147
+ ```bash
148
+ jst agent-guide
149
+ ```
150
+
151
+ Prints a version-tied operating manual (hard rules, modes, recipes, and the live
152
+ CLI/step reference). Prefer it over guessing command shapes or inventing ids.
153
+
154
+ ## The Scriptable CLI (`jst`)
155
+
156
+ Pipe-friendly commands for automation and quick extraction.
157
+
158
+ ```bash
159
+ # Fuzzy / set search (omit QUERY to list the matching set)
160
+ jst metric search "defense spending" --taxonomy country --limit 20 --format json
161
+ jst entity search --relation classified_as:sic:3674 --limit 50 --format json
162
+ jst entity search --metric gdp --metric cpi --mode intersect --format json
163
+
164
+ # Taxonomies
165
+ jst taxonomy ls --format json
166
+ jst taxonomy entities country --limit 20 --format json
167
+
168
+ # Bounded cross-sectional query (head/tail per series)
169
+ jst query --metric inflation --entity "United States" --frequency Monthly --tail 20
170
+ jst query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json
171
+
172
+ # Deep history for one known series
173
+ jst series observations ABC123 --start-date 2000-01-01 --limit 1000
174
+
175
+ # Entity graph
176
+ jst entity relations cik:1045810 --format pretty
177
+ ```
178
+
179
+ ## The Python API
180
+
181
+ ```python
182
+ from jstdata import JSTDataClient, Session
183
+
184
+ client = JSTDataClient()
185
+
186
+ # Cross-sectional observations (bounded per series)
187
+ df = client.query_df(
188
+ metric="gross-domestic-product",
189
+ entity=["usa", "gbr"],
190
+ tail=20,
191
+ )
192
+
193
+ # Rank a taxonomy population by latest value
194
+ top = client.query(
195
+ metric="gross-domestic-product",
196
+ taxonomy="country",
197
+ frequency="Annual",
198
+ tail=1,
199
+ sort_by="value",
200
+ limit=50,
201
+ )
202
+
203
+ # Relation-scoped entity search (OR when multiple)
204
+ entities = client.search_entities(
205
+ relation=["classified_as:sic:7372", "classified_as:sic:5961"],
206
+ taxonomy="sec-central-index-key",
207
+ limit=50,
208
+ )
209
+
210
+ # Deep history for one series
211
+ obs = client.get_series_observations("ABC123", start_date="2000-01-01")
212
+
213
+ # Stage intent for a later `jst run` / `jst workflow run`
214
+ session = Session(
215
+ metric=["gross-domestic-product"],
216
+ taxonomy="country",
217
+ tail=1,
218
+ sort_by="value",
219
+ )
220
+ session.save("labor.json")
221
+ ```
222
+
223
+ ## Extending the product
224
+
225
+ See [AGENTS.md](AGENTS.md) for how steps, the host, and saved workflows are
226
+ structured when adding new interactive surface area.
227
+
@@ -0,0 +1,196 @@
1
+ # Jefferson Street Data (jstdata)
2
+
3
+ A Python interface and Research OS for the Jefferson Street financial and economic data API.
4
+
5
+ ## Design Philosophy: From Filing Cabinet to Knowledge Graph
6
+
7
+ `jstdata` is built to minimize the friction between human thought and actionable data.
8
+
9
+ - **Series-First**: The individual data series is the primary resource, carrying its own metadata (frequency, units, source).
10
+ - **Entity Graph**: Entities are nodes in a relational graph — walk from a company to its SIC, a security ticker, or a geography.
11
+ - **Taxonomies**: Named populations (`country`, `sec-central-index-key`, …) scope search, query, and ranking.
12
+ - **Intent over IDs**: CLI and Python favor fuzzy search over memorizing slugs; always resolve before querying.
13
+ - **Sessions & workflows**: Stage resolved ids in a session JSON; compose interactive steps in the shell and save them as named workflows.
14
+ - **Reproducible Discovery**: High-speed discovery in the TUI transitions into immutable Python / CLI snippets.
15
+
16
+ ---
17
+
18
+ ## Installation
19
+
20
+ ```bash
21
+ # Using poetry
22
+ poetry install
23
+
24
+ # Manual install
25
+ pip install .
26
+ ```
27
+
28
+ ## Authentication & Configuration
29
+
30
+ ### Quick Start (CLI)
31
+
32
+ ```bash
33
+ jst login
34
+ ```
35
+
36
+ Credentials are saved to `~/.jstdata/config.json` with secure permissions.
37
+
38
+ ### Environment Variables
39
+
40
+ These take precedence over the config file:
41
+
42
+ ```bash
43
+ export JSTDATA_API_KEY="your-api-key-here"
44
+ # Optional: export JSTDATA_BASE_URL="https://api.jeffersonst.io"
45
+ ```
46
+
47
+ ### Managing Configuration
48
+
49
+ ```bash
50
+ jst config show
51
+ jst config show --verbose
52
+ jst config set api_key XXX
53
+ ```
54
+
55
+ ## Interactive investigation (`jst run`)
56
+
57
+ Compose TUI **steps** in the shell. Steps share one **Session** (staged metrics /
58
+ entities / series + query filters) for the lifetime of the run.
59
+
60
+ ```bash
61
+ # Catalog search → stage entities/metrics/series
62
+ jst run console
63
+
64
+ # Scope to a taxonomy and resource type
65
+ jst run console --taxonomy sec-central-index-key --resource-type entity
66
+
67
+ # Filter entities by typed graph edges (repeatable; OR'd)
68
+ jst run console --relation classified_as:sic:7372 --resource-type entity
69
+
70
+ # Chain steps
71
+ jst run console --taxonomy country : discover --mode union : rank --taxonomy country
72
+
73
+ # Preload a session JSON; set default export path
74
+ jst run --session labor.json --output out.json rank --taxonomy country
75
+ ```
76
+
77
+ Built-in steps:
78
+
79
+ | Step | Role |
80
+ |------|------|
81
+ | `console` | Search catalog; stage into the session |
82
+ | `discover` | Find metrics for session entities; preview coverage |
83
+ | `rank` | Leaderboard entities for a session metric |
84
+
85
+ Host keys (every step): `s` session · `f` find · `e` export · `n`/`p` next/prev · `?` step help · `q` quit.
86
+
87
+ ```bash
88
+ jst steps
89
+ jst step console
90
+ jst step rank --json
91
+ ```
92
+
93
+ ### Saved workflows
94
+
95
+ Persist step pipelines (not session contents) under `~/.jstdata/workflows/`:
96
+
97
+ ```bash
98
+ jst workflow create --id gdp-rank --description "GDP board" -- \
99
+ console --taxonomy country : rank --taxonomy country
100
+
101
+ jst workflow ls
102
+ jst workflow run gdp-rank --session labor.json
103
+ jst workflow rm gdp-rank
104
+ ```
105
+
106
+ (`jst workflows` remains a compatibility alias.)
107
+
108
+ ### Tutorial
109
+
110
+ ```bash
111
+ jst tutorial
112
+ # same as: jst workflow run tutorial
113
+ ```
114
+
115
+ ### Agents
116
+
117
+ ```bash
118
+ jst agent-guide
119
+ ```
120
+
121
+ Prints a version-tied operating manual (hard rules, modes, recipes, and the live
122
+ CLI/step reference). Prefer it over guessing command shapes or inventing ids.
123
+
124
+ ## The Scriptable CLI (`jst`)
125
+
126
+ Pipe-friendly commands for automation and quick extraction.
127
+
128
+ ```bash
129
+ # Fuzzy / set search (omit QUERY to list the matching set)
130
+ jst metric search "defense spending" --taxonomy country --limit 20 --format json
131
+ jst entity search --relation classified_as:sic:3674 --limit 50 --format json
132
+ jst entity search --metric gdp --metric cpi --mode intersect --format json
133
+
134
+ # Taxonomies
135
+ jst taxonomy ls --format json
136
+ jst taxonomy entities country --limit 20 --format json
137
+
138
+ # Bounded cross-sectional query (head/tail per series)
139
+ jst query --metric inflation --entity "United States" --frequency Monthly --tail 20
140
+ jst query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json
141
+
142
+ # Deep history for one known series
143
+ jst series observations ABC123 --start-date 2000-01-01 --limit 1000
144
+
145
+ # Entity graph
146
+ jst entity relations cik:1045810 --format pretty
147
+ ```
148
+
149
+ ## The Python API
150
+
151
+ ```python
152
+ from jstdata import JSTDataClient, Session
153
+
154
+ client = JSTDataClient()
155
+
156
+ # Cross-sectional observations (bounded per series)
157
+ df = client.query_df(
158
+ metric="gross-domestic-product",
159
+ entity=["usa", "gbr"],
160
+ tail=20,
161
+ )
162
+
163
+ # Rank a taxonomy population by latest value
164
+ top = client.query(
165
+ metric="gross-domestic-product",
166
+ taxonomy="country",
167
+ frequency="Annual",
168
+ tail=1,
169
+ sort_by="value",
170
+ limit=50,
171
+ )
172
+
173
+ # Relation-scoped entity search (OR when multiple)
174
+ entities = client.search_entities(
175
+ relation=["classified_as:sic:7372", "classified_as:sic:5961"],
176
+ taxonomy="sec-central-index-key",
177
+ limit=50,
178
+ )
179
+
180
+ # Deep history for one series
181
+ obs = client.get_series_observations("ABC123", start_date="2000-01-01")
182
+
183
+ # Stage intent for a later `jst run` / `jst workflow run`
184
+ session = Session(
185
+ metric=["gross-domestic-product"],
186
+ taxonomy="country",
187
+ tail=1,
188
+ sort_by="value",
189
+ )
190
+ session.save("labor.json")
191
+ ```
192
+
193
+ ## Extending the product
194
+
195
+ See [AGENTS.md](AGENTS.md) for how steps, the host, and saved workflows are
196
+ 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 .session import Session
4
+
5
+ __all__ = [
6
+ "JSTDataClient",
7
+ "Entity",
8
+ "Metric",
9
+ "Series",
10
+ "Observation",
11
+ "Taxonomy",
12
+ "Session",
13
+ ]