datalegion-cli 1.7.1__tar.gz → 1.9.0__tar.gz

{datalegion_cli-1.7.1 → datalegion_cli-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datalegion-cli
-Version: 1.7.1
+Version: 1.9.0
 Summary: CLI for the Data Legion API — agent-friendly, fully async
 Project-URL: Homepage, https://www.datalegion.ai
 Project-URL: Documentation, https://www.datalegion.ai/docs
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 The official command-line interface for the [Data Legion](https://www.datalegion.ai) API. Built for both humans and AI agents.
 
-Look up people and companies by email, phone, name, domain, LinkedIn, or ticker symbol. Search using SQL syntax. Clean, hash, and validate data fields before or after enrichment. Track credit usage and manage your configuration — all from the terminal.
+Look up people and companies by email, phone, name, domain, LinkedIn, or ticker symbol. Search using SQL syntax. Clean, hash, and validate data fields before or after enrichment. Track credit usage and manage your configuration, all from the terminal.
 
 ```bash
 pip install datalegion-cli
@@ -47,12 +47,12 @@ datalegion-cli person enrich --email john@example.com
 
 ## Features
 
-- **Fully async** — async from entry point to HTTP client, powered by `asyncio` and `httpx`
-- **Agent-friendly** — all output is JSON to stdout, logs go to stderr, supports `--stdin` for piping
+- **Fully async**: async from entry point to HTTP client, powered by `asyncio` and `httpx`
+- **Agent-friendly**: all output is JSON to stdout, logs go to stderr, supports `--stdin` for piping
 - **Search warnings**: when `search` or `discover` flags one of your filters (for example an industry name no stored value matches), the API's explanation is printed on stderr as `search warning: ...`; stdout stays JSON
-- **Encrypted config** — API keys are stored encrypted at rest (Fernet + PBKDF2, machine-tied)
-- **Auto-update** — checks PyPI for a newer release and self-updates via Homebrew, GitHub release, git pull, or pip/uv
-- **Multiple install methods** — Homebrew, GitHub release, pip/uv (with private index support), or from source
+- **Encrypted config**: API keys are stored encrypted at rest (Fernet + PBKDF2, machine-tied)
+- **Auto-update**: checks PyPI for a newer release and self-updates via Homebrew, GitHub release, git pull, or pip/uv
+- **Multiple install methods**: Homebrew, GitHub release, pip/uv (with private index support), or from source
 
 ## Installation
 
@@ -165,6 +165,9 @@ datalegion-cli person enrich --name "Jane Smith" --company "Acme Corp" --city "N
 # By LinkedIn
 datalegion-cli person enrich --social-url "https://linkedin.com/in/johndoe"
 
+# By NPI (10-digit National Provider Identifier)
+datalegion-cli person enrich --npi 1234567893
+
 # Minimum confidence
 datalegion-cli person enrich --email john@example.com --min-confidence high
 
@@ -179,6 +182,13 @@ datalegion-cli person enrich --email john@example.com --fields "full_name,emails
 datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'CA'" --limit 5
 ```
 
+`query` can also be an Elasticsearch-style query object as JSON (`bool`, `term`, `terms`, `match`, `match_phrase`, `range`, `exists`, `prefix`, `wildcard`, `nested`), on the response's own field names. For deep paging, pass each page's `next_cursor` back with `--cursor`; the last page has none. Company search takes both too.
+
+```bash
+datalegion-cli person search '{"bool": {"filter": [{"term": {"company_name": "google"}}, {"match": {"job_title": "engineer"}}]}}' --limit 100
+datalegion-cli person search "SELECT * FROM people WHERE state = 'ohio'" --limit 100 --cursor "<next_cursor from the last page>"
+```
+
 ### Person Discovery (Beta)
 
 ```bash
@@ -186,6 +196,22 @@ datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%go
 datalegion-cli person discover "software engineers in San Francisco who know Rust" --limit 10
 ```
 
+For the next page, pass the last page's `next_cursor` with `--cursor` and the same query: it reruns the same search. Company discover takes it too.
+
+```bash
+query="software engineers in San Francisco who know Rust"
+cursor=""
+while :; do
+  # A failed page (a 429, 402 or 403) prints its error and stops the loop
+  page=$(datalegion-cli person discover "$query" --limit 100 ${cursor:+--cursor} ${cursor:+"$cursor"}) || { printf '%s\n' "$page" >&2; break; }
+  printf '%s\n' "$page" | jq -r '.matches[].person.legion_id'
+  cursor=$(printf '%s\n' "$page" | jq -r '.next_cursor // empty')
+  [ -z "$cursor" ] && break
+  sleep 6  # Discover answers 10 requests a minute
+done
+[ -n "$cursor" ] && echo "stopped early; resume with --cursor $cursor" >&2
+```
+
 ### Company Enrichment
 
 ```bash
@@ -258,7 +284,7 @@ datalegion-cli version
 The CLI is designed to be called by AI agents and scripts. Key patterns:
 
 ```bash
-# All output is JSON to stdout — parse it directly
+# All output is JSON to stdout; parse it directly
 datalegion-cli person enrich --email john@example.com | jq '.matches[0].person.full_name'
 
 # Pipe JSON payloads via stdin
@@ -274,7 +300,7 @@ datalegion-cli person enrich --email bad 2>/dev/null
 
 ## Sandbox
 
-Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes Enrich, Bulk Enrich, Search and Discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
+Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes enrich, search and discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
 
 ```bash
 datalegion-cli --sandbox person enrich --email anyone@example.com

{datalegion_cli-1.7.1 → datalegion_cli-1.9.0}/README.md

@@ -2,7 +2,7 @@
 
 The official command-line interface for the [Data Legion](https://www.datalegion.ai) API. Built for both humans and AI agents.
 
-Look up people and companies by email, phone, name, domain, LinkedIn, or ticker symbol. Search using SQL syntax. Clean, hash, and validate data fields before or after enrichment. Track credit usage and manage your configuration — all from the terminal.
+Look up people and companies by email, phone, name, domain, LinkedIn, or ticker symbol. Search using SQL syntax. Clean, hash, and validate data fields before or after enrichment. Track credit usage and manage your configuration, all from the terminal.
 
 ```bash
 pip install datalegion-cli
@@ -12,12 +12,12 @@ datalegion-cli person enrich --email john@example.com
 
 ## Features
 
-- **Fully async** — async from entry point to HTTP client, powered by `asyncio` and `httpx`
-- **Agent-friendly** — all output is JSON to stdout, logs go to stderr, supports `--stdin` for piping
+- **Fully async**: async from entry point to HTTP client, powered by `asyncio` and `httpx`
+- **Agent-friendly**: all output is JSON to stdout, logs go to stderr, supports `--stdin` for piping
 - **Search warnings**: when `search` or `discover` flags one of your filters (for example an industry name no stored value matches), the API's explanation is printed on stderr as `search warning: ...`; stdout stays JSON
-- **Encrypted config** — API keys are stored encrypted at rest (Fernet + PBKDF2, machine-tied)
-- **Auto-update** — checks PyPI for a newer release and self-updates via Homebrew, GitHub release, git pull, or pip/uv
-- **Multiple install methods** — Homebrew, GitHub release, pip/uv (with private index support), or from source
+- **Encrypted config**: API keys are stored encrypted at rest (Fernet + PBKDF2, machine-tied)
+- **Auto-update**: checks PyPI for a newer release and self-updates via Homebrew, GitHub release, git pull, or pip/uv
+- **Multiple install methods**: Homebrew, GitHub release, pip/uv (with private index support), or from source
 
 ## Installation
 
@@ -130,6 +130,9 @@ datalegion-cli person enrich --name "Jane Smith" --company "Acme Corp" --city "N
 # By LinkedIn
 datalegion-cli person enrich --social-url "https://linkedin.com/in/johndoe"
 
+# By NPI (10-digit National Provider Identifier)
+datalegion-cli person enrich --npi 1234567893
+
 # Minimum confidence
 datalegion-cli person enrich --email john@example.com --min-confidence high
 
@@ -144,6 +147,13 @@ datalegion-cli person enrich --email john@example.com --fields "full_name,emails
 datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'CA'" --limit 5
 ```
 
+`query` can also be an Elasticsearch-style query object as JSON (`bool`, `term`, `terms`, `match`, `match_phrase`, `range`, `exists`, `prefix`, `wildcard`, `nested`), on the response's own field names. For deep paging, pass each page's `next_cursor` back with `--cursor`; the last page has none. Company search takes both too.
+
+```bash
+datalegion-cli person search '{"bool": {"filter": [{"term": {"company_name": "google"}}, {"match": {"job_title": "engineer"}}]}}' --limit 100
+datalegion-cli person search "SELECT * FROM people WHERE state = 'ohio'" --limit 100 --cursor "<next_cursor from the last page>"
+```
+
 ### Person Discovery (Beta)
 
 ```bash
@@ -151,6 +161,22 @@ datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%go
 datalegion-cli person discover "software engineers in San Francisco who know Rust" --limit 10
 ```
 
+For the next page, pass the last page's `next_cursor` with `--cursor` and the same query: it reruns the same search. Company discover takes it too.
+
+```bash
+query="software engineers in San Francisco who know Rust"
+cursor=""
+while :; do
+  # A failed page (a 429, 402 or 403) prints its error and stops the loop
+  page=$(datalegion-cli person discover "$query" --limit 100 ${cursor:+--cursor} ${cursor:+"$cursor"}) || { printf '%s\n' "$page" >&2; break; }
+  printf '%s\n' "$page" | jq -r '.matches[].person.legion_id'
+  cursor=$(printf '%s\n' "$page" | jq -r '.next_cursor // empty')
+  [ -z "$cursor" ] && break
+  sleep 6  # Discover answers 10 requests a minute
+done
+[ -n "$cursor" ] && echo "stopped early; resume with --cursor $cursor" >&2
+```
+
 ### Company Enrichment
 
 ```bash
@@ -223,7 +249,7 @@ datalegion-cli version
 The CLI is designed to be called by AI agents and scripts. Key patterns:
 
 ```bash
-# All output is JSON to stdout — parse it directly
+# All output is JSON to stdout; parse it directly
 datalegion-cli person enrich --email john@example.com | jq '.matches[0].person.full_name'
 
 # Pipe JSON payloads via stdin
@@ -239,7 +265,7 @@ datalegion-cli person enrich --email bad 2>/dev/null
 
 ## Sandbox
 
-Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes Enrich, Bulk Enrich, Search and Discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
+Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes enrich, search and discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
 
 ```bash
 datalegion-cli --sandbox person enrich --email anyone@example.com

{datalegion_cli-1.7.1 → datalegion_cli-1.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "datalegion-cli"
-version = "1.7.1"
+version = "1.9.0"
 description = "CLI for the Data Legion API — agent-friendly, fully async"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -103,5 +103,12 @@ ignore = [
 known-first-party = ["datalegion_cli"]
 
 [tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"
 asyncio_mode = "auto"
-testpaths = ["tests"]
+testpaths = ["tests"]
+
+[tool.uv]
+# 0.11.8 writes the lock's sentinel form for a relative exclude-newer (below).
+required-version = ">=0.11.8"
+# The fleet's one-day cooldown: no release under 24 h old is resolved, by any uv command here.
+exclude-newer = "1 day"

datalegion_cli-1.9.0/src/datalegion_cli/commands/__init__.py

@@ -0,0 +1,26 @@
+"""CLI command modules."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any
+
+import typer
+
+CursorOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--cursor",
+        help="The previous page's next_cursor, with the same query, for the next page (search: in place of --offset).",
+    ),
+]
+
+
+def search_query(text: str) -> str | dict[str, Any]:
+    """SQL as given, or a query object when the argument is a JSON object."""
+    if not text.lstrip().startswith("{"):
+        return text
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(f"The query looks like JSON but doesn't parse: {e.msg}.") from e

{datalegion_cli-1.7.1 → datalegion_cli-1.9.0}/src/datalegion_cli/commands/company.py

@@ -10,6 +10,7 @@ import typer
 
 from datalegion_cli.async_typer import async_command
 from datalegion_cli.client import APIError, LegionClient
+from datalegion_cli.commands import CursorOpt, search_query
 from datalegion_cli.output import emit_credits, emit_error, emit_json, emit_search_warning
 
 app = typer.Typer(name="company", help="Company enrichment, search, and discovery.")
@@ -102,8 +103,14 @@ async def enrich(
 @app.command()
 @async_command
 async def search(
-    query: Annotated[str, typer.Argument(help="SQL SELECT query against the companies table.")],
+    query: Annotated[
+        str,
+        typer.Argument(
+            help="SQL SELECT query against the companies table, or a query object as JSON."
+        ),
+    ],
     limit: LimitOpt = 1,
+    cursor: CursorOpt = None,
     titlecase: TitleOpt = False,
     include_fields: FieldsInclude = None,
     exclude_fields: FieldsExclude = None,
@@ -114,12 +121,15 @@ async def search(
         datalegion-cli company search "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100"
         datalegion-cli company search "SELECT * FROM companies WHERE name ILIKE '%tech%'" --limit 20
         datalegion-cli company search "SELECT * FROM companies WHERE domain = 'stripe.com'" --fields "name,domain,industry"
+        datalegion-cli company search '{"term": {"domain": "stripe.com"}}'
+        datalegion-cli company search "SELECT * FROM companies WHERE industry = 'banking'" --limit 100 --cursor <next_cursor>
     """
     client = LegionClient()
     try:
         result = await client.company_search(
-            query=query,
+            query=search_query(query),
             limit=limit,
+            cursor=cursor,
             titlecase=titlecase,
             include_fields=include_fields,
             exclude_fields=exclude_fields,
@@ -139,16 +149,23 @@ async def search(
 async def discover(
     query: Annotated[str, typer.Argument(help="Natural language company search query.")],
     limit: LimitOpt = 1,
+    cursor: CursorOpt = None,
     titlecase: TitleOpt = False,
     include_fields: FieldsInclude = None,
     exclude_fields: FieldsExclude = None,
 ) -> None:
-    """Search for companies using natural language (Beta)."""
+    """Search for companies using natural language (Beta).
+
+    For the next page, pass the previous page's next_cursor as --cursor with the same query: it reruns the same search.
+
+        datalegion-cli company discover "banks in Ohio" --limit 100 --cursor <next_cursor>
+    """
     client = LegionClient()
     try:
         result = await client.company_discover(
             query=query,
             limit=limit,
+            cursor=cursor,
             titlecase=titlecase,
             include_fields=include_fields,
             exclude_fields=exclude_fields,

{datalegion_cli-1.7.1 → datalegion_cli-1.9.0}/src/datalegion_cli/commands/person.py

@@ -10,6 +10,7 @@ import typer
 
 from datalegion_cli.async_typer import async_command
 from datalegion_cli.client import APIError, LegionClient
+from datalegion_cli.commands import CursorOpt, search_query
 from datalegion_cli.output import emit_credits, emit_error, emit_json, emit_search_warning
 
 app = typer.Typer(name="person", help="Person enrichment, search, and discovery.")
@@ -52,6 +53,9 @@ async def enrich(
     email_hash: Annotated[
         str | None, typer.Option("--email-hash", help="SHA-256/SHA-1/MD5 email hash.")
     ] = None,
+    npi: Annotated[
+        str | None, typer.Option("--npi", help="10-digit National Provider Identifier.")
+    ] = None,
     full_name: Annotated[str | None, typer.Option("--name", "-n", help="Full name.")] = None,
     first_name: Annotated[str | None, typer.Option("--first-name", help="First name.")] = None,
     last_name: Annotated[str | None, typer.Option("--last-name", help="Last name.")] = None,
@@ -82,6 +86,7 @@ async def enrich(
     Examples:
         datalegion-cli person enrich --email john@example.com
         datalegion-cli person enrich --name "Jane Doe" --company "Acme Corp"
+        datalegion-cli person enrich --npi 1234567893
         datalegion-cli person enrich --phone "+14155551234" --fields "full_name,work_email,job_title"
         echo '{"email":"jane@example.com"}' | datalegion-cli person enrich --stdin
     """
@@ -95,6 +100,7 @@ async def enrich(
             social_url=social_url,
             legion_id=legion_id,
             email_hash=email_hash,
+            npi=npi,
             full_name=full_name,
             first_name=first_name,
             last_name=last_name,
@@ -128,8 +134,14 @@ async def enrich(
 @app.command()
 @async_command
 async def search(
-    query: Annotated[str, typer.Argument(help="SQL SELECT query against the people table.")],
+    query: Annotated[
+        str,
+        typer.Argument(
+            help="SQL SELECT query against the people table, or a query object as JSON."
+        ),
+    ],
     limit: LimitOpt = 1,
+    cursor: CursorOpt = None,
     titlecase: TitleOpt = False,
     include_fields: FieldsInclude = None,
     exclude_fields: FieldsExclude = None,
@@ -139,12 +151,15 @@ async def search(
     Examples:
         datalegion-cli person search "SELECT * FROM people WHERE job_title = 'ceo' AND company_name ILIKE '%acme%'"
         datalegion-cli person search "SELECT * FROM people WHERE city = 'san francisco'" --limit 20
+        datalegion-cli person search '{"term": {"company_name": "acme"}}' --limit 100
+        datalegion-cli person search "SELECT * FROM people WHERE state = 'ohio'" --limit 100 --cursor <next_cursor>
     """
     client = LegionClient()
     try:
         result = await client.person_search(
-            query=query,
+            query=search_query(query),
             limit=limit,
+            cursor=cursor,
             titlecase=titlecase,
             include_fields=include_fields,
             exclude_fields=exclude_fields,
@@ -164,16 +179,23 @@ async def search(
 async def discover(
     query: Annotated[str, typer.Argument(help="Natural language search query.")],
     limit: LimitOpt = 1,
+    cursor: CursorOpt = None,
     titlecase: TitleOpt = False,
     include_fields: FieldsInclude = None,
     exclude_fields: FieldsExclude = None,
 ) -> None:
-    """Search for people using natural language (Beta)."""
+    """Search for people using natural language (Beta).
+
+    For the next page, pass the previous page's next_cursor as --cursor with the same query: it reruns the same search.
+
+        datalegion-cli person discover "nurses in Ohio" --limit 100 --cursor <next_cursor>
+    """
     client = LegionClient()
     try:
         result = await client.person_discover(
             query=query,
             limit=limit,
+            cursor=cursor,
             titlecase=titlecase,
             include_fields=include_fields,
             exclude_fields=exclude_fields,

{datalegion_cli-1.7.1 → datalegion_cli-1.9.0}/tests/test_commands.py

@@ -135,6 +135,20 @@ class TestPersonEnrich:
             )
         assert result.exit_code == 0
 
+    def test_enrich_by_npi_sends_it(self, monkeypatch):
+        _mock_config(monkeypatch)
+        sent = {}
+
+        async def fake_request(self, method, endpoint, *, payload=None, params=None):
+            sent.update(endpoint=endpoint, payload=payload)
+            return {"matches": [{"full_name": "Jane Smith"}]}
+
+        with patch("datalegion_cli.client.LegionClient.request", fake_request):
+            result = runner.invoke(app, ["person", "enrich", "--npi", "1234567893"])
+        assert result.exit_code == 0, result.output
+        assert sent["endpoint"].endswith("/person/enrich")
+        assert sent["payload"]["npi"] == "1234567893"
+
     def test_enrich_stdin(self, monkeypatch):
         _mock_config(monkeypatch)
         response = {"matches": [{"full_name": "Bob"}], "total": 1}
@@ -168,6 +182,52 @@ class TestPersonSearch:
         assert result.exit_code == 0
 
 
+class TestSearchQueryObjectAndCursor:
+    @pytest.mark.parametrize("entity", ["person", "company"])
+    def test_a_json_query_goes_as_an_object_with_the_cursor(self, monkeypatch, entity):
+        _mock_config(monkeypatch)
+        sent = []
+
+        async def fake_request(self, method, endpoint, *, payload=None, params=None):
+            sent.append(payload)
+            return {"matches": [], "total": 0, "next_cursor": "abc"}
+
+        monkeypatch.setattr("datalegion_cli.client.LegionClient.request", fake_request)
+        result = runner.invoke(
+            app, [entity, "search", '{"exists": {"field": "legion_id"}}', "--cursor", "abc"]
+        )
+        assert result.exit_code == 0, result.output
+        assert sent[0]["query"] == {"exists": {"field": "legion_id"}}
+        assert sent[0]["cursor"] == "abc"
+        assert json.loads(result.stdout)["next_cursor"] == "abc"
+
+    @pytest.mark.parametrize("entity", ["person", "company"])
+    def test_discover_sends_the_cursor_and_prints_next_cursor(self, monkeypatch, entity):
+        _mock_config(monkeypatch)
+        sent = []
+
+        async def fake_request(self, method, endpoint, *, payload=None, params=None):
+            sent.append((endpoint, payload))
+            return {"matches": [], "total": 0, "next_cursor": "def", "generated_query": "SELECT 1"}
+
+        monkeypatch.setattr("datalegion_cli.client.LegionClient.request", fake_request)
+        result = runner.invoke(app, [entity, "discover", "nurses in Ohio", "--cursor", "abc"])
+        assert result.exit_code == 0, result.output
+        assert sent[0][0] == f"/{entity}/discover"
+        assert sent[0][1]["query"] == "nurses in Ohio" and sent[0][1]["cursor"] == "abc"
+        assert json.loads(result.stdout)["next_cursor"] == "def"
+
+    def test_a_query_that_looks_like_json_but_does_not_parse_is_refused(self, monkeypatch):
+        _mock_config(monkeypatch)
+        result = runner.invoke(app, ["person", "search", "{not json"])
+        assert result.exit_code == 2
+
+    def test_sql_stays_a_string(self):
+        from datalegion_cli.commands import search_query
+
+        assert search_query("SELECT * FROM people") == "SELECT * FROM people"
+
+
 class TestPersonDiscover:
     def test_discover(self, monkeypatch):
         _mock_config(monkeypatch)

datalegion_cli-1.7.1/src/datalegion_cli/commands/__init__.py

@@ -1 +0,0 @@
-"""CLI command modules."""