filtrix-cli 0.1.0__tar.gz

filtrix_cli-0.1.0/LICENSE

@@ -0,0 +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.

filtrix_cli-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: filtrix-cli
+Version: 0.1.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/
+Author-email: Filtrix <team@filtrix.net>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,backtest,cli,filtrix,quant,screener,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+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: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4
+Requires-Dist: rich>=13
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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-0.1.0/README.md

@@ -0,0 +1,48 @@
+# 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-0.1.0/pyproject.toml

@@ -0,0 +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"

filtrix_cli-0.1.0/src/filtrix_cli/AGENTS.md

@@ -0,0 +1,47 @@
+# 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-0.1.0/src/filtrix_cli/__init__.py

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

filtrix_cli-0.1.0/src/filtrix_cli/__main__.py

@@ -0,0 +1,60 @@
+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()

filtrix_cli-0.1.0/src/filtrix_cli/auth.py

@@ -0,0 +1,76 @@
+"""Interactive login flows: direct, Telegram-2FA poll, and backup code."""
+import time
+from typing import Callable, Optional
+
+import httpx
+
+from filtrix_cli import __version__
+from filtrix_cli.output import CLIError
+
+_POLL_DEADLINE_SECONDS = 300
+
+
+def _ua() -> dict:
+    return {"User-Agent": f"filtrix-cli/{__version__}", "X-Agent-Request": "true"}
+
+
+def login(
+    base_url: str,
+    email: str,
+    password: str,
+    *,
+    poll_interval: float = 2.0,
+    on_pending: Optional[Callable[[str, Optional[str]], None]] = None,
+) -> str:
+    """Return a JWT. Handles direct login and Telegram 2FA. Raises CLIError
+    (type 'backup_code_required') when only a backup code can proceed."""
+    base = base_url.rstrip("/")
+    with httpx.Client(timeout=30) as client:
+        resp = client.post(f"{base}/api/auth/login", data={"username": email, "password": password}, headers=_ua())
+        if resp.status_code == 200:
+            return resp.json()["access_token"]
+        if resp.status_code == 400:
+            raise CLIError("auth_failed", "Incorrect email or password.", status=400, exit_code=4)
+        if resp.status_code == 202:
+            body = resp.json()
+            required = body.get("auth_required")
+            if required == "backup_code_only":
+                raise CLIError("backup_code_required",
+                               "2FA is on but Telegram is unlinked. Re-run with --backup-code.",
+                               status=202, exit_code=4)
+            if required == "telegram":
+                pending_id = body["pending_id"]
+                if on_pending:
+                    on_pending(pending_id, body.get("expires_at"))
+                return _poll_login(client, base, pending_id, poll_interval)
+            raise CLIError("auth_failed", f"Unexpected auth_required: {required}", status=202, exit_code=4)
+        raise CLIError("server_error", f"Login failed (HTTP {resp.status_code}).",
+                       status=resp.status_code, exit_code=1)
+
+
+def _poll_login(client: httpx.Client, base: str, pending_id: str, interval: float) -> str:
+    deadline = time.time() + _POLL_DEADLINE_SECONDS
+    while time.time() < deadline:
+        status = client.get(f"{base}/api/auth/login/status/{pending_id}", headers=_ua()).json().get("status")
+        if status == "approved":
+            done = client.post(f"{base}/api/auth/login/complete/{pending_id}", headers=_ua())
+            if done.status_code == 200:
+                return done.json()["access_token"]
+            raise CLIError("auth_failed", f"Could not finalize login (HTTP {done.status_code}).",
+                           status=done.status_code, exit_code=4)
+        if status == "denied":
+            raise CLIError("auth_failed", "Login was denied from Telegram.", exit_code=4)
+        if status == "expired":
+            raise CLIError("auth_failed", "Login approval expired. Try again.", exit_code=4)
+        time.sleep(interval)
+    raise CLIError("auth_failed", "Timed out waiting for Telegram approval.", retryable=True, exit_code=6)
+
+
+def login_backup_code(base_url: str, email: str, password: str, code: str) -> str:
+    base = base_url.rstrip("/")
+    with httpx.Client(timeout=30) as client:
+        resp = client.post(f"{base}/api/auth/login/backup-code",
+                           json={"email": email, "password": password, "code": code}, headers=_ua())
+        if resp.status_code == 200:
+            return resp.json()["access_token"]
+        raise CLIError("auth_failed", "Backup-code login failed.", status=resp.status_code, exit_code=4)

filtrix_cli-0.1.0/src/filtrix_cli/client.py

@@ -0,0 +1,132 @@
+"""Synchronous httpx client for the FILTRIX API, with error -> CLIError mapping."""
+import json
+from typing import Any, List, Optional
+
+import httpx
+
+from filtrix_cli import __version__
+from filtrix_cli.output import CLIError
+
+
+def _safe_detail(resp: httpx.Response) -> str:
+    try:
+        data = resp.json()
+    except Exception:
+        return resp.text or f"HTTP {resp.status_code}"
+    if isinstance(data, dict) and "detail" in data:
+        detail = data["detail"]
+        return detail if isinstance(detail, str) else json.dumps(detail)
+    return json.dumps(data)
+
+
+class FiltrixClient:
+    def __init__(self, base_url: str, api_key: Optional[str] = None,
+                 jwt: Optional[str] = None, timeout: float = 60.0):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.jwt = jwt
+        self.timeout = timeout
+
+    def _headers(self, auth: str) -> dict:
+        """auth in {'any', 'jwt', 'none'}."""
+        headers = {
+            "User-Agent": f"filtrix-cli/{__version__}",
+            "X-Agent-Request": "true",
+            "Content-Type": "application/json",
+        }
+        if auth == "none":
+            return headers
+        if auth == "jwt":
+            if not self.jwt:
+                raise CLIError("auth_failed", "This command requires login. Run `filtrix auth login`.",
+                               suggestion="filtrix auth login", exit_code=4)
+            headers["Authorization"] = f"Bearer {self.jwt}"
+            return headers
+        # auth == "any"
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        elif self.jwt:
+            headers["Authorization"] = f"Bearer {self.jwt}"
+        else:
+            raise CLIError("auth_failed", "No credentials. Set FILTRIX_API_KEY or run `filtrix auth login`.",
+                           suggestion="filtrix auth login", exit_code=4)
+        return headers
+
+    def _request(self, method: str, path: str, *, json_body: Any = None, auth: str = "any") -> Any:
+        url = f"{self.base_url}{path}"
+        headers = self._headers(auth)
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                resp = client.request(method, url, headers=headers, json=json_body)
+        except httpx.TimeoutException as e:
+            raise CLIError("network", f"Request timed out: {e}", retryable=True, exit_code=6)
+        except httpx.HTTPError as e:
+            raise CLIError("network", f"Network error: {e}", retryable=True, exit_code=6)
+        return self._handle_response(resp)
+
+    def _handle_response(self, resp: httpx.Response) -> Any:
+        if resp.status_code < 400:
+            return resp.json() if resp.content else {}
+        detail = _safe_detail(resp)
+        code = resp.status_code
+        if code in (401, 403):
+            raise CLIError("auth_failed", detail, status=code,
+                           suggestion="Run `filtrix auth login` or check your API key.", exit_code=4)
+        if code == 404:
+            raise CLIError("not_found", detail, status=404, exit_code=3)
+        if code == 429:
+            raise CLIError("rate_limited", detail, status=429, retryable=True,
+                           suggestion="Run `filtrix account` to see your quota.", exit_code=5)
+        if 400 <= code < 500:
+            raise CLIError("invalid_request", detail, status=code, exit_code=2)
+        raise CLIError("server_error", detail, status=code, retryable=True, exit_code=1)
+
+    # ---- Public API v1 ----
+    def backtest(self, filters: List[dict], outcome: str = "day_close_position",
+                 flat_threshold: float = 0.002, start_date: Optional[str] = None,
+                 end_date: Optional[str] = None) -> Any:
+        body: dict = {"filters": filters, "outcome": outcome, "flat_threshold": flat_threshold}
+        if start_date:
+            body["start_date"] = start_date
+        if end_date:
+            body["end_date"] = end_date
+        return self._request("POST", "/api/v1/backtest", json_body=body)
+
+    def screen(self, filters: List[dict], limit: int = 50, offset: int = 0) -> Any:
+        return self._request("POST", "/api/v1/screen",
+                             json_body={"filters": filters, "limit": limit, "offset": offset})
+
+    def ticker_info(self, symbol: str) -> Any:
+        return self._request("GET", f"/api/v1/ticker/{symbol.upper()}")
+
+    def list_filters(self) -> Any:
+        return self._request("GET", "/api/v1/filters", auth="none")
+
+    def account(self) -> Any:
+        return self._request("GET", "/api/v1/account")
+
+    # ---- Key management (JWT) ----
+    def keys_list(self) -> Any:
+        return self._request("GET", "/api/keys", auth="jwt")
+
+    def keys_create(self, name: str = "default") -> Any:
+        return self._request("POST", "/api/keys", json_body={"name": name}, auth="jwt")
+
+    def keys_revoke(self, key_id: int) -> Any:
+        return self._request("DELETE", f"/api/keys/{key_id}", auth="jwt")
+
+    # ---- Registration (pre-auth) ----
+    def register(self, email: str, password: str, delivery: str = "code",
+                 ref_source: Optional[str] = None) -> Any:
+        body: dict = {"email": email, "password": password, "delivery": delivery}
+        if ref_source:
+            body["ref_data"] = {"ref_source": ref_source}
+        return self._request("POST", "/api/auth/register", json_body=body, auth="none")
+
+    def verify_email_code(self, email: str, code: str) -> Any:
+        return self._request("POST", "/api/auth/verify-email-code",
+                             json_body={"email": email, "code": code}, auth="none")
+
+    def resend_code(self, email: str) -> Any:
+        return self._request("POST", "/api/auth/resend-code",
+                             json_body={"email": email}, auth="none")

filtrix_cli-0.1.0/src/filtrix_cli/commands/_helpers.py

@@ -0,0 +1,44 @@
+"""Shared plumbing for Typer commands: error handling, client construction, output."""
+import functools
+from typing import Any, Callable, Tuple
+
+import typer
+
+from filtrix_cli import config as config_mod
+from filtrix_cli.client import FiltrixClient
+from filtrix_cli.output import CLIError, emit_error, emit_json, is_json_mode
+from filtrix_cli.render import render_human
+from filtrix_cli.state import get_state
+
+
+def command(func: Callable) -> Callable:
+    """Wrap a Typer command: catch CLIError, emit it, exit with its code.
+    functools.wraps keeps the original signature so Typer still sees the params."""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        json_mode = is_json_mode(get_state().json)
+        try:
+            return func(*args, **kwargs)
+        except CLIError as err:
+            emit_error(err, json_mode)
+            raise typer.Exit(err.exit_code)
+    return wrapper
+
+
+def build_client() -> Tuple[FiltrixClient, dict]:
+    state = get_state()
+    settings = config_mod.resolve_settings(
+        profile=state.profile, api_key=state.api_key, base_url=state.base_url
+    )
+    client = FiltrixClient(
+        base_url=settings["base_url"], api_key=settings["api_key"], jwt=settings["jwt"]
+    )
+    return client, settings
+
+
+def output_result(result: Any, *, kind: str) -> None:
+    state = get_state()
+    if is_json_mode(state.json):
+        emit_json(result)
+    else:
+        render_human(result, kind=kind, quiet=state.quiet, no_color=state.no_color)

filtrix_cli-0.1.0/src/filtrix_cli/commands/account.py

@@ -0,0 +1,9 @@
+from filtrix_cli.commands._helpers import build_client, command, output_result
+
+
+@command
+def account() -> None:
+    """Show your tier and remaining daily quota."""
+    client, _ = build_client()
+    result = client.account()
+    output_result(result, kind="account")