databar 2.0.3__tar.gz → 2.0.5__tar.gz

{databar-2.0.3/src/databar.egg-info → databar-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databar
-Version: 2.0.3
+Version: 2.0.5
 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.3 → databar-2.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databar"
-version = "2.0.3"
+version = "2.0.5"
 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.3 → databar-2.0.5}/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.3"
+__version__ = "2.0.5"
 __all__ = [
     "DatabarClient",
     # exceptions
@@ -87,6 +88,7 @@ __all__ = [
     "Table",
     "Column",
     "TableEnrichment",
+    "RowsResponse",
     "InsertRow",
     "InsertOptions",
     "DedupeOptions",

databar-2.0.5/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.3 → databar-2.0.5}/src/databar/cli/app.py

@@ -30,6 +30,14 @@ app.add_typer(tables.app, name="table")
 app.add_typer(tasks.app, name="task")
 
 
+@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.3 → databar-2.0.5}/src/databar/client.py

@@ -43,6 +43,7 @@ from .models import (
     EnrichmentSummary,
     InsertOptions,
     InsertRow,
+    RowsResponse,
     RunResponse,
     Table,
     TableEnrichment,
@@ -521,14 +522,23 @@ class DatabarClient:
         self,
         table_uuid: str,
         page: int = 1,
-        per_page: int = 1000,
-    ) -> Dict[str, Any]:
-        """Get rows from a table with pagination. Returns raw dict with has_next_page etc."""
-        return self._request(
+        per_page: int = 100,
+    ) -> RowsResponse:
+        """
+        Get rows from a table with pagination.
+
+        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.
+        """
+        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.3 → databar-2.0.5}/src/databar/models.py

@@ -20,6 +20,11 @@ from pydantic import BaseModel, Field
 
 
 class User(BaseModel):
+    """Authenticated user profile.
+
+    Fields: first_name, email, balance, plan.
+    """
+
     first_name: Optional[str] = None
     email: str
     balance: float
@@ -51,22 +56,64 @@ class Choices(BaseModel):
 
 
 class EnrichmentParam(BaseModel):
-    name: str
-    is_required: bool
+    """A parameter required or accepted by an enrichment.
+
+    Fields: name, is_required, type_field, description, choices.
+
+    Property aliases: .slug → .name, .label → .description, .required → .is_required.
+    """
+
+    name: str = Field(description="Parameter slug used as the key in the params dict.")
+    is_required: bool = Field(description="Whether this parameter is required.")
     type_field: str = Field(
         description="Input type. Common values: text, select, mselect, datetime."
     )
-    description: str
+    description: str = Field(description="Human-readable label / description.")
     choices: Optional[Choices] = None
 
+    @property
+    def slug(self) -> str:
+        """Alias for name."""
+        return self.name
+
+    @property
+    def label(self) -> str:
+        """Alias for description."""
+        return self.description
+
+    @property
+    def required(self) -> bool:
+        """Alias for is_required."""
+        return self.is_required
+
 
 class EnrichmentResponseField(BaseModel):
-    name: str
-    type_field: str
+    """A field returned in the enrichment result data.
+
+    Fields: name, type_field.
+
+    Property aliases: .slug → .name, .label → .name.
+    """
+
+    name: str = Field(description="Field name as it appears in the result data.")
+    type_field: str = Field(description="Data type of this field.")
+
+    @property
+    def slug(self) -> str:
+        """Alias for name."""
+        return self.name
+
+    @property
+    def label(self) -> str:
+        """Alias for name."""
+        return self.name
 
 
 class EnrichmentSummary(BaseModel):
-    """Enrichment as returned by the list endpoint (no params/response_fields)."""
+    """Enrichment as returned by the list endpoint (no params/response_fields).
+
+    Fields: id, name, description, data_source, price, auth_method.
+    """
 
     id: int
     name: str
@@ -77,7 +124,16 @@ class EnrichmentSummary(BaseModel):
 
 
 class Enrichment(EnrichmentSummary):
-    """Full enrichment detail including params and response fields."""
+    """Full enrichment detail including params and response fields.
+
+    Fields: id, name, description, data_source, price, auth_method, params, response_fields.
+
+    Usage::
+
+        enrichment = client.get_enrichment(123)
+        for p in enrichment.params:
+            print(p.name, p.is_required, p.description)
+    """
 
     params: Optional[List[EnrichmentParam]] = None
     response_fields: Optional[List[EnrichmentResponseField]] = None
@@ -153,7 +209,20 @@ class WaterfallEnrichment(BaseModel):
 
 
 class Waterfall(BaseModel):
-    identifier: str
+    """A waterfall enrichment that tries multiple providers in sequence.
+
+    Fields: identifier, name, description, input_params, output_fields,
+    available_enrichments, is_email_verifying, email_verifiers.
+
+    Property aliases: .slug → .identifier.
+
+    Usage::
+
+        wf = client.get_waterfall("email_getter")
+        result = client.run_waterfall_sync(wf.identifier, {...})
+    """
+
+    identifier: str = Field(description="Slug-style identifier, e.g. 'email_getter'. Use this when calling run_waterfall().")
     name: str
     description: str
     input_params: List[Dict[str, Any]]
@@ -162,6 +231,11 @@ class Waterfall(BaseModel):
     is_email_verifying: bool
     email_verifiers: List[Any]
 
+    @property
+    def slug(self) -> str:
+        """Alias for identifier."""
+        return self.identifier
+
 
 # ===========================================================================
 # Tables
@@ -169,25 +243,92 @@ class Waterfall(BaseModel):
 
 
 class Table(BaseModel):
-    identifier: str
+    """A Databar table.
+
+    Fields: identifier, name, created_at, updated_at.
+
+    Property aliases: .id → .identifier, .uuid → .identifier.
+
+    Usage::
+
+        table = client.create_table(name="Leads", columns=["email", "name"])
+        rows = client.get_rows(table.identifier)
+    """
+
+    identifier: str = Field(description="Table UUID. Use this in all table operations.")
     name: str
     created_at: str
     updated_at: str
 
+    @property
+    def id(self) -> str:
+        """Alias for identifier."""
+        return self.identifier
+
+    @property
+    def uuid(self) -> str:
+        """Alias for identifier."""
+        return self.identifier
+
 
 class Column(BaseModel):
-    identifier: str
+    """A column defined on a table.
+
+    Fields: identifier, internal_name, name, type_of_value, data_processor_id.
+    """
+
+    identifier: str = Field(description="Column UUID.")
     internal_name: str
-    name: str
+    name: str = Field(description="Human-readable column name.")
     type_of_value: str
     data_processor_id: Optional[int] = None
 
 
 class TableEnrichment(BaseModel):
+    """An enrichment configured on a table.
+
+    Fields: id, name.
+
+    The id here is the TABLE-ENRICHMENT id — use it with run_table_enrichment(),
+    not the enrichment catalog id.
+    """
+
     id: int
     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.3 → databar-2.0.5/src/databar.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databar
-Version: 2.0.3
+Version: 2.0.5
 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.3 → databar-2.0.5}/src/databar.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ 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/_output.py
 src/databar/cli/app.py
 src/databar/cli/enrichments.py

{databar-2.0.3 → databar-2.0.5}/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.2" in result.output
+    assert "2.0.5" in result.output