Metadata-Version: 2.4
Name: wiseql
Version: 0.2.0
Summary: WiseQL — the wise data browser: run SQL recipes as small, observable, debuggable steps. In development.
Project-URL: Homepage, https://wiseql.dev
Project-URL: Repository, https://github.com/wiseql/wiseql
Project-URL: Issues, https://github.com/wiseql/wiseql/issues
Author-email: Reza Azizi <azizi.ra@gmail.com>
License: MIT
License-File: LICENSE
Keywords: data-quality,debugging,duckdb,oracle,pipeline,sql,tui
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.12
Requires-Dist: duckdb>=1.1
Requires-Dist: keyring>=25.0
Requires-Dist: oracledb>=2.4
Requires-Dist: pydantic>=2.7
Requires-Dist: textual>=1.0
Requires-Dist: typer>=0.12
Provides-Extra: ai
Requires-Dist: ollama>=0.3; extra == 'ai'
Description-Content-Type: text/markdown

# WiseQL

**The wise data browser.** A terminal app that runs **SQL recipes** — a complex
database read broken into a DAG of small, observable steps — with a live run
view, per-step reports, assertions that catch data issues automatically,
checkpoint/resume, run diffing, an in-app data explorer, and an optional local
AI layer that explains what a run did.

A 400-line SQL query is a black box. WiseQL turns it into a glass box.

> Early but usable. Oracle first (thin mode — no Instant Client needed),
> PostgreSQL next; DuckDB inside; read-only by default.

## Install

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/) (or pipx).

```bash
# from GitHub (with the optional AI add-on)
uv tool install "wiseql[ai] @ git+https://github.com/wiseql/wiseql.git"

# …or without AI
uv tool install "git+https://github.com/wiseql/wiseql.git"

# …or from a local clone
git clone https://github.com/wiseql/wiseql.git && cd wiseql
uv tool install '.[ai]'
```

This puts `wiseql` on your PATH. Check it:

```bash
wiseql version
wiseql --help
```

(`pipx install "wiseql[ai] @ git+https://github.com/wiseql/wiseql.git"` works too.)

## Connect to your database

Connections live in `~/.config/wiseql/config.toml` and hold everything **except**
the password (recipes reference them by name, so they stay shareable):

```toml
[connections.main]
driver  = "oracle"
host    = "db.example.com"
port    = 1521
service = "PROD"
user    = "me_readonly"
auth    = "keyring"          # OS keychain (default) · or "env" · or "wallet"

[defaults]
connection = "main"
```

Then store the password and test reachability:

```bash
wiseql conn login main      # prompts once, stores in your OS keyring
wiseql conn test main       # connects, reports latency + DB version
wiseql conn list            # see configured connections
```

> Use a **read-only** database user. WiseQL refuses non-SELECT SQL, but a
> read-only user is the real guarantee.

## Create a project and run a recipe

```bash
wiseql init returns-monitoring -c main           # scaffolds project.toml, recipes/, context/, runs/
cd returns-monitoring
wiseql context sync returns-monitoring -c main   # introspect the schema into context/tables.md
```

Add a recipe under `recipes/` (write one by hand — see
[RECIPE_SPEC.md](./RECIPE_SPEC.md) — or generate them, below). Then:

```bash
wiseql validate recipes/*.toml     # structural validation (add --ai for a semantic second opinion)
wiseql                             # open the TUI → pick the project → pick a recipe → F2 to run
wiseql run recipes/late-returns.toml --param run_date=2026-06-01   # …or headless (cron/CI; exit code is the contract)
```

Projects live in a visible **`~/wiseql/`** folder by default (override with
`[defaults] projects_dir` in `config.toml`). The dashboard shows the project's
folder path, and **Ctrl+O** opens it in Finder.

In the TUI: **F2** run · **F4** edit the selected recipe (built-in editor,
Ctrl+S to save) · **F5** new recipe · **Enter** drill into a step's data ·
**Ctrl+R** resume a failed run · **Ctrl+D** diff vs the previous run · **Ctrl+E**
explore a run's data with ad-hoc SQL · **Ctrl+O** open the project folder ·
**F4 on a run** AI-explain what happened · **F9** settings.

## Generate recipes with AI

If you have an AI assistant with access to your schema/SQL, paste the prompt in
[docs/recipe-generator-prompt.md](./docs/recipe-generator-prompt.md) — it emits a
complete WiseQL project (project.toml + recipes + context) for your database.
Then `wiseql validate recipes/*.toml` and run them.

## Optional: the local AI add-on

AI is **off by default** and never required. It runs locally via
[Ollama](https://ollama.com) — nothing leaves your machine.

```bash
# install Ollama, then:
ollama serve &
ollama pull gemma3            # or any local model tag you prefer
wiseql ai setup --model gemma3
wiseql ai status             # should say: ✓ ready
```

With it enabled, **F4** on a run streams an explanation (what the run did, what
looks correct, what's wrong and where to look), and `wiseql validate --ai` adds
a semantic recipe review. If Ollama is off or the model is missing, AI features
show a hint and the rest of the app is unaffected.

## Docs

- [RECIPE_SPEC.md](./RECIPE_SPEC.md) — the recipe format (authoritative)
- [docs/recipe-generator-prompt.md](./docs/recipe-generator-prompt.md) — generate recipes from your schema

## License

MIT
