seedloom 0.1.0__tar.gz

seedloom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seedloom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seedloom-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: seedloom
+Version: 0.1.0
+Summary: AI-powered database seeding: introspects your schema and generates realistic, referentially-valid seed data with Claude, OpenAI, Gemini, or local models.
+Author-email: Naeem Ahmed <freelancer.nak@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/therealonenak/seedloom
+Project-URL: Repository, https://github.com/therealonenak/seedloom
+Project-URL: Issues, https://github.com/therealonenak/seedloom/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg2-binary>=2.9
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.50.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.3.0; extra == "gemini"
+Provides-Extra: ollama
+Requires-Dist: requests>=2.31; extra == "ollama"
+Provides-Extra: all
+Requires-Dist: seedloom[anthropic,gemini,ollama,openai]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: seedloom[all]; extra == "dev"
+Dynamic: license-file
+
+# seedloom
+
+AI-powered database seeding. `seedloom` connects to your PostgreSQL database,
+introspects the real schema (tables, columns, types, foreign keys, enums,
+constraints), and uses an LLM to generate realistic, **referentially-valid**
+seed data - then inserts it in the correct dependency order.
+
+Works with Claude, OpenAI, Gemini, local Ollama models, and any
+OpenAI-compatible endpoint (Groq, Together, Fireworks, OpenRouter, DeepSeek,
+Mistral, LM Studio, vLLM, text-generation-webui) - see [Providers](#providers).
+
+No more hand-writing 50 fake users and hoping your `orders` table's `user_id`
+values actually exist.
+
+## Why not just use Faker?
+
+Faker generates *plausible-looking* values per column, with no awareness of
+your schema's relationships. seedloom:
+
+- Reads your **actual** schema (works with Prisma, Django, raw SQL migrations - anything)
+- Resolves foreign key dependency order automatically (seeds `users` before `orders` before `order_items`)
+- Constrains foreign-key columns to an `enum` of **real, already-inserted** parent IDs - the model
+  structurally cannot invent a dangling reference
+- Respects `NOT NULL`, `UNIQUE`, enum types, and column types when generating values
+- Skips columns the DB fills in itself (`SERIAL`, `gen_random_uuid()`, `now()` defaults)
+- Auto-fills image/avatar/logo/banner/video columns with real, working CDN URLs
+  (picsum.photos, i.pravatar.cc, sample .mp4s) instead of letting the model
+  invent broken links
+- Automatically excludes ORM/migration bookkeeping tables (`SequelizeMeta`,
+  `knex_migrations`, `alembic_version`, `django_migrations`,
+  `__EFMigrationsHistory`, etc.) from introspection - they're never seeded
+- Swap the LLM provider with one flag or env var - cloud or fully local/free
+
+## Install
+
+```bash
+pip install seedloom[anthropic]   # or [openai], [gemini], [ollama], [all]
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/therealonenak/seedloom
+cd seedloom
+pip install -e ".[all]"
+```
+
+Each provider is an optional extra so you only install the SDK you need.
+`ollama` has no cloud SDK - it just needs `requests`, already covered by that extra.
+
+## Setup
+
+Set `DATABASE_URL` plus whichever provider you're using (or put them in a `.env`
+file in your working directory):
+
+```bash
+export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
+export SEEDLOOM_PROVIDER="anthropic"       # default; see Providers below
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+## Usage
+
+```bash
+# 1. Introspect your schema and cache it locally
+seedloom init
+
+# 2. Generate + insert seed data, in FK-safe order
+seedloom run --rows 20
+
+# Preview generated data without inserting anything
+seedloom run --rows 5 --dry-run
+
+# Only seed specific tables
+seedloom run --rows 50 --tables users,products
+
+# Override the provider/model for a single run
+seedloom run --provider gemini --model gemini-2.5-flash --rows 20
+seedloom run --provider ollama --model llama3.1 --rows 20
+```
+
+Try it against the example schema in `examples/schema.sql` on a scratch database.
+
+## Providers
+
+Set `SEEDLOOM_PROVIDER` (or pass `--provider`) plus the matching API key env var.
+`SEEDLOOM_MODEL` overrides the default model for any provider.
+
+| Provider | `SEEDLOOM_PROVIDER` | API key env var | Notes |
+|---|---|---|---|
+| Anthropic (Claude) | `anthropic` | `ANTHROPIC_API_KEY` | default |
+| OpenAI | `openai` | `OPENAI_API_KEY` | |
+| Google Gemini | `gemini` | `GEMINI_API_KEY` | official Gemini API; free tier is capped at 20 requests/day per model - schemas with many tables will likely exhaust it in one run |
+| Ollama (local) | `ollama` | - | run any open-source model locally; needs `ollama serve` |
+| Groq | `groq` | `GROQ_API_KEY` | free tier, serves open-source models fast |
+| Together AI | `together` | `TOGETHER_API_KEY` | open-source models, free tier |
+| Fireworks AI | `fireworks` | `FIREWORKS_API_KEY` | open-source models |
+| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | many free `:free`-suffixed open-source models |
+| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | |
+| Mistral | `mistral` | `MISTRAL_API_KEY` | |
+| LM Studio (local) | `lmstudio` | - | local server, OpenAI-compatible |
+| vLLM (local) | `vllm` | - | local server, OpenAI-compatible |
+| text-generation-webui (local) | `text_generation_webui` | - | local server, OpenAI-compatible |
+| Any OpenAI-compatible endpoint | `openai_compatible` | `OPENAI_COMPATIBLE_API_KEY` | set `SEEDLOOM_BASE_URL` |
+
+Ollama host defaults to `http://localhost:11434`; override with `SEEDLOOM_HOST` or `--host`.
+Custom/self-hosted OpenAI-compatible endpoints use `SEEDLOOM_BASE_URL` or `--base-url`.
+
+A note on **Google Antigravity**: it's a desktop agentic IDE, not something with
+a public API for scripts like this to call. If you want Google's models
+programmatically, `gemini` (the official Gemini API) is the supported path -
+same models, real API key, free tier included.
+
+## How it works
+
+1. **Introspect** - queries `information_schema` / `pg_catalog` to build a full
+   picture of your schema: columns, types, nullability, uniqueness, enums, and
+   foreign keys. ORM/migration bookkeeping tables are filtered out automatically.
+2. **Order** - topologically sorts tables so parents are always seeded before
+   their dependents (`users` → `orders` → `order_items`).
+3. **Generate** - for each table, builds a JSON Schema describing exactly what
+   a valid row looks like (including an `enum` of real parent-key values for
+   any FK column) and asks the configured provider to fill it in via
+   tool-use / structured output. Image/video columns are then populated with
+   real, working CDN URLs rather than model-invented links.
+4. **Insert** - batch-inserts the generated rows and tracks the primary keys
+   the database assigns, so the *next* table's foreign keys always point at
+   something real.
+
+## Rate limits
+
+Cloud providers get automatic retry with exponential backoff on transient
+429/rate-limit errors, honoring the provider's own suggested retry delay
+when it's present in the error. If a provider reports a **daily** quota is
+exhausted (e.g. Gemini's free-tier 20-requests/day cap), seedloom fails
+fast with a clear message instead of retrying for several minutes against
+a quota that won't reset - switch `--provider`/`--model` or re-run once it
+resets. Already-seeded tables are skipped automatically on the next run.
+
+## Limitations (v1)
+
+- PostgreSQL only (MySQL/SQLite support welcome as a PR)
+- Single-column primary keys only for FK-pool tracking (composite PKs insert fine, just aren't reused as FK sources yet)
+- No deferred-constraint support for genuinely cyclic FK relationships between two tables
+- No per-provider quota/cost estimation before a run - a large schema can burn through a free-tier daily quota in a single `seedloom run`
+
+## Contributing
+
+PRs welcome - this was built as a learning project and is deliberately kept
+readable over clever. Good first contributions: MySQL/SQLite introspection,
+composite PK support, a `--seed-from-existing` mode that samples real rows
+for context instead of generating from scratch.
+
+## License
+
+MIT

seedloom-0.1.0/README.md

@@ -0,0 +1,156 @@
+# seedloom
+
+AI-powered database seeding. `seedloom` connects to your PostgreSQL database,
+introspects the real schema (tables, columns, types, foreign keys, enums,
+constraints), and uses an LLM to generate realistic, **referentially-valid**
+seed data - then inserts it in the correct dependency order.
+
+Works with Claude, OpenAI, Gemini, local Ollama models, and any
+OpenAI-compatible endpoint (Groq, Together, Fireworks, OpenRouter, DeepSeek,
+Mistral, LM Studio, vLLM, text-generation-webui) - see [Providers](#providers).
+
+No more hand-writing 50 fake users and hoping your `orders` table's `user_id`
+values actually exist.
+
+## Why not just use Faker?
+
+Faker generates *plausible-looking* values per column, with no awareness of
+your schema's relationships. seedloom:
+
+- Reads your **actual** schema (works with Prisma, Django, raw SQL migrations - anything)
+- Resolves foreign key dependency order automatically (seeds `users` before `orders` before `order_items`)
+- Constrains foreign-key columns to an `enum` of **real, already-inserted** parent IDs - the model
+  structurally cannot invent a dangling reference
+- Respects `NOT NULL`, `UNIQUE`, enum types, and column types when generating values
+- Skips columns the DB fills in itself (`SERIAL`, `gen_random_uuid()`, `now()` defaults)
+- Auto-fills image/avatar/logo/banner/video columns with real, working CDN URLs
+  (picsum.photos, i.pravatar.cc, sample .mp4s) instead of letting the model
+  invent broken links
+- Automatically excludes ORM/migration bookkeeping tables (`SequelizeMeta`,
+  `knex_migrations`, `alembic_version`, `django_migrations`,
+  `__EFMigrationsHistory`, etc.) from introspection - they're never seeded
+- Swap the LLM provider with one flag or env var - cloud or fully local/free
+
+## Install
+
+```bash
+pip install seedloom[anthropic]   # or [openai], [gemini], [ollama], [all]
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/therealonenak/seedloom
+cd seedloom
+pip install -e ".[all]"
+```
+
+Each provider is an optional extra so you only install the SDK you need.
+`ollama` has no cloud SDK - it just needs `requests`, already covered by that extra.
+
+## Setup
+
+Set `DATABASE_URL` plus whichever provider you're using (or put them in a `.env`
+file in your working directory):
+
+```bash
+export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
+export SEEDLOOM_PROVIDER="anthropic"       # default; see Providers below
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+## Usage
+
+```bash
+# 1. Introspect your schema and cache it locally
+seedloom init
+
+# 2. Generate + insert seed data, in FK-safe order
+seedloom run --rows 20
+
+# Preview generated data without inserting anything
+seedloom run --rows 5 --dry-run
+
+# Only seed specific tables
+seedloom run --rows 50 --tables users,products
+
+# Override the provider/model for a single run
+seedloom run --provider gemini --model gemini-2.5-flash --rows 20
+seedloom run --provider ollama --model llama3.1 --rows 20
+```
+
+Try it against the example schema in `examples/schema.sql` on a scratch database.
+
+## Providers
+
+Set `SEEDLOOM_PROVIDER` (or pass `--provider`) plus the matching API key env var.
+`SEEDLOOM_MODEL` overrides the default model for any provider.
+
+| Provider | `SEEDLOOM_PROVIDER` | API key env var | Notes |
+|---|---|---|---|
+| Anthropic (Claude) | `anthropic` | `ANTHROPIC_API_KEY` | default |
+| OpenAI | `openai` | `OPENAI_API_KEY` | |
+| Google Gemini | `gemini` | `GEMINI_API_KEY` | official Gemini API; free tier is capped at 20 requests/day per model - schemas with many tables will likely exhaust it in one run |
+| Ollama (local) | `ollama` | - | run any open-source model locally; needs `ollama serve` |
+| Groq | `groq` | `GROQ_API_KEY` | free tier, serves open-source models fast |
+| Together AI | `together` | `TOGETHER_API_KEY` | open-source models, free tier |
+| Fireworks AI | `fireworks` | `FIREWORKS_API_KEY` | open-source models |
+| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | many free `:free`-suffixed open-source models |
+| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | |
+| Mistral | `mistral` | `MISTRAL_API_KEY` | |
+| LM Studio (local) | `lmstudio` | - | local server, OpenAI-compatible |
+| vLLM (local) | `vllm` | - | local server, OpenAI-compatible |
+| text-generation-webui (local) | `text_generation_webui` | - | local server, OpenAI-compatible |
+| Any OpenAI-compatible endpoint | `openai_compatible` | `OPENAI_COMPATIBLE_API_KEY` | set `SEEDLOOM_BASE_URL` |
+
+Ollama host defaults to `http://localhost:11434`; override with `SEEDLOOM_HOST` or `--host`.
+Custom/self-hosted OpenAI-compatible endpoints use `SEEDLOOM_BASE_URL` or `--base-url`.
+
+A note on **Google Antigravity**: it's a desktop agentic IDE, not something with
+a public API for scripts like this to call. If you want Google's models
+programmatically, `gemini` (the official Gemini API) is the supported path -
+same models, real API key, free tier included.
+
+## How it works
+
+1. **Introspect** - queries `information_schema` / `pg_catalog` to build a full
+   picture of your schema: columns, types, nullability, uniqueness, enums, and
+   foreign keys. ORM/migration bookkeeping tables are filtered out automatically.
+2. **Order** - topologically sorts tables so parents are always seeded before
+   their dependents (`users` → `orders` → `order_items`).
+3. **Generate** - for each table, builds a JSON Schema describing exactly what
+   a valid row looks like (including an `enum` of real parent-key values for
+   any FK column) and asks the configured provider to fill it in via
+   tool-use / structured output. Image/video columns are then populated with
+   real, working CDN URLs rather than model-invented links.
+4. **Insert** - batch-inserts the generated rows and tracks the primary keys
+   the database assigns, so the *next* table's foreign keys always point at
+   something real.
+
+## Rate limits
+
+Cloud providers get automatic retry with exponential backoff on transient
+429/rate-limit errors, honoring the provider's own suggested retry delay
+when it's present in the error. If a provider reports a **daily** quota is
+exhausted (e.g. Gemini's free-tier 20-requests/day cap), seedloom fails
+fast with a clear message instead of retrying for several minutes against
+a quota that won't reset - switch `--provider`/`--model` or re-run once it
+resets. Already-seeded tables are skipped automatically on the next run.
+
+## Limitations (v1)
+
+- PostgreSQL only (MySQL/SQLite support welcome as a PR)
+- Single-column primary keys only for FK-pool tracking (composite PKs insert fine, just aren't reused as FK sources yet)
+- No deferred-constraint support for genuinely cyclic FK relationships between two tables
+- No per-provider quota/cost estimation before a run - a large schema can burn through a free-tier daily quota in a single `seedloom run`
+
+## Contributing
+
+PRs welcome - this was built as a learning project and is deliberately kept
+readable over clever. Good first contributions: MySQL/SQLite introspection,
+composite PK support, a `--seed-from-existing` mode that samples real rows
+for context instead of generating from scratch.
+
+## License
+
+MIT

seedloom-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seedloom"
+version = "0.1.0"
+description = "AI-powered database seeding: introspects your schema and generates realistic, referentially-valid seed data with Claude, OpenAI, Gemini, or local models."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Naeem Ahmed", email = "freelancer.nak@gmail.com" }]
+dependencies = [
+    "psycopg2-binary>=2.9",
+    "click>=8.1",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/therealonenak/seedloom"
+Repository = "https://github.com/therealonenak/seedloom"
+Issues = "https://github.com/therealonenak/seedloom/issues"
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40.0"]
+openai = ["openai>=1.50.0"]
+gemini = ["google-genai>=0.3.0"]
+ollama = ["requests>=2.31"]
+all = ["seedloom[anthropic,openai,gemini,ollama]"]
+dev = ["pytest>=8.0", "seedloom[all]"]
+
+[project.scripts]
+seedloom = "seedloom.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["seedloom*"]

seedloom-0.1.0/seedloom/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

seedloom-0.1.0/seedloom/cli.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import psycopg2
+from rich.console import Console
+from rich.table import Table as RichTable
+
+from .config import Config
+from .generator import generate_rows
+from .graph import CyclicDependencyError, resolve_seed_order
+from .inserter import existing_column_values, insert_rows, table_row_count
+from .introspect import introspect
+from .models import Schema
+from .providers import ProviderError, SUPPORTED_PROVIDERS, get_provider
+
+console = Console()
+SCHEMA_CACHE = Path(".seedloom_schema.json")
+
+
+@click.group()
+def main() -> None:
+    """seedloom — AI-powered database seeding.
+
+    Introspects your Postgres schema and uses Claude to generate realistic,
+    referentially-valid seed data.
+    """
+
+
+@main.command()
+def init() -> None:
+    """Connect to the database, introspect the schema, and cache it locally."""
+    try:
+        config = Config.load(require_provider=False)
+    except EnvironmentError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+
+    console.print("[cyan]Connecting and introspecting schema...[/cyan]")
+    try:
+        schema = introspect(config.database_url)
+    except psycopg2.OperationalError as e:
+        console.print(f"[red]Could not connect to database: {e}[/red]")
+        sys.exit(1)
+
+    if not schema.tables:
+        console.print("[yellow]No tables found in the 'public' schema.[/yellow]")
+        sys.exit(0)
+
+    SCHEMA_CACHE.write_text(json.dumps(schema.to_dict(), indent=2))
+
+    t = RichTable(title="Discovered schema")
+    t.add_column("Table")
+    t.add_column("Columns")
+    t.add_column("Foreign Keys")
+    for table in schema.tables.values():
+        fks = ", ".join(f"{fk.column}->{fk.ref_table}.{fk.ref_column}" for fk in table.foreign_keys)
+        t.add_row(table.name, str(len(table.columns)), fks or "-")
+    console.print(t)
+    console.print(f"[green]Schema cached to {SCHEMA_CACHE}[/green]. Run 'seedloom run' next.")
+
+
+@main.command()
+@click.option("--rows", default=10, show_default=True, help="Rows to generate per table.")
+@click.option("--tables", default=None, help="Comma-separated subset of tables to seed (default: all).")
+@click.option("--dry-run", is_flag=True, help="Generate data and print it without inserting.")
+@click.option(
+    "--provider",
+    default=None,
+    help=f"Override provider from config. Supported: {', '.join(SUPPORTED_PROVIDERS)}.",
+)
+@click.option("--model", default=None, help="Override model from config.")
+@click.option("--base-url", default=None, help="Override base URL (openai_compatible or self-hosted endpoints).")
+@click.option("--host", default=None, help="Override Ollama host (default: http://localhost:11434).")
+def run(
+    rows: int,
+    tables: str | None,
+    dry_run: bool,
+    provider: str | None,
+    model: str | None,
+    base_url: str | None,
+    host: str | None,
+) -> None:
+    """Generate and insert seed data, respecting foreign key order."""
+    try:
+        config = Config.load(provider_override=provider or "")
+    except EnvironmentError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+
+    if not SCHEMA_CACHE.exists():
+        console.print("[red]No cached schema found. Run 'seedloom init' first.[/red]")
+        sys.exit(1)
+
+    schema = Schema.from_dict(json.loads(SCHEMA_CACHE.read_text()))
+
+    try:
+        order = resolve_seed_order(schema)
+    except CyclicDependencyError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+
+    if tables:
+        wanted = set(t.strip() for t in tables.split(","))
+        order = [t for t in order if t in wanted]
+
+    try:
+        active_provider = get_provider(
+            config.provider,
+            api_key=config.api_key,
+            model=model or config.model,
+            base_url=base_url or config.base_url,
+            host=host or config.host,
+        )
+    except ProviderError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+
+    console.print(f"[cyan]Using provider: {config.provider}[/cyan]")
+    conn = None if dry_run else psycopg2.connect(config.database_url)
+
+    fk_pools: dict[str, dict[str, list]] = {}  # table -> column -> values
+
+    referenced_columns: dict[str, set[str]] = {}
+    for t in schema.tables.values():
+        for fk in t.foreign_keys:
+            referenced_columns.setdefault(fk.ref_table, set()).add(fk.ref_column)
+
+    try:
+        for table_name in order:
+            table = schema.tables[table_name]
+            needed_columns = sorted(referenced_columns.get(table_name, set()))
+
+            to_generate = rows
+            if conn is not None:
+                existing_count = table_row_count(conn, table_name)
+                if existing_count > 0 and needed_columns:
+                    existing_values = existing_column_values(conn, table_name, needed_columns)
+                    for col, vals in existing_values.items():
+                        if vals:
+                            fk_pools.setdefault(table_name, {})[col] = vals
+
+                if existing_count >= rows:
+                    console.print(
+                        f"[yellow]Skipping '{table_name}' — already has {existing_count} row(s) "
+                        f"(>= {rows} requested).[/yellow]"
+                    )
+                    continue
+
+                to_generate = rows - existing_count
+                if existing_count > 0:
+                    console.print(
+                        f"[cyan]'{table_name}' has {existing_count} row(s); generating "
+                        f"{to_generate} more to reach {rows}...[/cyan]"
+                    )
+                else:
+                    console.print(f"[cyan]Generating {to_generate} rows for '{table_name}'...[/cyan]")
+            else:
+                console.print(f"[cyan]Generating {to_generate} rows for '{table_name}'...[/cyan]")
+
+            fk_value_pool: dict[str, list] = {}
+            for fk in table.foreign_keys:
+                parent_pool = fk_pools.get(fk.ref_table, {}).get(fk.ref_column, [])
+                if parent_pool:
+                    fk_value_pool[fk.column] = parent_pool
+
+            try:
+                generated = generate_rows(active_provider, table, to_generate, fk_value_pool)
+            except ProviderError as e:
+                console.print(f"[red]{e}[/red]")
+                sys.exit(1)
+
+            if dry_run:
+                console.print(generated)
+                continue
+
+            inserted_values = insert_rows(conn, table, generated, needed_columns)
+            for col, vals in inserted_values.items():
+                if vals:
+                    fk_pools.setdefault(table_name, {}).setdefault(col, [])
+                    fk_pools[table_name][col].extend(vals)
+
+            console.print(f"[green]Inserted {len(generated)} rows into '{table_name}'.[/green]")
+    finally:
+        if conn:
+            conn.close()
+
+    console.print("[bold green]Done.[/bold green]")
+
+
+if __name__ == "__main__":
+    main()

seedloom-0.1.0/seedloom/config.py

@@ -0,0 +1,85 @@
+"""Configuration loading: env vars + optional .env file, no external deps."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .providers import NO_KEY_REQUIRED, SUPPORTED_PROVIDERS
+
+_PROVIDER_KEY_ENV: dict[str, str] = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "together": "TOGETHER_API_KEY",
+    "fireworks": "FIREWORKS_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "openai_compatible": "OPENAI_COMPATIBLE_API_KEY",
+}
+
+
+def _load_dotenv(path: Path = Path(".env")) -> None:
+    """Minimal .env loader — avoids pulling in python-dotenv as a dependency."""
+    if not path.exists():
+        return
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        os.environ.setdefault(key, value)
+
+
+@dataclass
+class Config:
+    database_url: str
+    provider: str = "anthropic"
+    api_key: str = ""
+    model: str = ""
+    base_url: str = ""
+    host: str = ""
+
+    @classmethod
+    def load(cls, provider_override: str = "", require_provider: bool = True) -> "Config":
+        _load_dotenv()
+        db_url = os.environ.get("DATABASE_URL", "")
+        provider = (provider_override or os.environ.get("SEEDLOOM_PROVIDER", "anthropic")).lower()
+        model = os.environ.get("SEEDLOOM_MODEL", "")
+        base_url = os.environ.get("SEEDLOOM_BASE_URL", "")
+        host = os.environ.get("SEEDLOOM_HOST", "")
+
+        missing = []
+        if not db_url:
+            missing.append("DATABASE_URL")
+
+        if provider not in SUPPORTED_PROVIDERS:
+            raise EnvironmentError(
+                f"Unknown provider '{provider}'. Supported: {', '.join(SUPPORTED_PROVIDERS)}."
+            )
+
+        api_key = ""
+        if require_provider and provider not in NO_KEY_REQUIRED:
+            key_env = _PROVIDER_KEY_ENV.get(provider, f"{provider.upper()}_API_KEY")
+            api_key = os.environ.get(key_env, "")
+            if not api_key:
+                missing.append(key_env)
+
+        if missing:
+            raise EnvironmentError(
+                f"Missing required environment variable(s): {', '.join(missing)}. "
+                "Set them in your shell or in a .env file in the current directory."
+            )
+
+        return cls(
+            database_url=db_url,
+            provider=provider,
+            api_key=api_key,
+            model=model,
+            base_url=base_url,
+            host=host,
+        )