Metadata-Version: 2.4
Name: abra-q
Version: 0.1.0
Summary: Python SDK for the Abra-Q API — manage datasources, run queries, and handle IAM from Python and Jupyter notebooks
Project-URL: Homepage, https://github.com/Abrajects/abra-q
Project-URL: Documentation, https://github.com/Abrajects/abra-q#readme
Author-email: tugrultamerc <tugrultamerc@gmail.com>
License-Expression: Apache-2.0
Keywords: abraq,datasource,jupyter,notebook,query,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Description-Content-Type: text/markdown

# 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

```bash
pip install abra-q
```

Or with **uv**:

```bash
uv add abra-q
```

## Quick Start

```python
from abra_q import AbraQ

client = AbraQ("<host provided by AbraDynamics team>")
client.login("user@example.com", "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

```python
from abra_q import AbraQ

client = AbraQ("<host provided by AbraDynamics team>")
client.login("analyst@company.com", "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

```python
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:

```python
# 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

```python
from abra_q import AbraQ, AuthenticationError, PermissionDeniedError, NotFoundError

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

try:
    client.login("user@example.com", "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
