llms-full.txt

# eDB — full documentation (llms-full.txt)

This file is a checked-in concatenation of eDB's documentation,
in the order listed below, so agents and tools can read the whole
corpus as one document. It is generated by hand from the sources —
when a source doc changes, update this file in the same commit.

Sources, in order:

- `docs/getting-started.md`
- `docs/architecture.md`
- `docs/api-reference.md`

# === docs/getting-started.md ===

# Getting Started with eDB

## Installation

```bash
# Clone the repository
git clone https://github.com/your-org/edb.git
cd edb

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"
```

## Quick Start: Python Library

```python
from edb.core.database import Database
from edb.core.models import ColumnDefinition, ColumnType, TableSchema

# Create a database (in-memory or file-backed)
db = Database("my_app.db")

# --- SQL (Relational) ---
schema = TableSchema(
    name="users",
    columns=[
        ColumnDefinition(name="id", col_type=ColumnType.INTEGER, primary_key=True),
        ColumnDefinition(name="name", col_type=ColumnType.TEXT, nullable=False),
        ColumnDefinition(name="email", col_type=ColumnType.TEXT, unique=True),
    ],
)
db.sql.create_table(schema)
db.sql.insert("users", {"id": 1, "name": "Alice", "email": "alice@example.com"})

result = db.sql.select("users", where={"name": "Alice"})
print(result.rows)  # [{"id": 1, "name": "Alice", "email": "alice@example.com"}]

# --- Document Store (NoSQL) ---
doc = db.docs.insert("logs", {"event": "user_created", "user_id": 1, "level": "info"})
print(doc.id)  # UUID

logs = db.docs.find("logs", filter_dict={"level": "info"})
print(len(logs))  # 1

# --- Key-Value Store ---
db.kv.set("session:abc123", {"user_id": 1, "role": "admin"}, ttl=3600)
session = db.kv.get("session:abc123")
print(session)  # {"user_id": 1, "role": "admin"}

# --- Transactions ---
with db.transaction():
    db.sql.insert("users", {"id": 2, "name": "Bob", "email": "bob@example.com"})
    db.docs.insert("logs", {"event": "user_created", "user_id": 2})
    # If any operation fails, everything rolls back

db.close()
```

## Quick Start: CLI

```bash
# Initialize a new database with default admin user
edb init --db my_app.db

# Open interactive SQL shell
edb shell --db my_app.db
# edb> CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL)
# edb> INSERT INTO products VALUES (1, 'Widget', 9.99)
# edb> SELECT * FROM products
# edb> .tables
# edb> .collections
# edb> exit

# Start the API server
edb serve --host 0.0.0.0 --port 8000 --db my_app.db
```

## Quick Start: REST API

```bash
# Start the server
edb serve

# Register a user
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "secure123", "role": "read_write"}'

# Login and get tokens
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin1234"}'

# Use the access_token from login response
TOKEN="<your-access-token>"

# Create a table
curl -X POST http://localhost:8000/sql/tables \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "products", "columns": [{"name": "id", "col_type": "INTEGER", "primary_key": true}, {"name": "name", "col_type": "TEXT"}]}'

# Insert data
curl -X POST http://localhost:8000/sql/tables/products/insert \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"id": 1, "name": "Widget"}}'

# Natural language query via ebot
curl -X POST http://localhost:8000/ebot/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "show all products"}'
```

## Configuration

eDB is configured via environment variables (prefixed with `EDB_`):

| Variable | Default | Description |
|----------|---------|-------------|
| `EDB_DB_PATH` | `edb_data.db` | Database file path |
| `EDB_API_HOST` | `127.0.0.1` | API server host |
| `EDB_API_PORT` | `8000` | API server port |
| `EDB_JWT_SECRET` | (default) | JWT signing secret — **change in production!** |
| `EDB_ENCRYPTION_KEY` | (default) | AES-256 encryption key — **change in production!** |
| `EDB_EBOT_ENABLED` | `true` | Enable ebot AI queries |
| `EDB_AUDIT_ENABLED` | `true` | Enable audit logging |

You can also use a `.env` file in the project root.

## Running Tests

```bash
pytest                          # Run all tests
pytest tests/unit/              # Unit tests only
pytest tests/integration/       # Integration tests only
pytest --cov=edb --cov-report=html  # With coverage report
```

# === docs/architecture.md ===

# eDB Architecture

## System Overview

```mermaid
graph TB
    Client[Client Application] --> API[REST API - FastAPI]
    Client --> CLI[CLI - edb shell]
    Client --> Embed[Python Embedding - import edb]

    API --> Auth[Auth Layer - JWT + RBAC]
    API --> Ebot[ebot AI - NL Translator]

    Auth --> QP[Query Parser]
    Ebot --> QP

    QP --> Planner[Query Planner]

    Planner --> SQL[Relational Store]
    Planner --> Doc[Document Store]
    Planner --> KV[Key-Value Store]

    SQL --> Engine[Storage Engine - SQLite]
    Doc --> Engine
    KV --> Engine

    Engine --> DB[(SQLite Database File)]

    Audit[Audit Logger] --> Engine
    Encrypt[Encryption Manager] --> Engine

    style API fill:#4CAF50,color:white
    style Engine fill:#2196F3,color:white
    style Auth fill:#FF9800,color:white
    style Ebot fill:#9C27B0,color:white
```

## Components

### Storage Engine (`edb.core.engine`)
The lowest-level component. Manages the SQLite connection with WAL mode, thread safety, and parameterized query execution.

### Relational Store (`edb.core.relational`)
SQL CRUD operations (CREATE TABLE, INSERT, SELECT, UPDATE, DELETE) with parameterized queries to prevent injection.

### Document Store (`edb.core.document`)
MongoDB-like JSON document storage. Collections are SQLite tables with `id`, `data` (JSON), `created_at`, `updated_at`. Supports JSON path queries via SQLite's JSON1 extension.

### Key-Value Store (`edb.core.keyvalue`)
Simple key-value operations with optional TTL expiration. Values are JSON-serialized. Expired entries are automatically purged.

### Unified Database (`edb.core.database`)
Single entry point combining all three stores. Provides transaction support via context manager (`with db.transaction()`).

### Query Parser (`edb.query.parser`)
Parses JSON-based query DSL into typed query objects. Validates actions, required fields, and type aliases.

### Query Planner (`edb.query.planner`)
Routes parsed queries to the correct store and executes them. Returns unified results regardless of underlying store type.

### Authentication (`edb.auth`)
- **JWT Handler**: Creates and verifies access/refresh tokens
- **User Manager**: User CRUD with bcrypt password hashing
- **RBAC Manager**: Role-based permission checks (admin, read_write, read_only, custom roles)

### Security (`edb.security`)
- **Encryption**: AES-256-GCM field-level encryption at rest
- **Audit Logger**: Tamper-resistant append-only log with hash chain verification
- **Input Validator**: SQL injection, NoSQL injection, and prompt injection detection

### ebot (`edb.ebot`)
- **Translator**: Natural language → eDB query DSL (rule-based regex patterns)
- **Sanitizer**: Validates translations, enforces RBAC on AI-generated queries

### REST API (`edb.api`)
FastAPI application with routes for SQL, Documents, KV, Auth, Admin, and ebot. All endpoints require JWT authentication and RBAC permission checks.

## Data Flow

1. **Request** → FastAPI endpoint
2. **Auth** → JWT verification → RBAC check
3. **Validation** → Input sanitization
4. **Execution** → Query parser → Planner → Appropriate store
5. **Audit** → Log the operation with hash chain
6. **Response** → Unified result format

# === docs/api-reference.md ===

# eDB API Reference

Base URL: `http://localhost:8000`

All endpoints except `/auth/register`, `/auth/login`, and `/health` require a `Bearer` token in the `Authorization` header.

---

## Health

### `GET /health`
Returns server health status.

**Response:** `{"status": "healthy", "version": "0.1.0"}`

---

## Authentication

### `POST /auth/register`
Register a new user.

**Body:**
```json
{"username": "alice", "password": "secure123", "role": "read_only"}
```

### `POST /auth/login`
Authenticate and receive tokens.

**Body:** `{"username": "alice", "password": "secure123"}`

**Response:**
```json
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600
}
```

### `POST /auth/refresh`
Refresh an access token.

**Body:** `{"refresh_token": "eyJ..."}`

### `GET /auth/me`
Get current user profile. Requires auth.

---

## SQL (Relational)

### `POST /sql/tables`
Create a table.

**Body:**
```json
{
  "name": "users",
  "columns": [
    {"name": "id", "col_type": "INTEGER", "primary_key": true},
    {"name": "name", "col_type": "TEXT", "nullable": false},
    {"name": "email", "col_type": "TEXT", "unique": true}
  ]
}
```

### `GET /sql/tables`
List all tables.

### `GET /sql/tables/{table_name}?limit=100&offset=0`
Get table data.

### `POST /sql/tables/{table_name}/select`
Query with filters.

**Body:**
```json
{
  "columns": ["name", "email"],
  "where": {"name": "Alice"},
  "order_by": "name ASC",
  "limit": 10
}
```

### `POST /sql/tables/{table_name}/insert`
Insert a row.

**Body:** `{"data": {"name": "Alice", "email": "alice@test.com"}}`

### `PUT /sql/tables/{table_name}/update`
Update rows.

**Body:** `{"data": {"email": "newemail@test.com"}, "where": {"name": "Alice"}}`

### `DELETE /sql/tables/{table_name}/delete`
Delete rows.

**Body:** `{"where": {"name": "Alice"}}`

### `POST /sql/execute`
Execute raw SQL (requires `db:write` permission).

**Body:** `{"sql": "SELECT COUNT(*) FROM users", "params": []}`

---

## Documents (NoSQL)

### `GET /docs/collections`
List all collections.

### `POST /docs/{collection}`
Insert a document.

**Body:** `{"data": {"name": "Alice", "age": 30}, "doc_id": "optional-custom-id"}`

### `POST /docs/{collection}/find`
Find documents.

**Body:** `{"filter": {"name": "Alice"}, "limit": 10, "offset": 0}`

### `GET /docs/{collection}/{doc_id}`
Get document by ID.

### `PUT /docs/{collection}/{doc_id}`
Update document.

**Body:** `{"data": {"age": 31}, "merge": true}`

### `DELETE /docs/{collection}/{doc_id}`
Delete document.

---

## Key-Value

### `GET /kv/keys?prefix=user:`
List keys.

### `GET /kv/{key}`
Get value.

### `PUT /kv/{key}`
Set value.

**Body:** `{"value": {"theme": "dark"}, "ttl": 3600}`

### `DELETE /kv/{key}`
Delete key.

---

## ebot (AI)

### `POST /ebot/query`
Natural language query.

**Body:**
```json
{"text": "show all users", "execute": true}
```

**Response:**
```json
{
  "success": true,
  "original_text": "show all users",
  "translated_query": {"type": "sql", "action": "select", "table": "users"},
  "confidence": 0.7,
  "explanation": "SELECT all from 'users'",
  "result": {"success": true, "data": [...], "row_count": 5}
}
```

---

## Admin

### `GET /admin/users`
List all users (admin only).

### `PUT /admin/users/{user_id}/role`
Update user role.

**Body:** `{"role": "read_write"}`

### `DELETE /admin/users/{user_id}`
Deactivate a user.

### `GET /admin/audit?event_type=auth&limit=100`
Get audit logs.

### `GET /admin/audit/verify`
Verify audit log hash chain integrity.

### `GET /admin/stats`
Get database statistics.