Metadata-Version: 2.4
Name: coltanedb
Version: 0.1.0
Summary: Official Python client and query SDK for ColtaneDB
Author-email: ColtaneDB Team <info.cometlabs@gmail.com>
Maintainer-email: ColtaneDB Team <info.cometlabs@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://coltanedb.dev
Project-URL: Documentation, https://github.com/itsjustayush/ColtaneDB#readme
Project-URL: Repository, https://github.com/itsjustayush/ColtaneDB.git
Project-URL: Issues, https://github.com/itsjustayush/ColtaneDB/issues
Keywords: colt,coltanedb,database,query-language,postgres,vector,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ColtaneDB Python SDK (`coltanedb`)

Official Python client and query SDK for **ColtaneDB** — the multi-model database engine and the **Colt** (`.colt`) declarative query language.

---

## Installation

Install the package via pip:

```bash
pip install coltanedb
```

---

## Quickstart

### 1. Initialize the Client

```python
from coltanedb import ColtaneClient

# Connect to ColtaneDB server or local dev instance
client = ColtaneClient(
    base_url="http://localhost:3000",
    api_key="clt_live_your_api_key",
    tenant_id="tnt_your_project_id",
)
```

### 2. Execute a Colt Query

```python
result = client.execute("""
    FIND books SELECT title, author, views
    WHERE views > 10
    ORDER BY views DESC
    LIMIT 20
""")

print("Query success:", result.success)
print("Returned rows:", result.rows)
```

### 3. Parameterized Execution

Pass named parameters safely:

```python
result = client.execute(
    source="FIND users SELECT id, email WHERE email == $target_email",
    parameters={"target_email": "alice@example.com"}
)
```

### 4. Compile & Plan Queries

Inspect the multi-engine execution plan produced by the Colt compiler:

```python
plan = client.plan("""
    DEFINE COLLECTION articles STRICT @backend(neon) {
        id: uuid @key,
        title: text,
        published: time @default(now)
    }
""")

for step in plan.steps:
    print(f"Backend: {step.backend}")
    print(f"Operation: {step.operation}")
    print(f"Statement: {step.parameterized_statement}")
```

### 5. Parse Colt Source (AST)

```python
ast_result = client.parse("FIND products SELECT id, price")
print("AST Program:", ast_result.ast)
```

---

## License

Apache-2.0 © ColtaneDB Team
