datalegion-cli 1.3.1__tar.gz → 1.5.0__tar.gz

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datalegion-cli
-Version: 1.3.1
+Version: 1.5.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
@@ -18,6 +18,7 @@ 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: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: cryptography>=44.0.0
@@ -164,7 +165,7 @@ datalegion-cli person enrich --name "Jane Smith" --company "Acme Corp" --city "N
 datalegion-cli person enrich --social-url "https://linkedin.com/in/johndoe"
 
 # Multiple results with minimum confidence
-datalegion-cli person enrich --email john@example.com --multiple --min-confidence high
+datalegion-cli person enrich --email john@example.com --min-confidence high
 
 # Select specific fields
 datalegion-cli person enrich --email john@example.com --fields "full_name,emails,phones"
@@ -270,12 +271,21 @@ datalegion-cli person enrich --email bad 2>/dev/null
 # {"ok": false, "error": "bad_request", "message": "..."}
 ```
 
+## 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.
+
+```bash
+datalegion-cli --sandbox person enrich --email anyone@example.com
+```
+
 ## Global flags
 
 | Flag | Description |
 |------|-------------|
 | `--verbose` / `-v` | Enable debug logging to stderr |
 | `--quiet` / `-q` | Suppress all log output |
+| `--sandbox` | Return sample records from enrich, search and discover, using no credits |
 | `--help` | Show help for any command |
 
 ## Development

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/README.md

@@ -130,7 +130,7 @@ datalegion-cli person enrich --name "Jane Smith" --company "Acme Corp" --city "N
 datalegion-cli person enrich --social-url "https://linkedin.com/in/johndoe"
 
 # Multiple results with minimum confidence
-datalegion-cli person enrich --email john@example.com --multiple --min-confidence high
+datalegion-cli person enrich --email john@example.com --min-confidence high
 
 # Select specific fields
 datalegion-cli person enrich --email john@example.com --fields "full_name,emails,phones"
@@ -236,12 +236,21 @@ datalegion-cli person enrich --email bad 2>/dev/null
 # {"ok": false, "error": "bad_request", "message": "..."}
 ```
 
+## 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.
+
+```bash
+datalegion-cli --sandbox person enrich --email anyone@example.com
+```
+
 ## Global flags
 
 | Flag | Description |
 |------|-------------|
 | `--verbose` / `-v` | Enable debug logging to stderr |
 | `--quiet` / `-q` | Suppress all log output |
+| `--sandbox` | Return sample records from enrich, search and discover, using no credits |
 | `--help` | Show help for any command |
 
 ## Development

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "datalegion-cli"
-version = "1.3.1"
+version = "1.5.0"
 description = "CLI for the Data Legion API — agent-friendly, fully async"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,6 +25,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Environment :: Console",
     "Typing :: Typed",
 ]

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/src/datalegion_cli/client.py

@@ -8,7 +8,7 @@ import httpx
 from loguru import logger
 
 from datalegion_cli import __version__
-from datalegion_cli.config import get_api_key, get_base_url
+from datalegion_cli.config import get_api_key, get_base_url, get_sandbox
 
 
 class APIError(Exception):
@@ -32,6 +32,15 @@ class APIError(Exception):
         return d
 
 
+# Endpoints the API mirrors under /sandbox/: sample records (Jane Sandbox, Sandbox Corp), no credits.
+# Utilities, reports, credits and dynamic bulk have no sandbox and call the real API.
+SANDBOX_PATHS = frozenset(
+    f"/{entity}/{op}"
+    for entity in ("person", "company")
+    for op in ("enrich", "enrich/bulk", "search", "discover")
+)
+
+
 class LegionClient:
     """Async client wrapping the Data Legion API."""
 
@@ -45,6 +54,7 @@ class LegionClient:
         self._base_url = base_url or get_base_url()
         self._api_key = (api_key or "").strip() or get_api_key()
         self._timeout = timeout
+        self._sandbox = get_sandbox()
         self._client: httpx.AsyncClient | None = None
         self.last_credits_used: str | None = None
         self.last_credits_remaining: str | None = None
@@ -77,6 +87,8 @@ class LegionClient:
         params: dict[str, Any] | None = None,
     ) -> dict[str, Any] | list[Any]:
         client = await self._get_client()
+        if self._sandbox and endpoint in SANDBOX_PATHS:
+            endpoint = f"/sandbox{endpoint}"
         logger.debug("{} {}", method.upper(), endpoint)
 
         if method.upper() == "GET":

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/src/datalegion_cli/commands/company.py

@@ -31,7 +31,6 @@ MinConfidence = Annotated[
 RequiredFields = Annotated[
     str | None, typer.Option("--required", help="Comma-separated required fields.")
 ]
-MultiOpt = Annotated[bool, typer.Option("--multiple", "-m", help="Return multiple matches.")]
 
 
 @app.command()
@@ -52,8 +51,6 @@ async def enrich(
     industry: Annotated[
         str | None, typer.Option("--industry", help="Industry (narrows name matching).")
     ] = None,
-    multiple: MultiOpt = False,
-    limit: LimitOpt = 2,
     min_confidence: MinConfidence = None,
     titlecase: TitleOpt = False,
     required_fields: RequiredFields = None,
@@ -67,7 +64,6 @@ async def enrich(
         datalegion-cli company enrich --domain google.com
         datalegion-cli company enrich --name "Acme Corp" --industry "Software"
         datalegion-cli company enrich --ticker AAPL --fields "name,industry,revenue"
-        datalegion-cli company enrich --linkedin-id 1441 --multiple --limit 5
         echo '{"domain":"stripe.com"}' | datalegion-cli company enrich --stdin
     """
     if stdin:
@@ -81,8 +77,6 @@ async def enrich(
             social_url=social_url,
             ticker_symbol=ticker_symbol,
             industry=industry,
-            multiple_results=multiple,
-            limit=limit,
             min_confidence=min_confidence,
             titlecase=titlecase,
             required_fields=required_fields,
@@ -168,8 +162,6 @@ async def discover(
 # @async_command
 # async def bulk(
 #     file: Annotated[str, typer.Argument(help="Path to JSON file with items array, or '-' for stdin.")],
-#     multiple: MultiOpt = False,
-#     limit: LimitOpt = 2,
 #     titlecase: TitleOpt = False,
 # ) -> None:
 #     """Bulk enrich up to 100 companies from a JSON file."""
@@ -184,8 +176,7 @@ async def discover(
 #     client = LegionClient()
 #     try:
 #         result = await client.company_bulk(
-#             items=items, multiple_results=multiple,
-#             limit=limit, titlecase=titlecase,
+#             items=items, titlecase=titlecase,
 #         )
 #         emit_json(result)
 #         emit_credits(client.last_credits_used, client.last_credits_remaining)

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/src/datalegion_cli/commands/person.py

@@ -31,7 +31,6 @@ MinConfidence = Annotated[
 RequiredFields = Annotated[
     str | None, typer.Option("--required", help="Comma-separated required fields.")
 ]
-MultiOpt = Annotated[bool, typer.Option("--multiple", "-m", help="Return multiple matches.")]
 
 
 @app.command()
@@ -67,8 +66,6 @@ async def enrich(
     postal_code: Annotated[
         str | None, typer.Option("--postal-code", help="Postal/ZIP code.")
     ] = None,
-    multiple: MultiOpt = False,
-    limit: LimitOpt = 2,
     min_confidence: MinConfidence = None,
     titlecase: TitleOpt = False,
     required_fields: RequiredFields = None,
@@ -82,7 +79,6 @@ async def enrich(
         datalegion-cli person enrich --email john@example.com
         datalegion-cli person enrich --name "Jane Doe" --company "Acme Corp"
         datalegion-cli person enrich --phone "+14155551234" --fields "name,email,title"
-        datalegion-cli person enrich --linkedin-id 12345 --multiple --limit 3
         echo '{"email":"jane@example.com"}' | datalegion-cli person enrich --stdin
     """
     if stdin:
@@ -107,8 +103,6 @@ async def enrich(
             birth_date=birth_date,
             address=address,
             postal_code=postal_code,
-            multiple_results=multiple,
-            limit=limit,
             min_confidence=min_confidence,
             titlecase=titlecase,
             required_fields=required_fields,
@@ -194,8 +188,6 @@ async def discover(
 # @async_command
 # async def bulk(
 #     file: Annotated[str, typer.Argument(help="Path to JSON file with items array, or '-' for stdin.")],
-#     multiple: MultiOpt = False,
-#     limit: LimitOpt = 2,
 #     titlecase: TitleOpt = False,
 # ) -> None:
 #     """Bulk enrich up to 100 people from a JSON file."""
@@ -211,8 +203,7 @@ async def discover(
 #     client = LegionClient()
 #     try:
 #         result = await client.person_bulk(
-#             items=items, multiple_results=multiple,
-#             limit=limit, titlecase=titlecase,
+#             items=items, titlecase=titlecase,
 #         )
 #         emit_json(result)
 #         emit_credits(client.last_credits_used, client.last_credits_remaining)

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/src/datalegion_cli/config.py

@@ -28,6 +28,7 @@ _DEFAULTS: dict[str, object] = {
     "default_output": "json",  # json | table | raw
     "install_method": "",  # brew | github | git | pip
     "device_id": "",  # random name for this machine's login key (see login.new_device_id)
+    "sandbox": False,  # sample records, no credits (see client.SANDBOX_PATHS)
 }
 
 # Fields that are stored encrypted on disk
@@ -94,6 +95,8 @@ def load_config() -> dict[str, object]:
         cfg["api_key"] = env_key
     if env_url := os.environ.get("LEGION_API_URL"):
         cfg["api_base_url"] = env_url
+    if env_sandbox := os.environ.get("LEGION_SANDBOX"):
+        cfg["sandbox"] = env_sandbox.strip().lower() in ("1", "true", "yes")
     return cfg
 
 
@@ -127,3 +130,8 @@ def get_api_key() -> str:
 
 def get_base_url() -> str:
     return str(load_config().get("api_base_url", _DEFAULTS["api_base_url"]))
+
+
+def get_sandbox() -> bool:
+    """Sandbox mode: the --sandbox flag, LEGION_SANDBOX, or `config set sandbox true`."""
+    return load_config().get("sandbox") is True

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/src/datalegion_cli/main.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from typing import Annotated
 
 import typer
@@ -36,9 +37,19 @@ app.add_typer(credits.app, name="credits")
 def main_callback(
     verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Enable debug logging.")] = False,
     quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress all log output.")] = False,
+    sandbox: Annotated[
+        bool,
+        typer.Option(
+            "--sandbox",
+            help="Return sample records from enrich, search and discover, using no credits.",
+        ),
+    ] = False,
 ) -> None:
     """Data Legion CLI."""
     setup_logging(verbose=verbose, quiet=quiet)
+    if sandbox:
+        # Read by config.load_config, so every client this run creates is in sandbox mode.
+        os.environ["LEGION_SANDBOX"] = "1"
 
 
 # ── Top-level commands ───────────────────────────────────────────────

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/tests/test_client.py

@@ -210,3 +210,47 @@ class TestConvenienceMethods:
         http = await self._setup_mock(mock_client, monkeypatch)
         await mock_client.credits_usage(start_date="2026-01-01", end_date="2026-03-01")
         assert http.get.call_args[0][0] == "/credits/usage"
+
+
+@pytest.mark.asyncio
+class TestSandbox:
+    """Sandbox mode sends only the endpoints the API mirrors to /sandbox/."""
+
+    async def _paths(self, monkeypatch, sandbox_env: str | None, endpoints: list[str]) -> list[str]:
+        if sandbox_env is None:
+            monkeypatch.delenv("LEGION_SANDBOX", raising=False)
+        else:
+            monkeypatch.setenv("LEGION_SANDBOX", sandbox_env)
+        client = LegionClient(base_url="https://x.local", api_key="legion_k")
+        mock_post = AsyncMock(return_value=make_response(200, {"matches": []}))
+        client._client = AsyncMock()
+        client._client.is_closed = False
+        client._client.post = mock_post
+        for endpoint in endpoints:
+            await client.request("POST", endpoint, payload={})
+        return [call.args[0] for call in mock_post.call_args_list]
+
+    async def test_sandbox_routes_only_mirrored_paths(self, monkeypatch):
+        paths = await self._paths(
+            monkeypatch, "1", ["/person/enrich", "/company/search", "/utility/clean"]
+        )
+        assert paths == ["/sandbox/person/enrich", "/sandbox/company/search", "/utility/clean"]
+
+    async def test_off_by_default(self, monkeypatch):
+        assert await self._paths(monkeypatch, None, ["/person/enrich"]) == ["/person/enrich"]
+
+    async def test_env_false_is_off(self, monkeypatch):
+        assert await self._paths(monkeypatch, "false", ["/person/enrich"]) == ["/person/enrich"]
+
+
+def test_sandbox_flag_turns_it_on(monkeypatch):
+    from typer.testing import CliRunner
+
+    from datalegion_cli.main import app
+
+    monkeypatch.delenv("LEGION_SANDBOX", raising=False)
+    CliRunner().invoke(app, ["--sandbox", "version"])
+    import os
+
+    assert os.environ.get("LEGION_SANDBOX") == "1"
+    monkeypatch.delenv("LEGION_SANDBOX", raising=False)

{datalegion_cli-1.3.1 → datalegion_cli-1.5.0}/tests/test_commands.py

@@ -438,3 +438,31 @@ class TestCreditsUsage:
         with _mock_client_request(response):
             result = runner.invoke(app, ["credits", "usage"])
         assert result.exit_code == 0
+
+
+# ── Several matches per lookup is an enterprise feature: no CLI option ──
+
+
+class TestEnrichOffersNoMultipleResults:
+    def test_enrich_rejects_multiple_and_limit(self, monkeypatch):
+        _mock_config(monkeypatch)
+        for entity, ident in (("person", ["--email", "a@b.co"]), ("company", ["--domain", "b.co"])):
+            for option in (["--multiple"], ["--limit", "3"]):
+                result = runner.invoke(app, [entity, "enrich", *ident, *option])
+                assert result.exit_code != 0, (entity, option)
+
+    def test_enrich_payload_carries_neither_field(self, monkeypatch):
+        _mock_config(monkeypatch)
+        sent: list[dict] = []
+
+        async def capture(self, method, endpoint, *, payload=None, params=None):
+            sent.append(payload or {})
+            return {"matches": [], "total": 0}
+
+        with patch("datalegion_cli.client.LegionClient.request", capture):
+            runner.invoke(app, ["person", "enrich", "--email", "a@b.co"])
+            runner.invoke(app, ["company", "enrich", "--domain", "b.co"])
+        assert len(sent) == 2
+        for payload in sent:
+            assert "multiple_results" not in payload
+            assert "limit" not in payload