Skip to main content

Jefferson Street Data (jstdata)

A Python interface and Investigation IDE for the Jefferson Street financial and economic data API.

Design Philosophy: From Filing Cabinet to Knowledge Graph

jstdata is built to minimize the friction between human thought and actionable data.

  • Series-First: The individual data series is the primary resource, carrying its own metadata (frequency, units, source).
  • Entity Graph: Entities are nodes in a relational graph — walk from a company to its SIC, a security ticker, or a geography.
  • Taxonomies: Named populations (country, sec-central-index-key, …) scope search, query, and ranking.
  • Intent over IDs: CLI and Python favor fuzzy search over memorizing slugs; always resolve before querying.
  • Investigations: Durable research artifacts — one workspace (staged ids), saved queries (cartesian metric × entity), and a tree of actions (analytical TUIs).
  • Reproducible Discovery: High-speed discovery in the TUI transitions into immutable Python / CLI snippets.

Installation

# Using poetry
poetry install

# Manual install
pip install .

Authentication & Configuration

Quick Start (CLI)

jst login

Credentials are saved to ~/.jstdata/config.json with secure permissions.

Environment Variables

These take precedence over the config file:

export JSTDATA_API_KEY="your-api-key-here"
# Optional: export JSTDATA_BASE_URL="https://api.jeffersonst.io"

Managing Configuration

jst config show
jst config show --verbose
jst config set api_key XXX

Investigations

An investigation is the durable research unit: YAML under ~/.jstdata/investigations/ with one workspace (staged metrics / entities / series), saved queries (cartesian metric × entity against GET /query), and a tree of actions (reusable TUI screens).

jst new --id housing-slowdown
jst open housing-slowdown
jst ls
jst                 # reopen the active investigation (Untitled if none)

# Saved queries (cartesian metric × entity)
jst query add --metric gdp --entity france --entity usa --name "FR vs US"
jst query inspect 1
jst query run 1 --format json

# Add actions (children of the active action unless --parent is set)
jst action add console --args '{"taxonomy":"country","resource_type":"entity"}'
jst action add discover --args '{"mode":"union"}' --activate
jst action add rank --args '{"taxonomy":"country"}'
jst action rm 2 --force

Built-in actions:

Action Role
console Search catalog; stage into the workspace
discover Find metrics for workspace entities; preview coverage
rank Leaderboard entities for a workspace metric
jst action ls
jst action show console
jst action show rank --json

Inside the TUI: g returns Home (Recent / Search / Actions / Workspace / Queries). esc goes back one level. : opens the command palette (fuzzy destinations and saved queries, plus :workspace, :search metric gdp, :query, :rename, :publish, :add, :rm, :tutorial) · n/p (↑/↓) siblings · N/P (→/←) depth · space collects into the workspace · t tutorials · ? help · q quit.

Active context lives in ~/.jstdata/.active.yaml.

Publish and clone

Publishing turns an investigation into a web page that anyone with the link can open: its queries, annotations and results, with each observation's provenance and a CSV download. Signed-in visitors can refresh the results with their own API key. The website runs the queries with yours when you publish.

When you publish, a draft of the page opens first: the title, a one-line description, an overview, and a note under each query's charts, all in one Markdown document laid out like the page. Fill it in and press Ctrl+S; the text is saved to the investigation, and you confirm before anything is shared.

jst publish                  # the active investigation: draft, confirm, publish
jst publish plain-bagel --no-edit   # skip the draft, use the saved text
jst publish plain-bagel --yes       # no draft, no confirmation (scripts)
jst publish plain-bagel --update    # fix the text on the existing link
jst publish plain-bagel --new       # always make a new link
jst clone https://www.jeffersonst.io/p/AbCdEf1234   # copy one into your environment

In the TUI, :publish does the same and shows the link, with c to copy it and o to open it.

Publishing an investigation again asks whether to update its existing link or make a new one. Updating replaces the page's text (title, description, overview, query names and notes) on the same link and keeps its results; the page shows "Edited". If you changed the queries themselves, publish a new link instead, so the results always match the page. jst remembers your links in ~/.jstdata/publications.json. jst clone saves the published queries and annotations as a new local investigation (adding -clone if the id is taken) and needs no API key.

Annotations (investigation and query) are Markdown; see docs/annotations.md for the format and what's planned.

The website defaults to https://www.jeffersonst.io; point at another with JSTDATA_SITE_URL or jst config set site_url <url>.

Tutorials

The first time you open the TUI, a tutorial menu appears. Pick one, or press esc to explore on your own; t (or :tutorial) brings the menu back any time. A coach bar docked at the top explains each step and names the exact keys to press, and advances as you do them. Each tutorial runs in its own investigation (tutorial-<id>); leaving it reopens yours.

Tutorial Level What you do
big-tech-gross-profit Beginner · guided Compare Apple, Microsoft, Amazon: Home → Search → collect → metric view → Workspace → Query → chart
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
g7-government-debt Advanced · open Research question on G7 government debt vs inflation; the coach only checks progress

A tip box across the top of each screen tells you what to press there (e.g. Press "2" to open Search). Hide it with its "✕ hide tips" or :tips off; :tips on brings it back.

Progress (menu seen, tutorials completed, tips on/off) lives in ~/.jstdata/onboarding.json. First jst / jst new / jst open also bootstraps the bundled tutorial (welcome) and plain-bagel demo investigations when none exist.

Agents

jst agent-guide
jst agent install          # Codex, Claude Code, Cursor (~/.agents, ~/.claude, ~/.cursor)
jst agent install cursor

jst agent-guide is the versioned operating manual (hard rules, modes, recipes, and the live CLI/action reference). Prefer it over guessing command shapes or inventing ids. jst agent install copies a tiny pointer skill (run jst agent-guide) into user-level skill directories. Discovery is not guaranteed — if the agent does not pick it up, say: Use the jst skill. Then run jst agent-guide and follow it.

The Scriptable API CLI (jst api)

Pipe-friendly resource commands for automation and quick extraction. Nested under jst api so they stay distinct from investigation commands.

# Fuzzy / set search (omit QUERY to list the matching set)
jst api metric search "defense spending" --taxonomy country --limit 20 --format json
jst api entity search --relation classified_as:sic:3674 --limit 50 --format json
jst api entity search --metric gdp --metric cpi --mode intersect --format json

# Taxonomies
jst api taxonomy ls --format json
jst api taxonomy entities country --limit 20 --format json

# Bounded cross-sectional query (head/tail per series)
jst api query --metric inflation --entity "United States" --frequency Monthly --tail 20
jst api query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json

# Deep history for one known series
jst api series observations ABC123 --start-date 2000-01-01 --limit 1000

# Entity graph
jst api entity relations cik:1045810 --format pretty

The Python API

from jstdata import JSTDataClient
from jstdata.investigation import Workspace

client = JSTDataClient()

# Cross-sectional observations (bounded per series)
df = client.query_df(
    metric="gross-domestic-product",
    entity=["usa", "gbr"],
    tail=20,
)

# Rank a taxonomy population by latest value
top = client.query(
    metric="gross-domestic-product",
    taxonomy="country",
    frequency="Annual",
    tail=1,
    sort_by="value",
    limit=50,
)

# Relation-scoped entity search (OR when multiple)
entities = client.search_entities(
    relation=["classified_as:sic:7372", "classified_as:sic:5961"],
    taxonomy="sec-central-index-key",
    limit=50,
)

# Deep history for one series
obs = client.get_series_observations("ABC123", start_date="2000-01-01")

# Workspace helpers project the same selectors as jst api query
ws = Workspace(
    metric=["gross-domestic-product"],
    taxonomy="country",
    tail=1,
    sort_by="value",
)
print(ws.to_cli())
df = ws.execute_df(client)

Extending the product

See AGENTS.md for how investigations, workspaces, and actions are structured when adding new interactive surface area.

Metadata

Release files for jstdata 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jstdata 0.5.0
File Size Uploaded Provenance Actions
jstdata-0.5.0.tar.gz 179.6 kB Without provenance Details for jstdata-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jstdata 0.5.0
File Interpreter ABI Platform Actions
jstdata-0.5.0-py3-none-any.whl Python 3 none any Details for jstdata-0.5.0-py3-none-any.whl

Total release size: 392.7 kB

Release files / jstdata-0.5.0.tar.gz

Download URL jstdata-0.5.0.tar.gz
Size 179.6 kB
Tags Source
SHA-256 checksum
How to use checksums
812ef7631ff361b8401e4ce684f8ebccbc807715878367292ea8b2acd46d812a
BLAKE2b-256 checksum
How to use checksums
c92372bca8782b630f83365feeec2941c2d4dbdddc304410509316fbbf930ecb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.11.18 Linux/7.0.0-1016-aws

Release files / jstdata-0.5.0-py3-none-any.whl

Download URL jstdata-0.5.0-py3-none-any.whl
Size 213.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b71e598d3905acfce07e9b57a43464ed5274bf30618359db955d91fe5aa67719
BLAKE2b-256 checksum
How to use checksums
57d28fa3ae2bac9dbdc69a079d68e862ded2c489c4a12091acff3703496904f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.11.18 Linux/7.0.0-1016-aws

Security for jstdata 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page