Metadata-Version: 2.4
Name: coltanedb
Version: 0.2.0
Summary: Official Python client and query SDK for ColtaneDB powered by the Meld Model
Author-email: Ayush Bhattacharya <info.cometlabs@gmail.com>
Maintainer-email: Ayush Bhattacharya <info.cometlabs@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://coltanedb.vercel.app
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,coltlang,coltanedb,meld,database,query-language,postgres,redis,mongodb,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** and the **Colt** (`.colt`, ColtLang) declarative query language, powered by the **Meld Model** (Multi-Engine Link Declaration).

*Conceived and created by **Ayush Bhattacharya**.*

---

## Installation

Install the package from PyPI:

```bash
pip install coltanedb
```

---

## Features

- **The Meld Model**: Query, link, and stitch records seamlessly across PostgreSQL, Redis, MongoDB, and SQLite.
- **Declarative Query Execution**: Execute `.colt` statements with injection-proof parameter binding.
- **Multi-Engine Planning**: Inspect native parameterized query plans before executing (`client.plan`).
- **Interactive Language Guide**: Export the complete Colt Language Reference via `coltanedb.guide(file=True)`.
- **Author & Project Metadata**: Inspect author credentials and repository links via `coltanedb.author()`.

---

## Quickstart

### 1. Initialize the Client

```python
import coltanedb
from coltanedb import ColtaneClient

# Initialize from an app.colt file (resolves connections via environment)
db = ColtaneClient.from_file("app.colt")

# Or connect to a running ColtaneDB bridge (colt serve) or server
client = ColtaneClient(
    base_url="http://localhost:3000",
    api_key="clt_live_demo",
)
```

### 2. Execute a Colt Query

```python
# Run with bound parameters
result = client.run("FIND books WHERE views > $min LIMIT 10", min=10)

print("Query success:", result.success)
for row in result.rows:
    print(f"Book: {row['title']}")

# Inspect execution metadata and cross-engine status
print(result.meta)
```

### 3. Generate the Complete Colt Language Guide

```python
# Creates a COLT_GUIDE.md file in the current working directory
coltanedb.guide(file=True)

# Or print readable plain text directly to the console
coltanedb.guide(file=False)
```

### 4. Author & Attribution

```python
# Prints author info with clickable terminal hyperlinks
coltanedb.author()
```

### 5. Inspect Execution Plans

```python
plan = client.plan("""
    FIND reviews FETCH book 
    WHERE book.views > 10 
    LIMIT 20
""")

for step in plan.steps:
    print(f"Backend: {step.backend}, Op: {step.operation}")
```

---

## License

Apache-2.0 © Ayush Bhattacharya & ColtaneDB Team
