databar 2.0.4__tar.gz → 2.0.6__tar.gz

{databar-2.0.4/src/databar.egg-info → databar-2.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databar
-Version: 2.0.4
+Version: 2.0.6
 Summary: Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai
 Author-email: "Databar.ai Team" <info@databar.ai>
 License: MIT License

{databar-2.0.4 → databar-2.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databar"
-version = "2.0.4"
+version = "2.0.6"
 description = "Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai"
 readme = "README.md"
 license = { file = "LICENSE" }

{databar-2.0.4 → databar-2.0.6}/src/databar/__init__.py

@@ -45,6 +45,7 @@ from .models import (
     EnrichmentSummary,
     InsertOptions,
     InsertRow,
+    RowsResponse,
     RunResponse,
     Table,
     TableEnrichment,
@@ -57,7 +58,7 @@ from .models import (
     WaterfallEnrichment,
 )
 
-__version__ = "2.0.4"
+__version__ = "2.0.6"
 __all__ = [
     "DatabarClient",
     # exceptions
@@ -87,6 +88,7 @@ __all__ = [
     "Table",
     "Column",
     "TableEnrichment",
+    "RowsResponse",
     "InsertRow",
     "InsertOptions",
     "DedupeOptions",

databar-2.0.6/src/databar/cli/_guide.py

@@ -0,0 +1,137 @@
+"""Embedded agent guide — printed by `databar agent-guide`."""
+
+AGENT_GUIDE = r"""# Databar SDK & CLI — Agent Guide
+
+Official Databar Python SDK and CLI (`pip install databar`).
+Run data enrichments, waterfall lookups, and manage tables via api.databar.ai/v1.
+
+## Setup
+
+```bash
+pip install databar
+export DATABAR_API_KEY=YOUR_API_KEY   # or: databar login --api-key YOUR_API_KEY
+databar whoami                        # verify auth
+```
+
+If `databar` command not found after install:
+```bash
+export PATH="$(python3 -m site --user-base)/bin:$PATH"
+```
+
+## CLI Quick Reference
+
+All commands support `--format table|json|csv` (default: table) and `--help`.
+**For machine-parseable output, always use `--format json`.**
+
+### Enrichments
+```
+databar enrich list                          # list all enrichments
+databar enrich list --query "linkedin"       # search enrichments
+databar enrich get <id>                      # get enrichment details (params, response fields)
+databar enrich choices <id> <param>          # list choices for a select param
+databar enrich run <id> --params '{"key": "value"}'   # run single
+databar enrich bulk <id> --input data.csv --out results.csv
+```
+
+### Waterfalls
+```
+databar waterfall list
+databar waterfall get <identifier>           # e.g. email_getter
+databar waterfall run <identifier> --params '{"key": "value"}'
+databar waterfall bulk <identifier> --input data.csv --out results.csv
+```
+
+### Tables
+```
+databar table list
+databar table create --name "My Table" --columns "email,name,company"
+databar table columns <table-uuid>
+databar table rows <table-uuid>
+databar table rows <table-uuid> --format json
+
+databar table insert <table-uuid> --data '[{"email":"a@b.com","name":"Alice"}]'
+databar table insert <table-uuid> --input data.csv --allow-new-columns
+
+databar table enrichments <table-uuid>
+databar table add-enrichment <table-uuid> --enrichment-id <id> --mapping '{"param": "column_name"}'
+databar table run-enrichment <table-uuid> --enrichment-id <TABLE-ENRICHMENT-ID>
+```
+
+Note: `run-enrichment` uses the TABLE-ENRICHMENT ID (from `add-enrichment` or `table enrichments`), NOT the catalog enrichment ID.
+
+### Tasks
+```
+databar task get <task-id>                   # check status once
+databar task get <task-id> --poll            # poll until complete
+```
+
+### Account
+```
+databar whoami
+databar whoami --format json
+```
+
+## Python SDK Quick Reference
+
+```python
+from databar import DatabarClient
+
+client = DatabarClient()  # reads DATABAR_API_KEY from env
+
+# Enrichments
+enrichments = client.list_enrichments(q="linkedin")
+enrichment = client.get_enrichment(123)
+# enrichment.params → list of EnrichmentParam (fields: .name, .is_required, .description)
+# enrichment.response_fields → list of EnrichmentResponseField (fields: .name, .type_field)
+
+result = client.run_enrichment_sync(123, {"email": "alice@example.com"})
+
+# Waterfalls
+waterfalls = client.list_waterfalls()
+# waterfall.identifier → slug like "email_getter" (also available as .slug)
+result = client.run_waterfall_sync("email_getter", {"linkedin_url": "..."})
+
+# Tables
+tables = client.list_tables()
+# table.identifier → UUID (also available as .id and .uuid)
+table = client.create_table(name="Leads", columns=["email", "name"])
+resp = client.get_rows(table.identifier)
+# resp.data → list of row dicts, resp.has_next_page, resp.total_count, resp.page
+
+from databar import InsertRow
+client.create_rows(table.identifier, [
+    InsertRow(fields={"email": "alice@example.com", "name": "Alice"}),
+])
+```
+
+## Key Concepts
+
+- All enrichment/waterfall runs are async: submit → get task_id → poll until completed.
+  The `*_sync` methods handle this automatically.
+- task_id is the universal identifier for polling. Use it with poll_task() or `databar task get`.
+- Results expire after 1 hour (status becomes "gone").
+- Table enrichments are a two-step process: add_enrichment() then run_table_enrichment().
+  The ID from add_enrichment is a TABLE-ENRICHMENT ID, different from the catalog enrichment ID.
+- The SDK auto-resolves column names to UUIDs in add_enrichment().
+
+## Model Field Aliases
+
+Common aliases that work on all models:
+- Table: .id, .uuid → .identifier
+- Waterfall: .slug → .identifier
+- EnrichmentParam: .slug → .name, .label → .description, .required → .is_required
+- EnrichmentResponseField: .slug → .name, .label → .name
+
+## Error Handling
+
+```python
+from databar import (
+    DatabarAuthError,                  # 401/403
+    DatabarInsufficientCreditsError,   # 406
+    DatabarNotFoundError,              # 404
+    DatabarTaskFailedError,            # task completed with error
+    DatabarTimeoutError,               # polling timed out
+    DatabarGoneError,                  # task data expired (>1 hour)
+)
+```
+"""

databar-2.0.6/src/databar/cli/_onboard.py

@@ -0,0 +1,289 @@
+"""
+`databar onboard` — interactive first-run setup wizard.
+
+Guides the user through:
+  1. Displaying the Databar welcome banner
+  2. API key entry & verification
+  3. PATH detection & optional auto-fix
+  4. Usage preference (CLI / Python SDK / both)
+  5. Tailored next-steps cheatsheet
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich.rule import Rule
+from rich.text import Text
+
+console = Console()
+
+# ---------------------------------------------------------------------------
+# ASCII banner
+# ---------------------------------------------------------------------------
+
+BANNER = r"""
+  ____        _        _
+ |  _ \  __ _| |_ __ _| |__   __ _ _ __
+ | | | |/ _` | __/ _` | '_ \ / _` | '__|
+ | |_| | (_| | || (_| | |_) | (_| | |
+ |____/ \__,_|\__\__,_|_.__/ \__,_|_|
+
+"""
+
+TAGLINE = "Data enrichment at your fingertips."
+
+# ---------------------------------------------------------------------------
+# Config helpers (mirrors _auth.py)
+# ---------------------------------------------------------------------------
+
+CONFIG_DIR = Path.home() / ".databar"
+CONFIG_FILE = CONFIG_DIR / "config"
+_KEY_PREFIX = "api_key="
+_PREF_PREFIX = "preferred_interface="
+
+
+def _save_key(api_key: str) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    if CONFIG_FILE.exists():
+        lines = [
+            l for l in CONFIG_FILE.read_text().splitlines()
+            if not l.startswith(_KEY_PREFIX)
+        ]
+    lines.append(f"{_KEY_PREFIX}{api_key}")
+    CONFIG_FILE.write_text("\n".join(lines) + "\n")
+    CONFIG_FILE.chmod(0o600)
+
+
+def _save_preference(pref: str) -> None:
+    lines: list[str] = []
+    if CONFIG_FILE.exists():
+        lines = [
+            l for l in CONFIG_FILE.read_text().splitlines()
+            if not l.startswith(_PREF_PREFIX)
+        ]
+    lines.append(f"{_PREF_PREFIX}{pref}")
+    CONFIG_FILE.write_text("\n".join(lines) + "\n")
+
+
+def _get_bin_dir() -> Path:
+    return Path(sys.executable).parent
+
+
+def _databar_on_path() -> bool:
+    return shutil.which("databar") is not None
+
+
+def _detect_shell_profile() -> Path | None:
+    shell = os.environ.get("SHELL", "")
+    home = Path.home()
+    if "zsh" in shell:
+        return home / ".zshrc"
+    if "bash" in shell:
+        profile = home / ".bash_profile"
+        return profile if profile.exists() else home / ".bashrc"
+    return None
+
+
+def _add_to_path(bin_dir: Path) -> bool:
+    """Append export PATH line to the detected shell profile. Returns True on success."""
+    profile = _detect_shell_profile()
+    if profile is None:
+        return False
+    export_line = f'\nexport PATH="{bin_dir}:$PATH"  # added by databar onboard\n'
+    with open(profile, "a") as f:
+        f.write(export_line)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Onboard steps
+# ---------------------------------------------------------------------------
+
+def _print_banner() -> None:
+    banner_text = Text(BANNER, style="bold cyan")
+    tagline_text = Text(f"  {TAGLINE}\n", style="dim")
+    console.print(banner_text, end="")
+    console.print(tagline_text)
+    console.print(Rule(style="cyan"))
+    console.print()
+
+
+def _step_api_key() -> str | None:
+    """Prompt for API key, save it, and verify with a whoami call."""
+    console.print("[bold]Step 1 — Connect your account[/bold]")
+    console.print(
+        "[dim]Get your API key at [link=https://databar.ai]databar.ai[/link] "
+        "→ Settings → API Keys[/dim]\n"
+    )
+
+    existing_key: str | None = None
+    if CONFIG_FILE.exists():
+        for line in CONFIG_FILE.read_text().splitlines():
+            if line.startswith(_KEY_PREFIX):
+                existing_key = line[len(_KEY_PREFIX):].strip()
+                break
+    if not existing_key:
+        existing_key = os.environ.get("DATABAR_API_KEY", "").strip() or None
+
+    if existing_key:
+        masked = existing_key[:6] + "•" * (len(existing_key) - 10) + existing_key[-4:]
+        use_existing = Confirm.ask(
+            f"  Found existing key [bold]{masked}[/bold] — use it?",
+            default=True,
+        )
+        if use_existing:
+            api_key = existing_key
+        else:
+            api_key = Prompt.ask("  Enter your Databar API key", password=True).strip()
+    else:
+        api_key = Prompt.ask("  Enter your Databar API key", password=True).strip()
+
+    if not api_key:
+        console.print("[yellow]  Skipped — you can run `databar login` later.[/yellow]\n")
+        return None
+
+    console.print("  [dim]Verifying…[/dim]", end="")
+    try:
+        from databar.client import DatabarClient
+        client = DatabarClient(api_key=api_key)
+        user = client.get_user()
+        client.close()
+        _save_key(api_key)
+        console.print(
+            f"\r  [bold green]✓[/bold green] Authenticated as "
+            f"[bold]{user.first_name or user.email}[/bold] "
+            f"([dim]{user.balance:.0f} credits[/dim])\n"
+        )
+        return api_key
+    except Exception as e:
+        console.print(f"\r  [bold red]✗[/bold red] Could not verify key: {e}\n")
+        console.print("  [dim]Key not saved. Run `databar login` to try again.[/dim]\n")
+        return None
+
+
+def _step_path() -> None:
+    """Check PATH and offer to fix it."""
+    console.print("[bold]Step 2 — Fix PATH (so `databar` works anywhere)[/bold]")
+
+    if _databar_on_path():
+        console.print("  [bold green]✓[/bold green] `databar` is already on your PATH.\n")
+        return
+
+    bin_dir = _get_bin_dir()
+    console.print(
+        f"  [yellow]![/yellow] `databar` is not on PATH.\n"
+        f"  It's installed at: [bold]{bin_dir}/databar[/bold]\n"
+    )
+
+    profile = _detect_shell_profile()
+    profile_label = str(profile) if profile else "your shell profile"
+    fix = Confirm.ask(
+        f"  Add `{bin_dir}` to PATH in {profile_label} automatically?",
+        default=True,
+    )
+    if fix:
+        ok = _add_to_path(bin_dir)
+        if ok:
+            console.print(
+                f"  [bold green]✓[/bold green] Added to {profile_label}.\n"
+                f"  Run [bold]source {profile_label}[/bold] or open a new terminal to apply.\n"
+            )
+        else:
+            console.print(
+                f"  [yellow]Could not detect your shell profile.[/yellow]\n"
+                f"  Add this manually:\n\n"
+                f"    [bold]export PATH=\"{bin_dir}:$PATH\"[/bold]\n"
+            )
+    else:
+        console.print(
+            f"  [dim]Skipped. Use the full path for now: [bold]{bin_dir}/databar[/bold][/dim]\n"
+        )
+
+
+def _step_preference() -> str:
+    """Ask how the user plans to use Databar and return their choice."""
+    console.print("[bold]Step 3 — How do you plan to use Databar?[/bold]\n")
+    console.print("  [bold cyan]1[/bold cyan]  CLI       — terminal commands, scripts, AI agents (Claude Code etc.)")
+    console.print("  [bold cyan]2[/bold cyan]  Python    — import DatabarClient in your Python code")
+    console.print("  [bold cyan]3[/bold cyan]  Both      — I'll use whichever fits the task\n")
+
+    choice = Prompt.ask("  Your choice", choices=["1", "2", "3"], default="3")
+    pref_map = {"1": "cli", "2": "python", "3": "both"}
+    pref = pref_map[choice]
+    _save_preference(pref)
+    console.print()
+    return pref
+
+
+def _step_next_steps(pref: str) -> None:
+    """Print tailored next steps based on preference."""
+    console.print(Rule(style="cyan"))
+    console.print()
+    console.print("[bold green]You're all set![/bold green] Here's where to start:\n")
+
+    if pref in ("cli", "both"):
+        console.print(Panel(
+            "[bold]CLI Quick Start[/bold]\n\n"
+            "  databar enrich list                          [dim]# browse enrichments[/dim]\n"
+            "  databar enrich get <id>                      [dim]# inspect params[/dim]\n"
+            "  databar enrich run <id> --params '{...}'     [dim]# run one row[/dim]\n"
+            "  databar enrich bulk <id> --input data.csv    [dim]# bulk from CSV[/dim]\n\n"
+            "  databar waterfall list\n"
+            "  databar waterfall run <identifier> --params '{...}'\n\n"
+            "  databar table create --name 'Leads' --columns 'email,name'\n"
+            "  databar table rows <uuid> --format json\n\n"
+            "  [dim]Tip: always use --format json when piping output.[/dim]",
+            border_style="cyan",
+            title="[cyan]CLI[/cyan]",
+        ))
+
+    if pref in ("python", "both"):
+        console.print(Panel(
+            "[bold]Python SDK Quick Start[/bold]\n\n"
+            "  from databar import DatabarClient\n\n"
+            "  client = DatabarClient()  [dim]# reads DATABAR_API_KEY from env or ~/.databar/config[/dim]\n\n"
+            "  enrichments = client.list_enrichments(q='email')\n"
+            "  result = client.run_enrichment_sync(123, {'email': 'alice@example.com'})\n\n"
+            "  tables = client.list_tables()\n"
+            "  rows = client.get_rows(table.identifier)   [dim]# returns RowsResponse[/dim]\n"
+            "  rows.data                                  [dim]# list of row dicts[/dim]",
+            border_style="cyan",
+            title="[cyan]Python[/cyan]",
+        ))
+
+    console.print(
+        "\n  [dim]Full reference: [bold]databar agent-guide[/bold] | "
+        "Docs: [link=https://build.databar.ai]build.databar.ai[/link][/dim]\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Command entry point
+# ---------------------------------------------------------------------------
+
+def onboard() -> None:
+    """Interactive setup wizard — configure auth, PATH, and get started."""
+    _print_banner()
+    console.print(
+        "  Welcome to [bold cyan]Databar[/bold cyan]! This wizard takes ~1 minute "
+        "and sets up everything you need.\n"
+        "  [dim]Press Ctrl+C at any time to exit.[/dim]\n"
+    )
+
+    try:
+        _step_api_key()
+        _step_path()
+        pref = _step_preference()
+        _step_next_steps(pref)
+    except (KeyboardInterrupt, typer.Abort):
+        console.print("\n\n[dim]Onboarding cancelled. Run `databar onboard` any time to restart.[/dim]")
+        raise typer.Exit(0)

{databar-2.0.4 → databar-2.0.6}/src/databar/cli/app.py

@@ -30,6 +30,22 @@ app.add_typer(tables.app, name="table")
 app.add_typer(tasks.app, name="task")
 
 
+@app.command("onboard")
+def onboard() -> None:
+    """Interactive setup wizard — configure auth, PATH, and get started."""
+    from ._onboard import onboard as _run_onboard
+
+    _run_onboard()
+
+
+@app.command("agent-guide")
+def agent_guide() -> None:
+    """Print the full agent usage guide (SDK + CLI reference for AI agents)."""
+    from ._guide import AGENT_GUIDE
+
+    typer.echo(AGENT_GUIDE)
+
+
 def _version_callback(value: bool) -> None:
     if value:
         typer.echo(f"databar {__version__}")

{databar-2.0.4 → databar-2.0.6}/src/databar/client.py

@@ -43,6 +43,7 @@ from .models import (
     EnrichmentSummary,
     InsertOptions,
     InsertRow,
+    RowsResponse,
     RunResponse,
     Table,
     TableEnrichment,
@@ -522,20 +523,22 @@ class DatabarClient:
         table_uuid: str,
         page: int = 1,
         per_page: int = 100,
-    ) -> Dict[str, Any]:
+    ) -> RowsResponse:
         """
         Get rows from a table with pagination.
 
-        Returns a dict with keys: ``data`` (list of row dicts), ``has_next_page``,
-        ``total_count``, ``page``.  Each row dict is keyed by column name.
+        Returns a :class:`RowsResponse` with ``.data`` (list of row dicts),
+        ``.has_next_page``, ``.total_count``, ``.page``.
+        Each row dict is keyed by column name and includes an ``id`` key.
 
         ``per_page`` max is 500 (API limit). Default is 100.
         """
-        return self._request(
+        data = self._request(
             "GET",
             f"/table/{table_uuid}/rows",
             params={"page": page, "per_page": per_page},
         )
+        return RowsResponse.model_validate(data)
 
     def create_rows(
         self,

{databar-2.0.4 → databar-2.0.6}/src/databar/models.py

@@ -297,6 +297,38 @@ class TableEnrichment(BaseModel):
     name: str
 
 
+# ===========================================================================
+# Rows — Query
+# ===========================================================================
+
+
+class RowsResponse(BaseModel):
+    """Paginated rows returned by get_rows().
+
+    Fields: data, has_next_page, total_count, page.
+
+    Property alias: .rows → .data.
+
+    Usage::
+
+        resp = client.get_rows(table.identifier)
+        for row in resp.data:
+            print(row["email"])
+        if resp.has_next_page:
+            resp2 = client.get_rows(table.identifier, page=2)
+    """
+
+    data: List[Dict[str, Any]] = Field(description="List of row dicts keyed by column name. Each row also has an 'id' key with the row UUID.")
+    has_next_page: bool = Field(default=False)
+    total_count: int = Field(default=0)
+    page: int = Field(default=1)
+
+    @property
+    def rows(self) -> List[Dict[str, Any]]:
+        """Alias for data."""
+        return self.data
+
+
 # ===========================================================================
 # Rows — Insert
 # ===========================================================================

{databar-2.0.4 → databar-2.0.6/src/databar.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databar
-Version: 2.0.4
+Version: 2.0.6
 Summary: Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai
 Author-email: "Databar.ai Team" <info@databar.ai>
 License: MIT License

{databar-2.0.4 → databar-2.0.6}/src/databar.egg-info/SOURCES.txt

@@ -13,6 +13,8 @@ src/databar.egg-info/requires.txt
 src/databar.egg-info/top_level.txt
 src/databar/cli/__init__.py
 src/databar/cli/_auth.py
+src/databar/cli/_guide.py
+src/databar/cli/_onboard.py
 src/databar/cli/_output.py
 src/databar/cli/app.py
 src/databar/cli/enrichments.py

{databar-2.0.4 → databar-2.0.6}/tests/test_cli.py

@@ -329,4 +329,4 @@ def test_task_get_poll(monkeypatch):
 def test_version_flag():
     result = runner.invoke(app, ["--version"])
     assert result.exit_code == 0
-    assert "2.0.4" in result.output
+    assert "2.0.6" in result.output