Metadata-Version: 2.4
Name: walkindb
Version: 0.1.0
Summary: Disposable SQLite for LLM agents. A single HTTP call provisions a private database with a 10-minute TTL. No signup, no API key, no credit card.
Project-URL: Homepage, https://walkindb.com
Project-URL: Repository, https://github.com/walkindb/walkindb
Project-URL: Documentation, https://walkindb.com/
Project-URL: Issues, https://github.com/walkindb/walkindb/issues
Author: walkindb
License-Expression: Apache-2.0
Keywords: agents,anthropic,database,ephemeral,llm,mcp,openai,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# walkindb

Python client for [walkindb](https://walkindb.com) — disposable SQLite for LLM agents.

A single HTTP call provisions a private SQLite database with a 10-minute TTL. No signup, no API key, no credit card.

## Install

```bash
pip install walkindb
```

Zero runtime dependencies — the client uses only the Python standard library, so it installs cleanly inside any agent sandbox.

## Use

```python
from walkindb import Client

db = Client()
db.execute("CREATE TABLE notes(id INTEGER PRIMARY KEY, body TEXT)")
db.execute("INSERT INTO notes(body) VALUES('hello')")
result = db.execute("SELECT * FROM notes")
print(result.columns)       # ['id', 'body']
print(result.rows)          # [[1, 'hello']]
print(result.rows_affected) # 0 for SELECT, N for INSERT/UPDATE/DELETE

# The session token lives on the Client instance and is reused on subsequent
# calls, so you keep reaching the same walk-in database until its 10-minute
# TTL expires. `db.session` holds the token; `db.expires_at` is the unix
# timestamp at which the instance will be deleted.
print(db.session, db.expires_at)
```

If you want a fresh walk-in:

```python
db.reset_session()
db.execute("SELECT 1")  # provisions a new instance
```

## Errors

Non-2xx responses raise `WalkinDBError` with `status` and `error` attributes. Notable codes:

- **400** — invalid JSON, missing `sql`, forbidden keyword, or SQL syntax error
- **404** — session token unknown, tampered, or expired (walkindb returns 404, not 401, on all session failures to prevent enumeration)
- **408** — query exceeded the 2-second wall-clock timeout
- **413** — request body exceeded the 8 KB cap
- **429** — rate limit exceeded (60 req/min, 10 new instance creations/min per IP)
- **507** — instance storage quota exceeded (10 MB per walk-in)

```python
from walkindb import Client, WalkinDBError

db = Client()
try:
    db.execute("SELECT * FROM does_not_exist")
except WalkinDBError as e:
    print(f"error {e.status}: {e.error}")
```

## Smoke test

```bash
python -m walkindb
```

Provisions a fresh walk-in, runs `SELECT 1`, and prints the session token.

## What walkindb is not

- Not a durable database. Data is deleted after ~10 minutes.
- Not for PII or regulated data. See the [AUP](https://walkindb.com/legal/aup/).
- Not a Postgres or MySQL replacement.

Apache 2.0. Server source at [github.com/walkindb/walkindb](https://github.com/walkindb/walkindb). Landing page and full docs at [walkindb.com](https://walkindb.com).
