README.md

---
license: apache-2.0
language:
- en
library_name: transformers
pipeline_tag: text-generation
tags:
- text-to-sql
- postgresql
- code-generation
base_model: Interchained/imagine-v8
---

# Imagine v9

**Quantized GGUF available:** `imagine-v9-Q4_K_M.gguf` (833MB) — runs on CPU via llama.cpp. Same model, 4-bit quantization.

**Imagine** is a compact local coding model built and fine-tuned by **Interchained**.

It is focused on PostgreSQL, schema-grounded text-to-SQL, database reasoning, and local-first deployment.

Imagine v9 is a research checkpoint fine-tuned from `Interchained/imagine-v8`. Where v8 was read-only, **v9 adds write capability**: it can generate `INSERT`, `UPDATE`, and `DELETE` statements grounded in the supplied schema.

## What Imagine is for

Imagine is designed for:

- PostgreSQL generation
- schema-grounded text-to-SQL
- database reasoning
- read **and** write SQL workflows
- local coding assistance
- structured database tasks
- local and self-hosted inference

Imagine is intentionally more focused than a general-purpose chatbot.

## Identity

The deployed model identity is **Imagine**.

Imagine was built and fine-tuned by **Interchained**.

DeepSeek-Coder is part of the upstream model lineage (via imagine-v8), but the deployed model identity is Imagine.

## Local-first

Imagine is intended to run locally on hardware controlled by the user.

Normal inference does not require a metered cloud inference API.

A larger teacher model may be used during research or curriculum generation, but Imagine does not require that teacher at runtime.

## PostgreSQL specialization

Imagine is trained around PostgreSQL and schema-grounded query generation.

The project emphasizes whether generated SQL:

1. parses correctly
2. satisfies the safety contract (read-only, or exactly one write statement)
3. binds against the supplied schema
4. executes successfully
5. answers the requested question — or produces the requested effect

The goal is not to match one reference SQL string exactly.

Different SQL queries can be semantically equivalent.

## Read/write SQL contract

Imagine v9 is trained for both read and write database tasks.

Expected reads include:

```
SELECT ...
```

and read-only:

```
WITH ...
SELECT ...
```

Expected writes are **exactly one** mutating statement per request:

```
INSERT INTO ...
```

```
UPDATE ... SET ... WHERE ...
```

```
DELETE FROM ... WHERE ...
```

Write requests that would require multiple statements, schema changes (`ALTER`, `DROP`, `CREATE`, `TRUNCATE`), or destructive unbounded operations remain out of contract.

Production deployments should still enforce access controls at the database-permission level. Writes should never run without human review.

## Schema grounding

Imagine should use only the schema supplied in the prompt.

It should not invent:

- tables
- columns
- relationships
- foreign keys
- join keys
- identifiers

If the requested information cannot be derived from the supplied schema, Imagine should avoid fabricating an answer.

Depending on the request, the correct response may be `UNANSWERABLE` or a clarification request.

## Ambiguity handling

Imagine is trained not to guess through material ambiguity.

If two reasonable interpretations would produce meaningfully different SQL or effects, Imagine should ask for clarification rather than silently choosing one.

This matters more for writes than reads: a wrong `WHERE` clause on a `DELETE` is not a rounding error.

## Output protocol

SQL tasks may use structured sentinel output:

```
<<<SQL>>>
SELECT ...
<<<END>>>
```

Unsupported requests may use:

```
<<<UNANSWERABLE>>>
...
<<<END>>>
```

Ambiguous requests may use clarification behavior rather than guessing.

## Training

Imagine v9 was produced by full fine-tuning from `Interchained/imagine-v8`.

The training path includes:

- imagine-v8 base (DeepSeek-Coder 1.3B lineage)
- PostgreSQL-focused supervised fine-tuning
- execution-gated SQL curriculum generation
- **write curriculum**: INSERT / UPDATE / DELETE templates verified by *effect*, not string match — candidate and reference run on two freshly materialized databases from identical state, and the pair is admitted only when both end in identical state
- relational writes via declared foreign keys (insert/update/delete through parent relationships)
- schema-grounding examples
- protocol-focused training

The project uses real database execution (via NEDB's PostgreSQL-compatible wire protocol) as part of its evaluation and curriculum pipeline.

Training corpus: 2,739 admitted pairs (1,931 reads + 810 writes), 99.9% gate admit rate.

- Full fine-tune, 1.35B trainable parameters
- 3 epochs, learning rate 1e-5, cosine schedule
- Final loss: 0.0320

## Execution gate

SQL is checked through several levels:

### Parse

The query must parse as PostgreSQL.

### Safety

The query must satisfy the contract: read-only, or exactly one `INSERT`/`UPDATE`/`DELETE`.

### Bind

The query must resolve successfully against the real supplied schema.

This catches nonexistent tables, nonexistent columns, ambiguous references, and related schema errors.

### Execute

The query must execute successfully.

### Result / effect agreement

For reads, the result is compared with a reference query. For writes, the *database state after execution* is compared: candidate and reference run on identical fresh databases, and the resulting states must match (excluding auto-generated IDs, which are nondeterministic across fresh databases).

Reference agreement is useful, but it is not identical to semantic correctness. A different projection or implementation may still answer the user's question correctly.

## Evaluation

A held-out telemetry evaluation contains 40 PostgreSQL questions.

- imagine-v8 baseline on this set: 50.0% (20/40)
- imagine-v9: 90.0% (36/40)
- Protocol compliance: 100%
- Strict parse: 100%
- Execute rate: 97.5%
- Invented relations: 0
- Invented columns: 0
- Refusals / unparseable / extra text: 0

Remaining failures were genuine wrong answers (unsupported predicates, unbounded date ranges, `count(DISTINCT col)` vs non-null row counts) and one gate policy stop on mixing `*` with aggregates.

## Example

Prompt:

```
What is the average cpu_pct in samples?
```

Possible output:

```
<<<SQL>>>
SELECT AVG(cpu_pct) FROM samples;
<<<END>>>
```

Write prompt:

```
Remove orders where status is 'refunded'.
```

Possible output:

```
<<<SQL>>>
DELETE FROM orders WHERE status = 'refunded';
<<<END>>>
```

## Loading Imagine

```
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_id = "Interchained/imagine-v9"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

messages = [
    {
        "role": "user",
        "content": "What model am I speaking with?"
    }
]

inputs = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_tensors="pt",
).to(model.device)

with torch.no_grad():
    output = model.generate(
        inputs,
        max_new_tokens=128,
        do_sample=False,
    )

response = tokenizer.decode(
    output[0][inputs["input_ids"].shape[-1]:],
    skip_special_tokens=True,
)

print(response)
```

## Intended use

Imagine is intended for:

- developers
- database engineers
- AI engineers
- PostgreSQL users
- text-to-SQL researchers
- local-model experimentation

## Limitations

Imagine v9 is a research checkpoint.

It may still:

- generate incorrect SQL
- misunderstand ambiguous requests
- apply incorrect filters
- choose incorrect ordering
- misunderstand business semantics
- deviate from the intended output protocol
- produce incomplete answers
- generate writes with wrong `WHERE` clauses — **always review write SQL before executing**
- show residual behavior from the upstream base model

Generated SQL should be reviewed before use in important systems. This applies doubly to writes.

## Security

Do not rely on model behavior alone for database safety.

Production systems should enforce controls such as:

- least-privilege database roles (read-only where writes aren't needed)
- statement timeouts
- row limits
- query validation
- schema restrictions
- application-level authorization
- audit logging
- human approval for all write statements

## Project philosophy

Imagine is built around three ideas: **Grounding over guessing.**

The supplied schema is the source of truth.

**Execution over string similarity.**

Correctness should be judged by what SQL actually does, not only whether it matches one reference string.

**Local control over unnecessary dependency.**

Useful coding models should be able to run on infrastructure controlled by the user.

## Status

**Imagine v9 — Research Checkpoint**

Built and fine-tuned by **Interchained**.