jstdata 0.2.0__py3-none-any.whl

jstdata/workflows/tutorial.py

@@ -0,0 +1,163 @@
+"""Interactive tutorial coach for the bundled ``tutorial`` workflow."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib.resources import files
+from typing import Any, Callable, Mapping, Optional
+
+import yaml
+
+from ..client import JSTDataClient
+from ..session import Session
+from .base import default_session_path
+from .export import ExportModal
+from .store import (
+    TUTORIAL_WORKFLOW_ID,
+    load_workflow,
+    resolve_saved_workflow,
+)
+
+_SCRIPT_PATH = "tutorial_script.yaml"
+
+
+@dataclass(frozen=True)
+class TutorialPhase:
+    text: str
+    step_index: Optional[int] = None
+    until: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TutorialPhase:
+        until = data.get("until") or {}
+        if not isinstance(until, dict):
+            raise ValueError("Tutorial phase 'until' must be a mapping.")
+        step_index = data.get("step_index")
+        if step_index is not None:
+            step_index = int(step_index)
+        return cls(
+            text=str(data.get("text") or "").strip(),
+            step_index=step_index,
+            until=until,
+        )
+
+
+@dataclass
+class TutorialCoach:
+    phases: tuple[TutorialPhase, ...]
+    phase_index: int = 0
+
+    @classmethod
+    def load(cls) -> TutorialCoach:
+        raw = files("jstdata.workflows.bundled").joinpath(_SCRIPT_PATH).read_text(
+            encoding="utf-8"
+        )
+        data = yaml.safe_load(raw) or {}
+        items = data.get("phases") or []
+        if not items:
+            raise ValueError("Tutorial script has no phases.")
+        return cls(phases=tuple(TutorialPhase.from_dict(p) for p in items))
+
+    @property
+    def is_complete(self) -> bool:
+        return self.phase_index >= len(self.phases)
+
+    @property
+    def current_phase(self) -> Optional[TutorialPhase]:
+        if self.is_complete:
+            return None
+        return self.phases[self.phase_index]
+
+    @property
+    def progress_label(self) -> str:
+        total = len(self.phases)
+        current = min(self.phase_index + 1, total)
+        return f"Step {current} / {total}"
+
+    def _phase_matches(
+        self,
+        phase: TutorialPhase,
+        session: Session,
+        step_index: int,
+        action: Optional[str],
+    ) -> bool:
+        until = phase.until or {}
+        if until.get("done"):
+            return False
+        if until.get("auto"):
+            return True
+        if phase.step_index is not None and phase.step_index != step_index:
+            return False
+        if "session_entity_count" in until:
+            needed = int(until["session_entity_count"])
+            return len(session.entity) >= needed
+        if "session_metric_count" in until:
+            needed = int(until["session_metric_count"])
+            return len(session.metric) >= needed
+        if "action" in until:
+            return action == until["action"]
+        return False
+
+    def maybe_advance(
+        self,
+        session: Session,
+        step_index: int,
+        action: Optional[str] = None,
+    ) -> bool:
+        """Advance when the current phase's completion rule is satisfied."""
+        if self.is_complete:
+            return False
+        phase = self.current_phase
+        assert phase is not None
+        if not self._phase_matches(phase, session, step_index, action):
+            return False
+        self.phase_index += 1
+        return True
+
+    def gate_progress(self, session: Session, step_index: int) -> bool:
+        """True when navigation should be blocked (incomplete count-based phase)."""
+        phase = self.current_phase
+        if phase is None or self.is_complete:
+            return False
+        if phase.until.get("action") == "next_step":
+            return False
+        if phase.step_index is not None and phase.step_index != step_index:
+            return False
+        until = phase.until or {}
+        if "session_entity_count" in until:
+            return len(session.entity) < int(until["session_entity_count"])
+        if "session_metric_count" in until:
+            return len(session.metric) < int(until["session_metric_count"])
+        return False
+
+
+class TutorialCoachBar:
+    """Mixin-friendly helper; actual widget lives in tutorial_host.py."""
+
+    @staticmethod
+    def format_header(progress: str) -> str:
+        return f"TUTORIAL · {progress}"
+
+
+def run_tutorial(
+    client: JSTDataClient,
+    *,
+    session_path: str | None = None,
+    output_path: str | None = None,
+) -> None:
+    """Load bundled tutorial workflow and launch the coached host."""
+    from .tutorial_host import TutorialHost
+
+    workflow = load_workflow(TUTORIAL_WORKFLOW_ID)
+    resolved = resolve_saved_workflow(workflow)
+    coach = TutorialCoach.load()
+    prefix = "-".join(s.spec.id for s in resolved)
+    out = output_path or default_session_path(prefix)
+    app = TutorialHost(
+        client,
+        resolved,
+        coach,
+        session_path=session_path,
+        output_path=out,
+    )
+    app.run()

jstdata/workflows/tutorial_host.py

@@ -0,0 +1,178 @@
+"""Tutorial host: WorkflowHost plus a persistent coach bar."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.screen import Screen
+from textual.widgets import Label, Static
+
+from .export import ExportModal
+from .host import WorkflowHost
+from .tutorial import TutorialCoach, TutorialCoachBar
+
+
+class CoachBarWidget(Static):
+    """Docked instruction strip shown for the whole tutorial run."""
+
+    DEFAULT_CSS = """
+    CoachBarWidget {
+        dock: top;
+        height: auto;
+        min-height: 4;
+        max-height: 8;
+        background: #1a1a2e;
+        border-bottom: thick #38bdf8;
+        padding: 0 1;
+    }
+
+    #coach-header {
+        color: #38bdf8;
+        text-style: bold;
+        height: 1;
+    }
+
+    #coach-body {
+        color: #e0e0e0;
+        height: auto;
+        padding-bottom: 1;
+    }
+    """
+
+    def __init__(self, header: str = "", body: str = "") -> None:
+        super().__init__()
+        self._header = header
+        self._body = body
+
+    def compose(self) -> ComposeResult:
+        yield Label(self._header, id="coach-header")
+        yield Static(self._body, id="coach-body")
+
+    def update_coach(self, header: str, body: str) -> None:
+        if not self.is_mounted:
+            self._header = header
+            self._body = body
+            return
+        self.query_one("#coach-header", Label).update(header)
+        self.query_one("#coach-body", Static).update(body)
+
+
+class TutorialHost(WorkflowHost):
+    """WorkflowHost with phased on-screen guidance for the bundled tutorial."""
+
+    def __init__(
+        self,
+        client,
+        steps,
+        coach: TutorialCoach,
+        session_path: str | None = None,
+        output_path: str | None = None,
+    ) -> None:
+        super().__init__(client, steps, session_path=session_path, output_path=output_path)
+        self.coach = coach
+        self._coach_bar: CoachBarWidget | None = None
+
+    def on_mount(self) -> None:
+        self.coach.maybe_advance(self.session, self.step_index, None)
+        self.set_interval(0.25, self._poll_coach)
+        self._push_current_step()
+
+    def _coach_text(self) -> tuple[str, str]:
+        phase = self.coach.current_phase
+        if phase is None:
+            return (
+                "TUTORIAL · complete",
+                "Tutorial complete. Press q to quit.",
+            )
+        return (
+            TutorialCoachBar.format_header(self.coach.progress_label),
+            phase.text,
+        )
+
+    def _poll_coach(self) -> None:
+        if self.coach.maybe_advance(self.session, self.step_index, None):
+            self._refresh_coach()
+
+    def _refresh_coach(self) -> None:
+        if self._coach_bar is None or not self._coach_bar.is_mounted:
+            return
+        header, body = self._coach_text()
+        self._coach_bar.update_coach(header, body)
+
+    def _push_current_step(self) -> None:
+        self.push_screen(self._make_current_screen())
+        self.call_after_refresh(self._mount_coach_on_active_screen)
+
+    def _mount_coach_on_active_screen(self) -> None:
+        """Mount coach on the active step screen (App-level mounts sit behind Screens)."""
+        screen = self.screen
+        if not isinstance(screen, Screen):
+            return
+        if self._coach_bar is not None and self._coach_bar.is_mounted:
+            self._coach_bar.remove()
+        header, body = self._coach_text()
+        self._coach_bar = CoachBarWidget(header, body)
+        screen.mount(self._coach_bar)
+
+    def _after_step_change(self) -> None:
+        self.call_after_refresh(self._mount_coach_on_active_screen)
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        phase = self.coach.current_phase
+        if (
+            action == "next_step"
+            and phase is not None
+            and phase.until.get("action") == "next_step"
+        ):
+            return True
+        return super().check_action(action, parameters)
+
+    def action_next_step(self) -> None:
+        phase = self.coach.current_phase
+        if phase is not None and not self.coach.is_complete:
+            if phase.until.get("action") != "next_step":
+                if self.coach.gate_progress(self.session, self.step_index):
+                    self.notify(
+                        "Finish the current tutorial step first.",
+                        severity="warning",
+                    )
+                    return
+        if self.step_index >= len(self.steps) - 1:
+            self.notify("Last step in the pipeline", severity="warning")
+            return
+        advanced = self.coach.maybe_advance(
+            self.session, self.step_index, "next_step"
+        )
+        self._pop_overlays()
+        self.step_index += 1
+        self.switch_screen(self._make_current_screen())
+        self._after_step_change()
+        if advanced:
+            self._refresh_coach()
+
+    def action_prev_step(self) -> None:
+        if self.step_index <= 0:
+            self.notify("First step in the pipeline", severity="warning")
+            return
+        self._pop_overlays()
+        self.step_index -= 1
+        self.switch_screen(self._make_current_screen())
+        self._after_step_change()
+
+    def action_session(self) -> None:
+        super().action_session()
+        if self.coach.maybe_advance(self.session, self.step_index, "open_session"):
+            self._refresh_coach()
+
+    def action_export(self) -> None:
+        self.push_screen(
+            ExportModal(
+                self.session,
+                default_path=self.output_path,
+                on_write=self._on_tutorial_session_written,
+            )
+        )
+
+    def _on_tutorial_session_written(self, path: str) -> None:
+        if self.coach.maybe_advance(self.session, self.step_index, "session_written"):
+            self._refresh_coach()
+            self.notify(f"Tutorial complete — session saved to {path}")

jstdata-0.2.0.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: jstdata
+Version: 0.2.0
+Summary: Python API, CLI, and interactive workflows for Jefferson Street financial and economic data.
+License: MIT
+License-File: LICENSE
+Keywords: api,cli,data,jefferson street,economics,finance
+Author: Mahfuj Ahbab
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: click (>=8.2.1,<9.0.0)
+Requires-Dist: pandas (>=2.3.1,<3.0.0)
+Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Requires-Dist: textual (>=1.0.0,<2.0.0)
+Project-URL: Homepage, https://github.com/Jefferson-Street-Technologies/jstdata
+Project-URL: Repository, https://github.com/Jefferson-Street-Technologies/jstdata
+Description-Content-Type: text/markdown
+
+# Jefferson Street Data (jstdata)
+
+A Python interface and Research OS 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.
+- **Sessions & workflows**: Stage resolved ids in a session JSON; compose interactive steps in the shell and save them as named workflows.
+- **Reproducible Discovery**: High-speed discovery in the TUI transitions into immutable Python / CLI snippets.
+
+---
+
+## Installation
+
+```bash
+# Using poetry
+poetry install
+
+# Manual install
+pip install .
+```
+
+## Authentication & Configuration
+
+### Quick Start (CLI)
+
+```bash
+jst login
+```
+
+Credentials are saved to `~/.jstdata/config.json` with secure permissions.
+
+### Environment Variables
+
+These take precedence over the config file:
+
+```bash
+export JSTDATA_API_KEY="your-api-key-here"
+# Optional: export JSTDATA_BASE_URL="https://api.jeffersonst.io"
+```
+
+### Managing Configuration
+
+```bash
+jst config show
+jst config show --verbose
+jst config set api_key XXX
+```
+
+## Interactive investigation (`jst run`)
+
+Compose TUI **steps** in the shell. Steps share one **Session** (staged metrics /
+entities / series + query filters) for the lifetime of the run.
+
+```bash
+# Catalog search → stage entities/metrics/series
+jst run console
+
+# Scope to a taxonomy and resource type
+jst run console --taxonomy sec-central-index-key --resource-type entity
+
+# Filter entities by typed graph edges (repeatable; OR'd)
+jst run console --relation classified_as:sic:7372 --resource-type entity
+
+# Chain steps
+jst run console --taxonomy country : discover --mode union : rank --taxonomy country
+
+# Preload a session JSON; set default export path
+jst run --session labor.json --output out.json rank --taxonomy country
+```
+
+Built-in steps:
+
+| Step | Role |
+|------|------|
+| `console` | Search catalog; stage into the session |
+| `discover` | Find metrics for session entities; preview coverage |
+| `rank` | Leaderboard entities for a session metric |
+
+Host keys (every step): `s` session · `f` find · `e` export · `n`/`p` next/prev · `?` step help · `q` quit.
+
+```bash
+jst steps
+jst step console
+jst step rank --json
+```
+
+### Saved workflows
+
+Persist step pipelines (not session contents) under `~/.jstdata/workflows/`:
+
+```bash
+jst workflow create --id gdp-rank --description "GDP board" -- \
+  console --taxonomy country : rank --taxonomy country
+
+jst workflow ls
+jst workflow run gdp-rank --session labor.json
+jst workflow rm gdp-rank
+```
+
+(`jst workflows` remains a compatibility alias.)
+
+### Tutorial
+
+```bash
+jst tutorial
+# same as: jst workflow run tutorial
+```
+
+### Agents
+
+```bash
+jst agent-guide
+```
+
+Prints a version-tied operating manual (hard rules, modes, recipes, and the live
+CLI/step reference). Prefer it over guessing command shapes or inventing ids.
+
+## The Scriptable CLI (`jst`)
+
+Pipe-friendly commands for automation and quick extraction.
+
+```bash
+# Fuzzy / set search (omit QUERY to list the matching set)
+jst metric search "defense spending" --taxonomy country --limit 20 --format json
+jst entity search --relation classified_as:sic:3674 --limit 50 --format json
+jst entity search --metric gdp --metric cpi --mode intersect --format json
+
+# Taxonomies
+jst taxonomy ls --format json
+jst taxonomy entities country --limit 20 --format json
+
+# Bounded cross-sectional query (head/tail per series)
+jst query --metric inflation --entity "United States" --frequency Monthly --tail 20
+jst query --metric gdp --taxonomy country --tail 1 --sort-by value --limit 50 --format json
+
+# Deep history for one known series
+jst series observations ABC123 --start-date 2000-01-01 --limit 1000
+
+# Entity graph
+jst entity relations cik:1045810 --format pretty
+```
+
+## The Python API
+
+```python
+from jstdata import JSTDataClient, Session
+
+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")
+
+# Stage intent for a later `jst run` / `jst workflow run`
+session = Session(
+    metric=["gross-domestic-product"],
+    taxonomy="country",
+    tail=1,
+    sort_by="value",
+)
+session.save("labor.json")
+```
+
+## Extending the product
+
+See [AGENTS.md](AGENTS.md) for how steps, the host, and saved workflows are
+structured when adding new interactive surface area.
+

jstdata-0.2.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+jstdata/__init__.py,sha256=HQVrTOLDbVmhAZVlxPNuysSwp7h02gipLPaPmzCmFPg,257
+jstdata/agent_guide.py,sha256=i4MXf0ra16Do98IWeq2YJ0Tdyd__klCBQGDunPh6sQ4,18539
+jstdata/cli.py,sha256=PeZwk8GZEPHQ-fveA31LSZEKcZS6Bs0DqGGZ9I-sXOU,20349
+jstdata/client.py,sha256=U2HlIsSddLAeRCM2KDhZ9scA73sPP1hB6wfTXG_82Fs,18906
+jstdata/models.py,sha256=bbipJxITf6K_5N2rVdv01QaxJp_8Y--ud92drhKJkLg,4656
+jstdata/session.py,sha256=myRmghmSyZ98Co0tJ2MmO8AMo5HNyoe7OpCK9MLCMZI,8874
+jstdata/utils.py,sha256=ge9nPasdCaJyEgEdH9z9-uZ1wmR-Fur5z798qcLOQLs,3198
+jstdata/workflows/__init__.py,sha256=QVFkujbTsDqqcubbm7s9-fwoxeJllVxOuH_PZ_aZWEE,2033
+jstdata/workflows/base.py,sha256=UvLRA6wDQdYyYZNqqFzhNRo-YK4D2vEiCJUA89Ks6NA,10650
+jstdata/workflows/bundled/__init__.py,sha256=f4FveHIFSbteKjgLqhgnEwpheuigMolIudZqzSdX8YI,58
+jstdata/workflows/bundled/tutorial.yaml,sha256=ECaWCXPvnD2PcHefJHRKsgMuyMyCJAp1bVs8yTClt2c,356
+jstdata/workflows/bundled/tutorial_script.yaml,sha256=DVRtJnmRIAQrgIa2ZqPcwPTyx3TIOJgS4IO4yQsnxAw,952
+jstdata/workflows/chart.py,sha256=jbXt-vuDfrH17zMUGZdYPBnyUk6qMoufufwISaR4fJE,11218
+jstdata/workflows/console.py,sha256=8GkLr9Gp1veTF8LBEkgW7v9PjNxxMzt2_2HI54sWhnQ,18845
+jstdata/workflows/discover.py,sha256=eUWIDf_4vlEsag8B9cEB2HCv5_KmOVlSN5RbEKScSVA,17359
+jstdata/workflows/export.py,sha256=SvovNEf8vRHEUa-reI4YJg5S87gcelukd28b0oAlQrw,4879
+jstdata/workflows/find.py,sha256=aKFlHjItbpB3gAPOdOxBV3GbL--ZSUBq-DjuPFf3Qzg,12104
+jstdata/workflows/host.py,sha256=WfrXv2TIK96lZtkoqDkXjgHe__wK-mtQwkeYu5DWU0w,7772
+jstdata/workflows/rank.py,sha256=vjK4dX1wOriwKUEuO9OWgucXRvMqo9iUzEFzaVPFlFM,22342
+jstdata/workflows/session_manager.py,sha256=HBJfUkKSiKWTJhWxeOi12nPf8ToDnpsHwaHqApWEjbA,8527
+jstdata/workflows/store.py,sha256=iFhaXrC0s5rIFNQDoMrHAYSqhBKS9X6tQtVqzZwDgkk,10531
+jstdata/workflows/tutorial.py,sha256=w2ht5-wpOzUB-YnnbKU68SuHD_PdDBE_pBQn8zL-QK4,5025
+jstdata/workflows/tutorial_host.py,sha256=_b3ycgrZpAhFcUYPQnnmtVZyDfmpP9oUdj4BL3rCHLk,5902
+jstdata-0.2.0.dist-info/METADATA,sha256=fYJl31donCLLoqq8MHsnA94M45ITcte6AbhHyP0JrbE,6679
+jstdata-0.2.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+jstdata-0.2.0.dist-info/entry_points.txt,sha256=LiXk2o_qORp1dSOntBHUmOm4h1RKB4PFCPVnpw6V69E,39
+jstdata-0.2.0.dist-info/licenses/LICENSE,sha256=6GgMUDMJtgsxaYAeTpyCFH6t6bNVNVUQsgkUKLQxyoo,1068
+jstdata-0.2.0.dist-info/RECORD,,

jstdata-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jstdata-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+jst=jstdata.cli:cli
+

jstdata-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahfuj Ahbab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT of OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.