abra-q 0.1.0

Python SDK for the Abra-Q API — manage datasources, run queries, and handle IAM from Python and Jupyter notebooks

abra-q

Python SDK for the Abra-Q API — manage datasources, run natural-language queries, and handle IAM, all from Python or a Jupyter notebook.

Installation

pip install abra-q

Or with uv:

uv add abra-q

Quick Start

from abra_q import AbraQ

client = AbraQ("<host provided by AbraDynamics team>")
client.login("[e-mail]", "password")

# List datasources
datasources = client.datasources.list()

# Ask a question in natural language
result = client.datasources.prompt("my-datasource-id", "Show me top 10 customers by revenue")
print(result["query"])        # Generated SQL
print(result["explanation"])  # AI explanation

# Run raw SQL
rows = client.datasources.query("my-datasource-id", "SELECT * FROM customers LIMIT 5")

Using in Jupyter Notebooks

from abra_q import AbraQ

client = AbraQ("<host provided by AbraDynamics team>")
client.login("[e-mail]", "password")

# Natural-language query
result = client.datasources.prompt("sales-db", "Monthly revenue for the last year")
print(result["query"])

# Execute the generated query
data = client.datasources.query("sales-db", result["query"])

# Convert to pandas DataFrame (optional)
import pandas as pd
df = pd.DataFrame(data["rows"], columns=[c["name"] for c in data["columns"]])
df.head()

API Reference

Client

client = AbraQ(base_url, timeout=30)
client.login(email, password)
client.logout()

Datasources — client.datasources

Method	Description
list()	List all accessible datasources
get(id)	Get datasource details
create(...)	Create a new datasource
delete(id)	Delete a datasource
test_connection(...)	Test connection before creating
prompt(id, text)	Generate SQL from natural language
query(id, sql)	Execute raw SQL
enhance(id)	AI-enhance table/column descriptions
reacquaint(id)	Resync schema
sample_queries(id)	Get sample queries
generate_sample_queries(id)	Generate sample queries with AI

Datasets — client.datasets

Method	Description
parse(file_path)	Parse a CSV/Excel file
import_dataset(sheets=...)	Import parsed data as a datasource

Query Builder — client.query_builder

Method	Description
intelligent_prompt(prompt, datasource_ids)	Multi-datasource natural language query
list_sessions()	List query builder sessions
create_session()	Create a new session
get_session(id)	Get session details

Saved Queries — client.queries

Method	Description
get(query_id)	Get a saved query
execute(query_id)	Execute a saved query

Both accept an optional api_key parameter for agent-based authentication.

IAM — client.iam

Manage policies, roles, groups, agents, and user policies:

# Policies
client.iam.list_policies()
client.iam.create_policy(id="pol-1", name="ReadOnly", statement=[...])

# Roles
client.iam.list_roles()
client.iam.create_role(id="role-1", name="Analyst")
client.iam.attach_role_policy("role-1", "pol-1")

# Groups
client.iam.list_groups()
client.iam.add_user_to_group("group-1", "user-1")

# Agents (API keys)
client.iam.create_agent(id="bot-1", description="ETL bot")
client.iam.assign_agent_role("bot-1", "role-1")

Users — client.users

Method	Description
me()	Get current user profile
list()	List all users
create(email)	Create a user
delete(id)	Delete a user
change_password(current, new)	Change password

Preferences — client.preferences

Method	Description
get()	Get all preferences
set_llm_model(model)	Set LLM model
set_embedding_model(model)	Set embedding model
set_vector_threshold(label, threshold)	Set similarity threshold

Error Handling

from abra_q import AbraQ, AuthenticationError, PermissionDeniedError, NotFoundError

client = AbraQ("host provided by AbraDynamics team")

try:
    client.login("[e-mail]", "wrong-password")
except AuthenticationError as e:
    print(f"Login failed: {e}")

try:
    client.datasources.get("nonexistent-id")
except NotFoundError:
    print("Datasource not found")
except PermissionDeniedError:
    print("You don't have access")

License

Apache 2.0