bibliotheca-client 0.1.0

Python client library for Bibliotheca data exploration platform

Bibliotheca Client SDK

Python client library for interacting with the Bibliotheca data exploration platform.

Installation

pip install bibliotheca-client

Or install from source:

cd client-sdk
pip install -e .

Quick Start

from bibliotheca_client import BibliothecaClient

# Initialize the client with your API key
client = BibliothecaClient(
    base_url="https://anthology.pantology.io/apis",
    api_key="bib_xxxxxxxxxx..."  # Get from https://anthology.pantology.io/api-keys
)

# Check your usage and tier
usage = client.get_usage()
print(f"Tier: {usage['tier_name']}")
print(f"Tokens Used: {usage['tokens_used_today']} / {usage['daily_limit']}")

# Generate hypotheses for data exploration
hypotheses = client.generate_hypotheses(
    user_grouping="my-database",
    user_context="I want to understand sales trends"
)

for hypothesis in hypotheses:
    print(f"{hypothesis['title']}: {hypothesis['question']}")

# Generate SQL from natural language
result = client.generate_sql(
    session_id="my-session-123",
    user_question="What are the top 10 products by revenue?",
    user_grouping="my-database",
    run_debugger=True,
    debugging_rounds=2
)

print(result['GeneratedSQL'])

Authentication

The Bibliotheca API uses API key authentication. Here's how to get your API key:

Getting Your API Key

1. Log in to Bibliotheca at https://anthology.pantology.io
2. Click "API Keys" in the left sidebar (🔑 icon)
3. Click "Create New API Key"
4. Copy your API key (shown only once!)
5. Use it in your code or set as environment variable

Using API Keys

from bibliotheca_client import BibliothecaClient

# Option 1: Direct initialization
client = BibliothecaClient(
    base_url="https://anthology.pantology.io/apis",
    api_key="bib_xxxxxxxxxx..."
)

# Option 2: From environment variable (recommended)
import os
client = BibliothecaClient(
    base_url=os.getenv('BIBLIOTHECA_BACKEND_URL', 'https://anthology.pantology.io/apis'),
    api_key=os.getenv('BIBLIOTHECA_API_KEY')
)

API Key Security Best Practices

• Never commit API keys to version control
• Use environment variables: export BIBLIOTHECA_API_KEY='bib_xxx'
• Revoke keys immediately if compromised
• Manage keys in the UI at https://anthology.pantology.io/api-keys

Rate Limits

API keys have different tiers:

• Free: 10,000 tokens/day (~12-13 queries)
• Plus: 100,000 tokens/day (~125 queries)
• Premium: Custom limits

Check your usage:

usage = client.get_usage()
print(f"Tokens remaining: {usage['tokens_remaining']}")

API Reference

BibliothecaClient

__init__(base_url: str, api_key: str = None, id_token: str = None)

Initialize the client with backend URL and API key.

Parameters:

• base_url: Backend API endpoint URL
• api_key: API key from https://anthology.pantology.io/api-keys (recommended)
• id_token: Firebase ID token (legacy, for backward compatibility)

generate_hypotheses(user_grouping: str, hypothesis_model: str = 'gemini-2.5-pro', user_context: str = "") -> List[Dict]

Generate data exploration hypotheses based on database schema.

Parameters:

• user_grouping: Database grouping identifier
• hypothesis_model: LLM model for hypothesis generation
• user_context: Optional context about exploration goals

Returns: List of hypothesis dictionaries with title, description, and question fields.

generate_sql(session_id: str, user_question: str, user_grouping: str, **kwargs) -> Dict

Generate SQL query from natural language question.

Parameters:

• session_id: Session identifier for conversation tracking
• user_question: Natural language question
• user_grouping: Database grouping identifier
• Additional optional parameters for model configuration

Returns: Dictionary with ResponseCode, GeneratedSQL, SessionId, and Error fields.

get_available_databases() -> List[Dict]

Get list of available databases/groupings.

Returns: List of database schema information.

get_usage() -> Dict

Get current API key usage and tier information.

Returns: Dictionary with tier_name, tokens_used_today, daily_limit, tokens_remaining, and resets_at fields.

list_api_keys() -> Dict

List all API keys associated with your account.

Returns: Dictionary with keys list and tier information.

revoke_api_key(key_id: str) -> Dict

Revoke an API key (useful if compromised).

Parameters:

• key_id: The key ID to revoke

Returns: Success/error response.

translate_sql(sql: str, target_dialect: str) -> str

Translate SQL between different database dialects (e.g., PostgreSQL to BigQuery).

Parameters:

• sql: Source SQL query
• target_dialect: Target SQL dialect (e.g., 'bigquery', 'postgres', 'spark')

Returns: Translated SQL query string.

update_token(id_token: str)

Update the authentication token (legacy method for Firebase tokens).

Development

Setup Development Environment

cd client-sdk
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black bibliotheca_client/

License

Apache License 2.0

Support

For issues and questions, please email us at [e-mail]