Submits a prompt to the Secoda embedded AI endpoint and polls until the
response is complete. Sends MCP progress notifications at each poll interval
so clients can show elapsed time. Returns the AI's response text along with
the chat ID, which can be passed as `parent` in a follow-up call to continue
the conversation.

Args:
    prompt: The message or question to send to the Secoda AI.
    ctx: MCP context (injected by FastMCP; not part of the tool schema).
    parent: Chat ID of a previous conversation to continue (optional).
        Pass the chat_id from a previous ai_chat response to maintain context.
    persona_id: Persona ID to use for the AI chat (optional).
        Defaults to AI_PERSONA_ID env var if set, otherwise the workspace default persona.
    poll_interval_seconds: Seconds between polling attempts (default: 10).
    timeout_seconds: Maximum seconds to wait for completion (default: 360).

Returns:
    JSON with keys:
        - success: true
        - chat_id: The ID of this chat (use as `parent` in follow-up calls)
        - status: "completed"
        - response_content: The AI's response text

Example:
    # Start a new conversation
    ai_chat(prompt="How do we handle price reductions in GMV calculations?")

    # Continue a previous conversation
    ai_chat(
        prompt="Can you elaborate on the discount logic?",
        parent="0d53d57b-d1ef-4fc2-bc50-fd3fba2fea93"
    )

Error handling:
    - 403: Permission denied - check API token has AI chat permissions
    - 429: Rate limit exceeded - tool retries automatically
    - Timeout: Increase timeout_seconds if the AI takes longer than expected

Args:
    entity_id: The ID of the entity to get lineage for
    truncate_length: Maximum characters for text fields in results (default: 150)

Returns:
    Entity lineage with text fields truncated to specified length

Use this to get full details about a collection after finding it via list_collections.

Args:
    collection_id: The unique identifier of the collection
    truncate_length: Maximum characters for text fields in results (default: 150).
        Set to None for full descriptions.

Returns:
    Collection details with text fields truncated to specified length

Example:
    get_collection(collection_id="collection-123")

Use this to read the full content of a question and any accepted answers after
finding it via list_questions or search_documentation.

Args:
    question_id: The unique identifier of the question
    truncate_length: Maximum characters for text fields in results (default: 150).
        Set to None to read the full question and answer text.

Returns:
    Question details including title, description, and answers

Use this to get full details of a catalog resource (table, column, view, etc.)
after finding it through list_resources or search_data_assets.

Args:
    resource_id: The unique identifier of the resource to retrieve
    truncate_length: Maximum characters for text fields in results (default: 150).
        Set to None when you need full descriptions/definitions.

Returns:
    Resource details with text fields truncated to specified length

Args:
    truncate_length: Maximum characters for text fields in results (default: 150)

Returns:
    Glossary with text fields truncated to specified length

Collections are organized groups of related resources (tables, dashboards, documents).
Use this to browse what topic areas and resource groups exist.

Args:
    title: Filter collections by title (optional)
    page: Page number for pagination (default: 1)
    truncate_length: Maximum characters for text fields in results (default: 150)

Returns:
    List of collections with text fields truncated to specified length

Example:
    list_collections(title="Customer")
    list_collections(page=2)

Questions in Secoda represent data consumer inquiries that have been asked and
answered by the data team. Use this to find existing answers before asking
a new question.

Args:
    page: Page number for pagination (default: 1)
    truncate_length: Maximum characters for text fields in results (default: 150)

Returns:
    List of questions with text fields truncated to specified length

This endpoint provides precise control over resource queries using structured filters.
Use this when you need exact matching, specific field filtering, or complex queries.

Args:
    filter: FilterOperand (field or logical) for filtering resources
    sort: SortConfig for ordering results
    page: Page number for pagination (default: 1)
    truncate_length: Maximum characters for text fields in results (default: 150)

Returns:
    Paginated list of resources matching the filter criteria

Filter Examples:

    # Single condition - title contains
    filter = {"operator": "contains", "field": "title", "value": "order_lines"}

    # Single condition - entity type
    filter = {"operator": "exact", "field": "native_type", "value": "table"}

    # Find all columns of a specific table
    filter = {"operator": "exact", "field": "parent_id", "value": "table-id-123"}

    # Multiple conditions with AND
    filter = {
        "operator": "and",
        "operands": [
            {"operator": "exact", "field": "native_type", "value": "table"},
            {"operator": "contains", "field": "title", "value": "customer"}
        ]
    }

Sort Examples:

    # Sort by title ascending
    sort = {"field": "title", "order": "asc"}

    # Sort by external_usage descending (most popular first)
    sort = {"field": "external_usage", "order": "desc"}

Args:
    entity_id: The ID of the entity to retrieve
    truncate_length: Maximum characters for text fields in results (default: 150).
        Often useful to set to None when you need full descriptions/definitions.

Returns:
    Entity details with text fields truncated to specified length

Args:
    query: Search query for finding tables, columns, charts, dashboards
    page: Page number for pagination (default: 1)
    truncate_length: Maximum characters for text fields in results (default: 150)

Returns:
    Search results with text fields truncated to specified length

Args:
    query: Search query for finding documents, questions, glossary terms
    page: Page number for pagination (default: 1)
    truncate_length: Maximum characters for text fields in results (default: 150)

Returns:
    Search results with text fields truncated to specified length