seedforge 0.1.0__tar.gz

seedforge-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: seedforge
+Version: 0.1.0
+Summary: AI-powered test data generator that reads your database schema and fills it with realistic, FK-valid data in seconds
+Author-email: SilkHorizon <hello@silkhorizon.uz>
+License: MIT
+Project-URL: Homepage, https://github.com/silkhorizonstudios/seedforge
+Project-URL: Documentation, https://seedforge.dev
+Project-URL: Repository, https://github.com/silkhorizonstudios/seedforge
+Keywords: database,testing,faker,seed,synthetic-data,postgresql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: faker>=25.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1.0; extra == "mysql"
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.40.0; extra == "ai"
+Provides-Extra: all
+Requires-Dist: pymysql>=1.1.0; extra == "all"
+Requires-Dist: anthropic>=0.40.0; extra == "all"
+
+# SeedForge
+
+**One command to fill your database with realistic test data.**
+
+SeedForge connects to your database, reads the schema (tables, columns, foreign keys, constraints), and generates realistic, FK-valid data — no code, no config, no seed scripts.
+
+```bash
+pip install seedforge
+seedforge connect postgresql://user:pass@localhost/mydb
+seedforge generate --rows 1000
+# Done. 40 tables filled in 3 seconds.
+```
+
+## Features
+
+- **Zero-config** — reads your DB schema automatically, no setup needed
+- **FK integrity** — resolves foreign keys via topological sort, inserts in correct order
+- **Smart heuristics** — 80+ column name patterns for realistic data (`email` → real email, `price` → decimal, `role` → admin/user/editor)
+- **Deterministic** — use `--seed` to get the same data every time
+- **AI-powered** — optional Claude AI integration for maximum realism
+- **Export** — SQL or JSON file output
+- **Privacy-first** — runs entirely locally, your data never leaves your machine
+
+## Installation
+
+```bash
+pip install seedforge
+
+# With MySQL support
+pip install seedforge[mysql]
+
+# With AI support (Claude API)
+pip install seedforge[ai]
+
+# Everything
+pip install seedforge[all]
+```
+
+## Quick Start
+
+### 1. Connect
+
+```bash
+seedforge connect postgresql://user:pass@localhost:5432/mydb
+```
+
+Saves the connection to `.seedforge.yaml` so you don't have to type it again.
+
+### 2. Inspect
+
+```bash
+seedforge inspect
+```
+
+Shows all tables, columns, types, foreign keys, and insertion order:
+
+```
+Found 18 tables (insertion order):
+
+         1. users
+┏━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓
+┃ Column     ┃ Type      ┃ Nullable ┃ FK →  ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩
+│ id         │ serial    │ NO       │       │
+│ email      │ varchar   │ NO       │       │
+│ name       │ varchar   │ YES      │       │
+└────────────┴───────────┴──────────┴───────┘
+
+             2. orders
+┏━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Column     ┃ Type      ┃ Nullable ┃ FK →       ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ id         │ serial    │ NO       │            │
+│ user_id    │ integer   │ NO       │ users.id   │
+│ total      │ numeric   │ NO       │            │
+└────────────┴───────────┴──────────┴────────────┘
+```
+
+### 3. Generate
+
+```bash
+# Generate and insert 100 rows per table
+seedforge generate --rows 100
+
+# Preview without inserting
+seedforge generate --rows 10 --dry-run
+
+# Export to SQL file
+seedforge generate --rows 1000 --export sql
+
+# Export to JSON
+seedforge generate --rows 1000 --export json
+
+# Deterministic (same data every time)
+seedforge generate --rows 100 --seed 42
+
+# Only specific tables (auto-includes FK parents)
+seedforge generate --tables orders,payments --rows 50
+
+# Clean tables before generating
+seedforge generate --rows 100 --clean
+```
+
+### 4. AI Generate (optional)
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+seedforge ai-generate --rows 20
+```
+
+Uses Claude AI to generate context-aware data with maximum realism.
+
+## How It Works
+
+1. **Schema introspection** — connects to your database, reads `information_schema` to get tables, columns, types, FK relationships, constraints, ENUMs
+2. **Dependency graph** — builds a directed graph from FK relationships, runs topological sort to determine insertion order (parents first)
+3. **Smart heuristics** — maps column names to appropriate generators (`email` → realistic email, `phone` → phone number, `created_at` → recent datetime)
+4. **FK resolution** — child rows automatically reference real IDs from already-generated parent rows
+5. **Batch insert** — fast bulk insertion with proper transaction handling
+
+## Column Name Heuristics
+
+SeedForge automatically detects what kind of data to generate based on column names:
+
+| Column name | Generated data |
+|---|---|
+| `email` | `john.smith@example.com` |
+| `phone`, `mobile` | `+1-555-0123` |
+| `first_name` | `John` |
+| `last_name` | `Smith` |
+| `username` | `jsmith42` |
+| `address`, `street` | `123 Main St, Apt 4` |
+| `city` | `San Francisco` |
+| `country` | `United States` |
+| `price`, `amount`, `total` | `49.99` |
+| `url`, `website` | `https://example.com` |
+| `avatar`, `image_url` | `https://picsum.photos/seed/123/400/300` |
+| `role` | `admin`, `user`, `moderator` |
+| `status` | `active`, `pending`, `completed` |
+| `plan` | `free`, `pro`, `enterprise` |
+| `created_at`, `updated_at` | Recent datetime |
+| `is_active`, `verified` | `true` (85% bias) |
+| `is_deleted`, `archived` | `false` (90% bias) |
+| `password` | SHA-256 hash |
+| `token`, `api_key` | Random hex string |
+| `uuid`, `guid` | Valid UUID v4 |
+| ...and 60+ more patterns | |
+
+## Configuration
+
+`.seedforge.yaml` (auto-created by `seedforge connect`):
+
+```yaml
+db_url: postgresql://user:pass@localhost:5432/mydb
+default_rows: 100
+default_schema: public
+seed: 42  # optional, for deterministic generation
+exclude_tables:
+  - _prisma_migrations
+  - django_migrations
+```
+
+## Supported Databases
+
+- [x] PostgreSQL
+- [x] MySQL / MariaDB
+- [ ] SQLite (planned)
+
+## Data Privacy
+
+**Your data never leaves your machine.** SeedForge runs entirely locally — it connects directly to your database, generates data in memory, and inserts it. No cloud, no telemetry, no data collection.
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and PRs welcome at [github.com/silkhorizonstudios/seedforge](https://github.com/silkhorizonstudios/seedforge).

seedforge-0.1.0/README.md

@@ -0,0 +1,179 @@
+# SeedForge
+
+**One command to fill your database with realistic test data.**
+
+SeedForge connects to your database, reads the schema (tables, columns, foreign keys, constraints), and generates realistic, FK-valid data — no code, no config, no seed scripts.
+
+```bash
+pip install seedforge
+seedforge connect postgresql://user:pass@localhost/mydb
+seedforge generate --rows 1000
+# Done. 40 tables filled in 3 seconds.
+```
+
+## Features
+
+- **Zero-config** — reads your DB schema automatically, no setup needed
+- **FK integrity** — resolves foreign keys via topological sort, inserts in correct order
+- **Smart heuristics** — 80+ column name patterns for realistic data (`email` → real email, `price` → decimal, `role` → admin/user/editor)
+- **Deterministic** — use `--seed` to get the same data every time
+- **AI-powered** — optional Claude AI integration for maximum realism
+- **Export** — SQL or JSON file output
+- **Privacy-first** — runs entirely locally, your data never leaves your machine
+
+## Installation
+
+```bash
+pip install seedforge
+
+# With MySQL support
+pip install seedforge[mysql]
+
+# With AI support (Claude API)
+pip install seedforge[ai]
+
+# Everything
+pip install seedforge[all]
+```
+
+## Quick Start
+
+### 1. Connect
+
+```bash
+seedforge connect postgresql://user:pass@localhost:5432/mydb
+```
+
+Saves the connection to `.seedforge.yaml` so you don't have to type it again.
+
+### 2. Inspect
+
+```bash
+seedforge inspect
+```
+
+Shows all tables, columns, types, foreign keys, and insertion order:
+
+```
+Found 18 tables (insertion order):
+
+         1. users
+┏━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┓
+┃ Column     ┃ Type      ┃ Nullable ┃ FK →  ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━┩
+│ id         │ serial    │ NO       │       │
+│ email      │ varchar   │ NO       │       │
+│ name       │ varchar   │ YES      │       │
+└────────────┴───────────┴──────────┴───────┘
+
+             2. orders
+┏━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Column     ┃ Type      ┃ Nullable ┃ FK →       ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ id         │ serial    │ NO       │            │
+│ user_id    │ integer   │ NO       │ users.id   │
+│ total      │ numeric   │ NO       │            │
+└────────────┴───────────┴──────────┴────────────┘
+```
+
+### 3. Generate
+
+```bash
+# Generate and insert 100 rows per table
+seedforge generate --rows 100
+
+# Preview without inserting
+seedforge generate --rows 10 --dry-run
+
+# Export to SQL file
+seedforge generate --rows 1000 --export sql
+
+# Export to JSON
+seedforge generate --rows 1000 --export json
+
+# Deterministic (same data every time)
+seedforge generate --rows 100 --seed 42
+
+# Only specific tables (auto-includes FK parents)
+seedforge generate --tables orders,payments --rows 50
+
+# Clean tables before generating
+seedforge generate --rows 100 --clean
+```
+
+### 4. AI Generate (optional)
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+seedforge ai-generate --rows 20
+```
+
+Uses Claude AI to generate context-aware data with maximum realism.
+
+## How It Works
+
+1. **Schema introspection** — connects to your database, reads `information_schema` to get tables, columns, types, FK relationships, constraints, ENUMs
+2. **Dependency graph** — builds a directed graph from FK relationships, runs topological sort to determine insertion order (parents first)
+3. **Smart heuristics** — maps column names to appropriate generators (`email` → realistic email, `phone` → phone number, `created_at` → recent datetime)
+4. **FK resolution** — child rows automatically reference real IDs from already-generated parent rows
+5. **Batch insert** — fast bulk insertion with proper transaction handling
+
+## Column Name Heuristics
+
+SeedForge automatically detects what kind of data to generate based on column names:
+
+| Column name | Generated data |
+|---|---|
+| `email` | `john.smith@example.com` |
+| `phone`, `mobile` | `+1-555-0123` |
+| `first_name` | `John` |
+| `last_name` | `Smith` |
+| `username` | `jsmith42` |
+| `address`, `street` | `123 Main St, Apt 4` |
+| `city` | `San Francisco` |
+| `country` | `United States` |
+| `price`, `amount`, `total` | `49.99` |
+| `url`, `website` | `https://example.com` |
+| `avatar`, `image_url` | `https://picsum.photos/seed/123/400/300` |
+| `role` | `admin`, `user`, `moderator` |
+| `status` | `active`, `pending`, `completed` |
+| `plan` | `free`, `pro`, `enterprise` |
+| `created_at`, `updated_at` | Recent datetime |
+| `is_active`, `verified` | `true` (85% bias) |
+| `is_deleted`, `archived` | `false` (90% bias) |
+| `password` | SHA-256 hash |
+| `token`, `api_key` | Random hex string |
+| `uuid`, `guid` | Valid UUID v4 |
+| ...and 60+ more patterns | |
+
+## Configuration
+
+`.seedforge.yaml` (auto-created by `seedforge connect`):
+
+```yaml
+db_url: postgresql://user:pass@localhost:5432/mydb
+default_rows: 100
+default_schema: public
+seed: 42  # optional, for deterministic generation
+exclude_tables:
+  - _prisma_migrations
+  - django_migrations
+```
+
+## Supported Databases
+
+- [x] PostgreSQL
+- [x] MySQL / MariaDB
+- [ ] SQLite (planned)
+
+## Data Privacy
+
+**Your data never leaves your machine.** SeedForge runs entirely locally — it connects directly to your database, generates data in memory, and inserts it. No cloud, no telemetry, no data collection.
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and PRs welcome at [github.com/silkhorizonstudios/seedforge](https://github.com/silkhorizonstudios/seedforge).

seedforge-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seedforge"
+version = "0.1.0"
+description = "AI-powered test data generator that reads your database schema and fills it with realistic, FK-valid data in seconds"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "SilkHorizon", email = "hello@silkhorizon.uz"},
+]
+keywords = ["database", "testing", "faker", "seed", "synthetic-data", "postgresql"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "psycopg2-binary>=2.9.0",
+    "faker>=25.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+mysql = ["pymysql>=1.1.0"]
+ai = ["anthropic>=0.40.0"]
+all = ["pymysql>=1.1.0", "anthropic>=0.40.0"]
+
+[project.scripts]
+seedforge = "seedforge.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/silkhorizonstudios/seedforge"
+Documentation = "https://seedforge.dev"
+Repository = "https://github.com/silkhorizonstudios/seedforge"
+
+[tool.setuptools.packages.find]
+include = ["seedforge*"]

seedforge-0.1.0/seedforge/__init__.py

@@ -0,0 +1,3 @@
+"""SeedForge - AI-powered test data generator for databases."""
+
+__version__ = "0.1.0"

seedforge-0.1.0/seedforge/ai.py

@@ -0,0 +1,150 @@
+"""AI-слой: Claude анализирует схему и генерирует контекстно-зависимые данные.
+
+Используется как premium-фича. Отправляет только метаданные схемы (имена таблиц/колонок),
+НЕ реальные данные пользователя.
+"""
+
+import json
+import os
+
+
+def get_ai_generators(tables: dict, api_key: str | None = None) -> dict:
+    """Попросить Claude проанализировать схему и предложить генераторы.
+
+    Возвращает dict: {"table.column": {"generator": "...", "args": {...}}}
+    """
+    api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        return {}
+
+    # Собираем метаданные схемы (только имена, типы, связи — НЕ данные)
+    schema_desc = _build_schema_description(tables)
+
+    try:
+        import anthropic
+        client = anthropic.Anthropic(api_key=api_key)
+
+        response = client.messages.create(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=4096,
+            messages=[{
+                "role": "user",
+                "content": f"""Analyze this database schema and suggest realistic test data generators for each column.
+
+Schema:
+{schema_desc}
+
+For each column, suggest what kind of realistic data should be generated.
+Focus on columns where the name alone isn't enough to determine the right generator
+(e.g., "name" in an "organizations" table should be a company name, not a person name).
+
+Return a JSON object where keys are "table.column" and values have:
+- "generator": one of the Faker methods (e.g., "company", "name", "sentence") or a custom description
+- "example": an example value
+- "values": (optional) a list of realistic values to choose from (for status/type/role fields)
+
+Only include columns where your suggestion differs from the obvious default.
+Return ONLY valid JSON, no markdown, no explanation."""
+            }],
+        )
+
+        text = response.content[0].text.strip()
+        # Убираем markdown если есть
+        if text.startswith("```"):
+            text = text.split("\n", 1)[1]
+            text = text.rsplit("```", 1)[0]
+
+        return json.loads(text)
+
+    except ImportError:
+        return {}
+    except Exception:
+        return {}
+
+
+def generate_with_ai(
+    table_name: str,
+    columns: list[dict],
+    row_count: int,
+    api_key: str | None = None,
+    context: str = "",
+) -> list[dict] | None:
+    """Генерировать данные для таблицы через Claude.
+
+    Используется для небольших таблиц (до 50 строк) где нужна высокая реалистичность.
+    Для больших объёмов используем rule-based генерацию.
+    """
+    api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        return None
+
+    # Ограничиваем до 50 строк для AI-генерации (стоимость)
+    row_count = min(row_count, 50)
+
+    col_desc = ", ".join(
+        f"{c['name']} ({c['type']}{'?' if c.get('nullable') else ''})"
+        for c in columns
+    )
+
+    try:
+        import anthropic
+        client = anthropic.Anthropic(api_key=api_key)
+
+        prompt = f"""Generate {row_count} realistic rows for the "{table_name}" table.
+Columns: {col_desc}
+{f"Context: {context}" if context else ""}
+
+Requirements:
+- Data must be realistic and internally consistent
+- If column is a name in an organization table, use company names
+- If column is a status, use realistic statuses
+- Dates should be recent (within last 2 years)
+- Respect nullable columns (occasionally set to null)
+
+Return a JSON array of objects. Each object has column names as keys.
+Return ONLY valid JSON, no markdown, no explanation."""
+
+        response = client.messages.create(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=8192,
+            messages=[{"role": "user", "content": prompt}],
+        )
+
+        text = response.content[0].text.strip()
+        if text.startswith("```"):
+            text = text.split("\n", 1)[1]
+            text = text.rsplit("```", 1)[0]
+
+        return json.loads(text)
+
+    except ImportError:
+        return None
+    except Exception:
+        return None
+
+
+def _build_schema_description(tables: dict) -> str:
+    """Построить текстовое описание схемы для AI."""
+    lines = []
+    for table_name, table in tables.items():
+        cols = []
+        for col in table.columns:
+            parts = [f"{col.name} {col.data_type}"]
+            if col.is_primary:
+                parts.append("PK")
+            if col.fk_table:
+                parts.append(f"FK→{col.fk_table}.{col.fk_column}")
+            if not col.nullable:
+                parts.append("NOT NULL")
+            if col.is_unique:
+                parts.append("UNIQUE")
+            if col.enum_values:
+                parts.append(f"ENUM({', '.join(col.enum_values[:5])})")
+            cols.append(" ".join(parts))
+
+        lines.append(f"TABLE {table_name}:")
+        for c in cols:
+            lines.append(f"  - {c}")
+        lines.append("")
+
+    return "\n".join(lines)