filtrix-cli 0.1.0__tar.gz → 0.2.0__tar.gz

filtrix_cli-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc

{filtrix_cli-0.1.0 → filtrix_cli-0.2.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Filtrix
-
-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.
+MIT License
+
+Copyright (c) 2026 Filtrix
+
+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.

{filtrix_cli-0.1.0 → filtrix_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: filtrix-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Agent-first command-line interface for the FILTRIX backtest engine.
 Project-URL: Homepage, https://filtrix.net
 Project-URL: Documentation, https://pypi.org/project/filtrix-cli/
@@ -43,7 +43,7 @@ pipx install filtrix-cli      # or: uvx filtrix-cli ...
 ## Authenticate
 
 ```bash
-export FILTRIX_API_KEY=flt_your_key      # for backtests/screens/ticker/account
+export FILTRIX_API_KEY=flt_your_key      # for every read command
 filtrix auth login                       # for managing API keys (stores a JWT)
 ```
 
@@ -57,11 +57,18 @@ filtrix auth register --email you@example.com --accept-tos
 ## Examples
 
 ```bash
-filtrix backtest --filter "gap_gup>=50" --filter "price_price<5"
-filtrix screen --filter "gap_gup>=50" --limit 20
+filtrix meta                                      # outcomes, units, limits, quota (free)
+filtrix filters --search "relative volume"        # find column names (no key needed)
+filtrix backtest --filter "gap_gup>=50" --filter "price_price<5" --sample 5
+filtrix backtest -f "gap_gup>=10" --outcome day_return --threshold 0
+filtrix screen --filter "gap_gup>=50" --limit 20 --field rv_computed
 filtrix --json screen --filter "gap_gup>=50"     # force JSON in a terminal
-filtrix ticker NVDA
-filtrix filters --search gap
+filtrix ticker NVDA                               # metadata
+filtrix overview NVDA                             # price, moves, 52-week range, fundamentals
+filtrix gaps TSLA --threshold 10 --direction down # this ticker's own gap history
+filtrix daily AAPL --limit 60                     # daily OHLCV bars
+filtrix coverage TSLA                             # how much history
+filtrix premarket                                 # today's premarket gappers (free)
 filtrix account
 filtrix keys create --name laptop
 filtrix llms          # machine-readable usage guide for AI agents

{filtrix_cli-0.1.0 → filtrix_cli-0.2.0}/README.md

@@ -1,48 +1,55 @@
-# filtrix-cli
-
-Agent-first command-line interface to [FILTRIX](https://filtrix.net) — historical trading-pattern backtesting.
-
-## Install
-
-```bash
-pipx install filtrix-cli      # or: uvx filtrix-cli ...
-```
-
-## Authenticate
-
-```bash
-export FILTRIX_API_KEY=flt_your_key      # for backtests/screens/ticker/account
-filtrix auth login                       # for managing API keys (stores a JWT)
-```
-
-### Sign up (terminal)
-
-```bash
-filtrix auth register --email you@example.com --accept-tos
-# FILTRIX emails a 6-digit code; paste it when prompted; you're logged in.
-```
-
-## Examples
-
-```bash
-filtrix backtest --filter "gap_gup>=50" --filter "price_price<5"
-filtrix screen --filter "gap_gup>=50" --limit 20
-filtrix --json screen --filter "gap_gup>=50"     # force JSON in a terminal
-filtrix ticker NVDA
-filtrix filters --search gap
-filtrix account
-filtrix keys create --name laptop
-filtrix llms          # machine-readable usage guide for AI agents
-```
-
-## Output & scripting
-
-Output is human-readable in a terminal and JSON when piped or with the global `--json` flag.
-Global flags (`--json`, `--quiet`, `--profile`, `--api-key`, `--base-url`) go BEFORE the subcommand.
-Exit codes: 0 ok, 2 usage, 3 not-found, 4 auth, 5 rate-limited, 6 network, 1 server.
-
-## Configuration
-
-Settings resolve in order: CLI flag > environment variable > config file
-(`filtrix config path` shows the location). Use `--profile NAME` for multiple environments.
-Credentials (API key / JWT) are stored in cleartext in this TOML file (best-effort `chmod 600` on POSIX) — treat it like an SSH key.
+# filtrix-cli
+
+Agent-first command-line interface to [FILTRIX](https://filtrix.net) — historical trading-pattern backtesting.
+
+## Install
+
+```bash
+pipx install filtrix-cli      # or: uvx filtrix-cli ...
+```
+
+## Authenticate
+
+```bash
+export FILTRIX_API_KEY=flt_your_key      # for every read command
+filtrix auth login                       # for managing API keys (stores a JWT)
+```
+
+### Sign up (terminal)
+
+```bash
+filtrix auth register --email you@example.com --accept-tos
+# FILTRIX emails a 6-digit code; paste it when prompted; you're logged in.
+```
+
+## Examples
+
+```bash
+filtrix meta                                      # outcomes, units, limits, quota (free)
+filtrix filters --search "relative volume"        # find column names (no key needed)
+filtrix backtest --filter "gap_gup>=50" --filter "price_price<5" --sample 5
+filtrix backtest -f "gap_gup>=10" --outcome day_return --threshold 0
+filtrix screen --filter "gap_gup>=50" --limit 20 --field rv_computed
+filtrix --json screen --filter "gap_gup>=50"     # force JSON in a terminal
+filtrix ticker NVDA                               # metadata
+filtrix overview NVDA                             # price, moves, 52-week range, fundamentals
+filtrix gaps TSLA --threshold 10 --direction down # this ticker's own gap history
+filtrix daily AAPL --limit 60                     # daily OHLCV bars
+filtrix coverage TSLA                             # how much history
+filtrix premarket                                 # today's premarket gappers (free)
+filtrix account
+filtrix keys create --name laptop
+filtrix llms          # machine-readable usage guide for AI agents
+```
+
+## Output & scripting
+
+Output is human-readable in a terminal and JSON when piped or with the global `--json` flag.
+Global flags (`--json`, `--quiet`, `--profile`, `--api-key`, `--base-url`) go BEFORE the subcommand.
+Exit codes: 0 ok, 2 usage, 3 not-found, 4 auth, 5 rate-limited, 6 network, 1 server.
+
+## Configuration
+
+Settings resolve in order: CLI flag > environment variable > config file
+(`filtrix config path` shows the location). Use `--profile NAME` for multiple environments.
+Credentials (API key / JWT) are stored in cleartext in this TOML file (best-effort `chmod 600` on POSIX) — treat it like an SSH key.

{filtrix_cli-0.1.0 → filtrix_cli-0.2.0}/pyproject.toml

@@ -1,51 +1,51 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "filtrix-cli"
-version = "0.1.0"
-description = "Agent-first command-line interface for the FILTRIX backtest engine."
-readme = "README.md"
-requires-python = ">=3.10"
-license = {text = "MIT"}
-authors = [
-    {name = "Filtrix", email = "team@filtrix.net"},
-]
-keywords = ["filtrix", "cli", "trading", "backtest", "screener", "ai-agents", "quant"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Environment :: Console",
-    "Intended Audience :: Developers",
-    "Intended Audience :: Financial and Insurance Industry",
-    "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Topic :: Office/Business :: Financial :: Investment",
-]
-dependencies = [
-    "typer>=0.12",
-    "rich>=13",
-    "httpx>=0.27",
-    "platformdirs>=4",
-    "tomli-w>=1.0",
-    "tomli>=2.0; python_version < '3.11'",
-]
-
-[project.optional-dependencies]
-dev = ["pytest>=8", "respx>=0.21"]
-
-[project.urls]
-Homepage = "https://filtrix.net"
-Documentation = "https://pypi.org/project/filtrix-cli/"
-
-[project.scripts]
-filtrix = "filtrix_cli.__main__:main"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/filtrix_cli"]
-
-[tool.hatch.build.targets.wheel.force-include]
-"src/filtrix_cli/AGENTS.md" = "filtrix_cli/AGENTS.md"
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "filtrix-cli"
+version = "0.2.0"
+description = "Agent-first command-line interface for the FILTRIX backtest engine."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Filtrix", email = "team@filtrix.net"},
+]
+keywords = ["filtrix", "cli", "trading", "backtest", "screener", "ai-agents", "quant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "httpx>=0.27",
+    "platformdirs>=4",
+    "tomli-w>=1.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "respx>=0.21"]
+
+[project.urls]
+Homepage = "https://filtrix.net"
+Documentation = "https://pypi.org/project/filtrix-cli/"
+
+[project.scripts]
+filtrix = "filtrix_cli.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/filtrix_cli"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/filtrix_cli/AGENTS.md" = "filtrix_cli/AGENTS.md"

{filtrix_cli-0.1.0 → filtrix_cli-0.2.0}/src/filtrix_cli/AGENTS.md

@@ -1,47 +1,59 @@
-# filtrix-cli — agent guide
-
-Structured command-line access to the FILTRIX historical backtest engine.
-
-## Output contract
-- Add `--json` (or pipe stdout) to get JSON on stdout. Human tables otherwise.
-- Data goes to stdout; errors/progress go to stderr.
-- Errors (stderr, JSON): {"error":{"type","message","status","retryable","suggestion","input"}}.
-
-## Exit codes
-- 0 success
-- 1 server/unexpected error (retryable)
-- 2 usage / invalid filter
-- 3 not found
-- 4 authentication required/failed
-- 5 rate limited (retryable)
-- 6 network/timeout (retryable)
-
-## Auth
-- Reads/backtests: set env FILTRIX_API_KEY=flt_... (or `filtrix config set api_key ...`).
-- Key management: `filtrix auth login` first (stores a JWT).
-
-## Commands
-- filtrix backtest --filter "COL OP VAL" [--filter ...] [--outcome ...] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
-- filtrix screen   --filter ... [--limit N] [--offset N]
-- filtrix ticker   SYMBOL
-- filtrix filters  [--search TEXT] [--type number|date|string]
-- filtrix account
-- filtrix keys list|create|revoke
-- filtrix auth login|logout|status
-- filtrix auth register --email E --password P --accept-tos   (emails a 6-digit code, then prompts for it, then auto-logs-in)
-- filtrix auth verify-code CODE --email E --password P        (resume a pending signup)
-- filtrix auth resend-code --email E
-- filtrix config get|set|list|path
-
-Note: global flags like `--json` go BEFORE the subcommand (e.g. `filtrix --json backtest ...`).
-
-## Filter DSL
-"COL OP VAL", operators: >= <= != = > < like in. Repeat --filter for AND.
-Examples: "gap_gup>=10", "price_price<5", "earnings_date_days_earningd=0.25", "sic_code in 7372,7389".
-Use the RAW schema column names from `filtrix filters` (e.g. price_price, float_shares_float) — these
-can differ from screen's friendlier output field names (price, float_shares). Unknown columns return exit 2.
-For exact control, pass `--filters-json '[{"column":...,"operator":...,"value":...,"value_type":...}]'`
-or `--filters-json -` to read the JSON array from stdin.
-
-## Discover filters
-Run `filtrix filters --json` to enumerate valid columns, value types, and operators.
+# filtrix-cli — agent guide
+
+Structured command-line access to the FILTRIX historical backtest engine.
+
+## Output contract
+- Add `--json` (or pipe stdout) to get JSON on stdout. Human tables otherwise.
+- Data goes to stdout; errors/progress go to stderr.
+- Errors (stderr, JSON): {"error":{"type","message","status","retryable","suggestion","input"}}.
+
+## Exit codes
+- 0 success
+- 1 server/unexpected error (retryable)
+- 2 usage / invalid filter
+- 3 not found
+- 4 authentication required/failed
+- 5 rate limited (retryable)
+- 6 network/timeout (retryable)
+
+## Auth
+- Reads/backtests: set env FILTRIX_API_KEY=flt_... (or `filtrix config set api_key ...`).
+- Quota: 50 requests/day free, 1000 Pro; meta, filters, account, premarket are free. Resets at midnight America/New_York.
+- Key management: `filtrix auth login` first (stores a JWT).
+
+## Commands
+- filtrix meta                (free) outcome definitions + units, limits, quotas, data coverage
+- filtrix filters  [--search TEXT] [--type number|date|string|time|enum] [--limit N]   (no auth; ranked search)
+- filtrix backtest --filter "COL OP VAL" [--filter ...] [--outcome ...] [--threshold X] [--pos-min A --pos-max B]
+                   [--sample N] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--flat-threshold F]
+- filtrix screen   --filter ... [--limit N] [--offset N] [--field COL ...]
+- filtrix ticker   SYMBOL       metadata (name, sector, market cap)
+- filtrix overview SYMBOL       last close, 1d/5d/20d moves, 52-week range, TTM fundamentals (verified email)
+- filtrix gaps     SYMBOL [--threshold 10] [--direction up|down] [--stat avg|median]   this ticker's own gap history
+- filtrix daily    SYMBOL [--limit 250]   daily OHLCV bars, oldest first (max 500)
+- filtrix coverage [SYMBOL]     first/last event date and counts
+- filtrix premarket             (free) today's premarket gappers with historical stats
+- filtrix account               (free) tier, quota used/remaining, reset time, capabilities
+- filtrix keys list|create|revoke
+- filtrix auth login|logout|status
+- filtrix auth register --email E --password P --accept-tos   (emails a 6-digit code, then prompts for it, then auto-logs-in)
+- filtrix auth verify-code CODE --email E --password P        (resume a pending signup)
+- filtrix auth resend-code --email E
+- filtrix config get|set|list|path
+
+Note: global flags like `--json` go BEFORE the subcommand (e.g. `filtrix --json backtest ...`).
+
+## Filter DSL
+"COL OP VAL", operators: >= <= != = > < like in. Repeat --filter for AND.
+Examples: "gap_gup>=10", "price_price<5", "earnings_date_days_earningd=0.25", "sic_code in 7372,7389".
+Use the RAW schema column names from `filtrix filters` (e.g. price_price, float_shares_float) — these
+can differ from screen's friendlier output field names (price, float_shares). Unknown columns return exit 2.
+For exact control, pass `--filters-json '[{"column":...,"operator":...,"value":...,"value_type":...}]'`
+or `--filters-json -` to read the JSON array from stdin.
+
+## Discover filters
+Run `filtrix filters --search "<words>" --json` to find columns (raw name, Trade-Ideas code, description,
+operators, value type). `filtrix meta --json` defines every backtest outcome and its unit:
+day_close_position (0 = closed at the low, 1 = at the high; default), day_return (fraction),
+reg_pct / hi_to_cl_pct / lo_to_cl_pct (percent). Each backtest response also carries
+outcome_definition, direction_rule (what long/short/flat_pct mean) and bucket_prob_definition.

filtrix_cli-0.2.0/src/filtrix_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{filtrix_cli-0.1.0 → filtrix_cli-0.2.0}/src/filtrix_cli/__main__.py

@@ -1,60 +1,67 @@
-import typer
-
-from filtrix_cli import __version__
-from filtrix_cli.state import set_state
-from filtrix_cli.commands import backtest as backtest_cmd
-from filtrix_cli.commands import screen as screen_cmd
-from filtrix_cli.commands import ticker as ticker_cmd
-from filtrix_cli.commands import filters as filters_cmd
-from filtrix_cli.commands import account as account_cmd
-from filtrix_cli.commands import keys as keys_cmd
-from filtrix_cli.commands import authcmd
-from filtrix_cli.commands import configcmd
-from filtrix_cli.commands import llms as llms_cmd
-
-app = typer.Typer(
-    add_completion=False,
-    help="FILTRIX CLI — terminal access to the FILTRIX backtest engine.",
-)
-
-
-@app.callback(invoke_without_command=True)
-def _root(
-    ctx: typer.Context,
-    json: bool = typer.Option(False, "--json", help="Force JSON output to stdout."),
-    quiet: bool = typer.Option(False, "--quiet", "-q", help="Bare values only."),
-    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output."),
-    profile: str = typer.Option(None, "--profile", help="Config profile to use."),
-    api_key: str = typer.Option(None, "--api-key", help="Override API key for this run."),
-    base_url: str = typer.Option(None, "--base-url", help="Override API base URL for this run."),
-) -> None:
-    """FILTRIX CLI — terminal access to the FILTRIX backtest engine."""
-    set_state(json=json, quiet=quiet, no_color=no_color,
-              profile=profile, api_key=api_key, base_url=base_url)
-    if ctx.invoked_subcommand is None:
-        typer.echo(ctx.get_help())
-
-
-@app.command()
-def version() -> None:
-    """Print the CLI version."""
-    typer.echo(f"filtrix-cli {__version__}")
-
-
-app.command("backtest")(backtest_cmd.backtest)
-app.command("screen")(screen_cmd.screen)
-app.command("ticker")(ticker_cmd.ticker)
-app.command("filters")(filters_cmd.filters)
-app.command("account")(account_cmd.account)
-app.add_typer(keys_cmd.app, name="keys")
-app.add_typer(authcmd.app, name="auth")
-app.add_typer(configcmd.app, name="config")
-app.command("llms")(llms_cmd.llms)
-
-
-def main() -> None:
-    app()
-
-
-if __name__ == "__main__":
-    main()
+import typer
+
+from filtrix_cli import __version__
+from filtrix_cli.state import set_state
+from filtrix_cli.commands import backtest as backtest_cmd
+from filtrix_cli.commands import screen as screen_cmd
+from filtrix_cli.commands import ticker as ticker_cmd
+from filtrix_cli.commands import filters as filters_cmd
+from filtrix_cli.commands import account as account_cmd
+from filtrix_cli.commands import keys as keys_cmd
+from filtrix_cli.commands import authcmd
+from filtrix_cli.commands import configcmd
+from filtrix_cli.commands import llms as llms_cmd
+from filtrix_cli.commands import market as market_cmd
+
+app = typer.Typer(
+    add_completion=False,
+    help="FILTRIX CLI — terminal access to the FILTRIX backtest engine.",
+)
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    json: bool = typer.Option(False, "--json", help="Force JSON output to stdout."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Bare values only."),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output."),
+    profile: str = typer.Option(None, "--profile", help="Config profile to use."),
+    api_key: str = typer.Option(None, "--api-key", help="Override API key for this run."),
+    base_url: str = typer.Option(None, "--base-url", help="Override API base URL for this run."),
+) -> None:
+    """FILTRIX CLI — terminal access to the FILTRIX backtest engine."""
+    set_state(json=json, quiet=quiet, no_color=no_color,
+              profile=profile, api_key=api_key, base_url=base_url)
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+
+
+@app.command()
+def version() -> None:
+    """Print the CLI version."""
+    typer.echo(f"filtrix-cli {__version__}")
+
+
+app.command("backtest")(backtest_cmd.backtest)
+app.command("screen")(screen_cmd.screen)
+app.command("ticker")(ticker_cmd.ticker)
+app.command("filters")(filters_cmd.filters)
+app.command("account")(account_cmd.account)
+app.add_typer(keys_cmd.app, name="keys")
+app.add_typer(authcmd.app, name="auth")
+app.add_typer(configcmd.app, name="config")
+app.command("llms")(llms_cmd.llms)
+app.command("meta")(market_cmd.meta)
+app.command("coverage")(market_cmd.coverage)
+app.command("overview")(market_cmd.overview)
+app.command("gaps")(market_cmd.gaps)
+app.command("daily")(market_cmd.daily)
+app.command("premarket")(market_cmd.premarket)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()