fixtureforge 2.0.0__tar.gz → 2.0.2__tar.gz

fixtureforge-2.0.2/PKG-INFO

@@ -0,0 +1,427 @@
+Metadata-Version: 2.4
+Name: fixtureforge
+Version: 2.0.2
+Summary: Agentic Test Data Harness: memory, multi-agent swarms, permission gates, coverage analysis. Provider-agnostic (Gemini, OpenAI, Anthropic, Ollama).
+License: MIT
+License-File: LICENSE
+Keywords: testing,fixtures,test-data,qa,automation,synthetic-data,llm
+Author: Yaniv Metuku
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: all
+Provides-Extra: anthropic
+Provides-Extra: gemini
+Provides-Extra: openai
+Provides-Extra: sql
+Requires-Dist: anthropic (>=0.18.0,<0.19.0) ; extra == "anthropic" or extra == "all"
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: faker (>=22.0.0,<23.0.0)
+Requires-Dist: google-genai (>=1.0.0,<2.0.0) ; extra == "gemini" or extra == "all"
+Requires-Dist: openai (>=1.0.0,<2.0.0) ; extra == "openai" or extra == "all"
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: rich (>=13.7.0,<14.0.0)
+Requires-Dist: sqlalchemy (>=2.0.0,<3.0.0) ; extra == "sql" or extra == "all"
+Project-URL: Homepage, https://fixtureforge.dev
+Project-URL: Repository, https://github.com/Yaniv2809/fixtureforge
+Description-Content-Type: text/markdown
+
+# FixtureForge
+
+**Agentic Test Data Harness for Python.**  
+Generate realistic, context-aware fixtures — deterministic in CI, AI-powered in development.
+
+[![PyPI version](https://img.shields.io/pypi/v/fixtureforge.svg)](https://pypi.org/project/fixtureforge/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## The Problem
+
+```python
+# This is what most test data looks like:
+user = User(name="Test User", email="test@test.com", bio="Lorem ipsum...")
+
+# It doesn't catch real-world edge cases.
+# It doesn't feel like production data.
+# And writing 500 of them by hand? Not happening.
+```
+
+FixtureForge solves this in two modes:
+
+```python
+# CI mode — deterministic, zero AI, seed-controlled. Same seed = same data. Always.
+forge = Forge(use_ai=False, seed=42)
+users = forge.create_batch(User, count=500)
+
+# Dev mode — AI-generated, context-aware, realistic
+forge = Forge()
+reviews = forge.create_batch(Review, count=50, context="angry holiday customers")
+```
+
+---
+
+## Installation
+
+```bash
+pip install fixtureforge
+```
+
+With your preferred AI provider:
+
+```bash
+pip install "fixtureforge[anthropic]"   # Claude
+pip install "fixtureforge[openai]"      # GPT
+pip install "fixtureforge[gemini]"      # Google Gemini
+pip install "fixtureforge[all]"         # All providers
+```
+
+---
+
+## Quick Start
+
+```python
+from fixtureforge import Forge
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+    bio: str
+
+forge = Forge()  # auto-detects provider from env vars
+users = forge.create_batch(User, count=50, context="SaaS platform users")
+```
+
+That's it. FixtureForge:
+- Assigns sequential IDs automatically
+- Generates `name` and `email` with Faker (zero API cost)
+- Sends only `bio` to the AI — in a single batch call for all 50 records
+
+---
+
+## Core Concepts
+
+### Intelligent Field Routing
+
+Every field is classified into a tier. Only semantic fields hit the AI:
+
+| Tier | Fields | Generator | Cost |
+|------|--------|-----------|------|
+| **Structural** | `id`, `user_id`, `order_id` | Internal counters / FK registry | Free |
+| **Standard** | `name`, `email`, `phone`, `address`, `date` | Faker | Free |
+| **Computed** | `@computed_field` properties | Pydantic | Free |
+| **Semantic** | `bio`, `description`, `review`, `message` | LLM (batched) | API tokens |
+
+100 users with 2 semantic fields = **2 API calls**, not 200.
+
+### CI Mode vs Dev Mode
+
+```python
+# CI — fully deterministic, no network, reproducible
+forge = Forge(use_ai=False, seed=42)
+
+# Dev — AI-powered, realistic context
+forge = Forge(provider_name="anthropic", model="claude-haiku-4-5-20251001")
+
+# Large datasets — seed+interpolation, constant cost regardless of count
+forge.create_large(Order, count=100_000, seed_ratio=0.01)  # pays for ~1k, delivers 100k
+```
+
+### Verbose Mode
+
+See exactly where each value comes from:
+
+```python
+forge = Forge(use_ai=False, seed=42, verbose=True)
+user = forge.create(User)
+
+# [structural] id    = 1
+# [faker]      name  = 'Allison Hill'
+# [faker]      email = 'donaldgarcia@example.net'
+# [ai]         bio   = 'Passionate developer with 8 years...'
+```
+
+---
+
+## Providers
+
+FixtureForge auto-detects your provider from environment variables:
+
+```bash
+export ANTHROPIC_API_KEY=...   # → Claude (default: claude-haiku-4-5-20251001)
+export OPENAI_API_KEY=...      # → GPT    (default: gpt-4o-mini)
+export GOOGLE_API_KEY=...      # → Gemini (default: gemini-2.0-flash)
+export GROQ_API_KEY=...        # → Groq   (default: llama-3.3-70b-versatile)
+# No key? → Ollama (localhost:11434) → Deterministic-only
+```
+
+Or be explicit:
+
+```python
+forge = Forge(provider_name="anthropic", model="claude-sonnet-4-6")
+forge = Forge(provider_name="ollama", model="llama3.2")
+forge = Forge(use_ai=False)  # zero cost, zero network
+```
+
+---
+
+## Foreign Key Relationships
+
+Register parent records first — child FKs resolve automatically:
+
+```python
+# Step 1: generate customers
+customers = forge.create_batch(Customer, count=10)
+
+# Step 2: orders automatically reference real customer IDs
+orders = forge.create_batch(Order, count=100)
+# order.customer_id → always a valid customer.id
+```
+
+---
+
+## DataSwarms — Parallel Multi-Model Generation
+
+Generate multiple models in parallel with shared AI cache.  
+The first model warms the cache; every subsequent model inherits it (~90% cheaper per model).
+
+```python
+results = forge.swarm(
+    models=[User, Order, Product, Payment],
+    counts=[10,   50,    100,     30],
+    contexts=["SaaS users", "E-commerce orders", None, None],
+)
+
+# returns:
+# {
+#   "User":    [...10 users...],
+#   "Order":   [...50 orders...],
+#   "Product": [...100 products...],
+#   "Payment": [...30 payments...],
+# }
+```
+
+5 models ≈ cost of 1.5 models.
+
+---
+
+## Permission Gates
+
+FixtureForge classifies models by data sensitivity and gates dangerous operations:
+
+```python
+class SafeUser(BaseModel):
+    id: int
+    name: str          # SAFE — auto-approved
+
+class CustomerProfile(BaseModel):
+    id: int
+    ssn: str           # SENSITIVE — requires FORGE_ALLOW_PII=1
+    salary: float      # SENSITIVE
+
+class SecurityTest(BaseModel):
+    id: int
+    sql_injection: str # DANGEROUS — requires interactive confirmation
+```
+
+```python
+# PII auto-approved
+forge = Forge(allow_pii=True)
+
+# CI/headless — dangerous ops silently rejected
+forge = Forge(interactive=False)
+```
+
+Three levels: `safe` (auto) → `sensitive` (env gate) → `dangerous` (human prompt).
+
+---
+
+## Domain Rules — ForgeMemory
+
+Persist business rules that survive across sessions.  
+Rules are re-read on every generation call — update a rule, next call respects it immediately.
+
+```python
+forge.memory.add_rule("financial", "Users under 18 get restricted account type")
+forge.memory.add_rule("user", "Israeli phone numbers use format 05x-xxx-xxxx")
+forge.memory.add_rule("orders", "Max 3 active loans per customer at any time")
+
+# Rules inject into AI prompts automatically
+users = forge.create_batch(User, count=50, context="Israeli SaaS platform")
+```
+
+**Skeptical Memory** — rules are hints, not truth. FixtureForge validates stored rules against the live schema before every generation call.
+
+**Progressive Forgetting** — field names and types are never stored (re-derivable from the model). Only business rules that exist nowhere else in the code are kept.
+
+---
+
+## ForgeDream — Coverage Analysis
+
+Find gaps in your test-data coverage automatically:
+
+```python
+import os
+os.environ["FORGE_FLAG_DREAM"] = "1"
+
+report = forge.dream(models=[User, Order], force=True)
+print(report.summary())
+
+# ForgeDream Report - 2026-04-08
+#   Coverage gaps found  : 3
+#   Rule conflicts found : 0
+#   Top gaps:
+#     [User.age]   no_boundary : No boundary-value rules for numeric field 'age'
+#     [User.email] no_invalid  : No invalid-data rules for well-known field 'email'
+#     [Order.total] no_boundary: No boundary-value rules for numeric field 'total'
+```
+
+Four phases: **Orient** (read index) → **Gather** (find gaps) → **Consolidate** (merge rules) → **Prune** (trim to ≤200 lines).
+
+Report saved as `.forge/coverage_gaps.json`.
+
+---
+
+## Streaming — Memory-Safe Large Datasets
+
+```python
+# Lazy evaluation — writes to disk one record at a time
+for user in forge.create_stream(User, count=1_000_000, filename="users.json"):
+    pass  # process one record, never loads all into memory
+```
+
+Supports `.json`, `.csv`, `.sql` output formats.
+
+---
+
+## Export
+
+```python
+from fixtureforge.core.exporter import DataExporter
+
+users = forge.create_batch(User, count=100)
+DataExporter.to_json(users, "users.json")
+DataExporter.to_csv(users, "users.csv")
+DataExporter.to_sql(users, "users.sql", table_name="users")
+```
+
+---
+
+## Response Cache
+
+AI responses are cached locally for 7 days. Identical requests cost nothing after the first call.
+
+```python
+forge = Forge(use_cache=True)   # default — saves to ~/.fixtureforge/cache/
+forge = Forge(use_cache=False)  # disable caching
+```
+
+---
+
+## Feature Flags
+
+```python
+from fixtureforge.config import is_enabled, flag_summary
+
+flag_summary()
+# {
+#   'FORGE_SWARMS':      True,   # shipped
+#   'FORGE_PERMISSIONS': True,   # shipped
+#   'FORGE_COMPRESSION': True,   # shipped
+#   'FORGE_MCP':         True,   # shipped
+#   'FORGE_DREAM':       False,  # enable with FORGE_FLAG_DREAM=1
+#   'FORGE_KAIROS':      False,  # coming in v2.x
+#   'FORGE_ULTRAPLAN':   False,  # coming in v2.x
+# }
+```
+
+Enable any staged feature with an env var:
+
+```bash
+FORGE_FLAG_DREAM=1 python run_tests.py
+```
+
+---
+
+## Stats & Diagnostics
+
+```python
+forge.stats()
+# {
+#   "registry": {"user": 50, "order": 200},
+#   "session_tokens": 1240,
+#   "memory": {"topics": 3, "total_kb": 2.4},
+#   "flags": {"FORGE_SWARMS": True, "FORGE_PERMISSIONS": True}
+# }
+
+forge.clear_registry()  # reset FK registry between independent test scenarios
+```
+
+---
+
+## Architecture
+
+```
+FixtureForge v2.0
+├── Config Layer        feature flags, env-var overrides
+├── Security Layer      safe / sensitive / dangerous gates, mailbox pattern
+├── Memory Layer        FORGE.md pointer index, on-demand topic files
+├── Generation Layer    IntelligentRouter, SmartBatchEngine, DataSwarms
+├── Compression Layer   Micro → Auto → Full (three-layer pipeline)
+├── Export Layer        JSON / CSV / SQL / streaming
+└── Background Layer    ForgeDream coverage analysis (feature-flagged)
+```
+
+**Provider-agnostic**: Claude, GPT, Gemini, Groq, Ollama, or no AI at all.  
+**Pydantic v2 native**: full support for `@computed_field`, validators, and constrained types.  
+**CI-safe**: `seed=` parameter guarantees identical output across runs.
+
+---
+
+## Comparison
+
+| | FixtureForge | factory_boy | faker | hypothesis |
+|---|---|---|---|---|
+| AI-generated context | Yes | No | No | No |
+| Deterministic (seed=) | Yes | Yes | Yes | Yes |
+| FK relationships | Auto | Manual | No | No |
+| Coverage analysis | Yes | No | No | Partial |
+| CI-safe mode | Yes | Yes | Yes | Yes |
+| Large datasets | Yes (100k+) | Manual | Manual | No |
+| Permission gates | Yes | No | No | No |
+
+FixtureForge is not a replacement for `faker` — it uses `faker` internally. It's not a replacement for `hypothesis` — it solves a different problem. It adds the layer between "I need realistic data" and "I need it to feel like production".
+
+---
+
+## Requirements
+
+- Python 3.11+
+- pydantic >= 2.5
+- faker >= 22.0
+
+AI providers are optional extras — the core works with zero dependencies beyond pydantic and faker.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Links
+
+- **PyPI**: https://pypi.org/project/fixtureforge/
+- **Repository**: https://github.com/Yaniv2809/fixtureforge
+- **Issues**: https://github.com/Yaniv2809/fixtureforge/issues
+

fixtureforge-2.0.2/README.md

@@ -0,0 +1,392 @@
+# FixtureForge
+
+**Agentic Test Data Harness for Python.**  
+Generate realistic, context-aware fixtures — deterministic in CI, AI-powered in development.
+
+[![PyPI version](https://img.shields.io/pypi/v/fixtureforge.svg)](https://pypi.org/project/fixtureforge/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## The Problem
+
+```python
+# This is what most test data looks like:
+user = User(name="Test User", email="test@test.com", bio="Lorem ipsum...")
+
+# It doesn't catch real-world edge cases.
+# It doesn't feel like production data.
+# And writing 500 of them by hand? Not happening.
+```
+
+FixtureForge solves this in two modes:
+
+```python
+# CI mode — deterministic, zero AI, seed-controlled. Same seed = same data. Always.
+forge = Forge(use_ai=False, seed=42)
+users = forge.create_batch(User, count=500)
+
+# Dev mode — AI-generated, context-aware, realistic
+forge = Forge()
+reviews = forge.create_batch(Review, count=50, context="angry holiday customers")
+```
+
+---
+
+## Installation
+
+```bash
+pip install fixtureforge
+```
+
+With your preferred AI provider:
+
+```bash
+pip install "fixtureforge[anthropic]"   # Claude
+pip install "fixtureforge[openai]"      # GPT
+pip install "fixtureforge[gemini]"      # Google Gemini
+pip install "fixtureforge[all]"         # All providers
+```
+
+---
+
+## Quick Start
+
+```python
+from fixtureforge import Forge
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+    bio: str
+
+forge = Forge()  # auto-detects provider from env vars
+users = forge.create_batch(User, count=50, context="SaaS platform users")
+```
+
+That's it. FixtureForge:
+- Assigns sequential IDs automatically
+- Generates `name` and `email` with Faker (zero API cost)
+- Sends only `bio` to the AI — in a single batch call for all 50 records
+
+---
+
+## Core Concepts
+
+### Intelligent Field Routing
+
+Every field is classified into a tier. Only semantic fields hit the AI:
+
+| Tier | Fields | Generator | Cost |
+|------|--------|-----------|------|
+| **Structural** | `id`, `user_id`, `order_id` | Internal counters / FK registry | Free |
+| **Standard** | `name`, `email`, `phone`, `address`, `date` | Faker | Free |
+| **Computed** | `@computed_field` properties | Pydantic | Free |
+| **Semantic** | `bio`, `description`, `review`, `message` | LLM (batched) | API tokens |
+
+100 users with 2 semantic fields = **2 API calls**, not 200.
+
+### CI Mode vs Dev Mode
+
+```python
+# CI — fully deterministic, no network, reproducible
+forge = Forge(use_ai=False, seed=42)
+
+# Dev — AI-powered, realistic context
+forge = Forge(provider_name="anthropic", model="claude-haiku-4-5-20251001")
+
+# Large datasets — seed+interpolation, constant cost regardless of count
+forge.create_large(Order, count=100_000, seed_ratio=0.01)  # pays for ~1k, delivers 100k
+```
+
+### Verbose Mode
+
+See exactly where each value comes from:
+
+```python
+forge = Forge(use_ai=False, seed=42, verbose=True)
+user = forge.create(User)
+
+# [structural] id    = 1
+# [faker]      name  = 'Allison Hill'
+# [faker]      email = 'donaldgarcia@example.net'
+# [ai]         bio   = 'Passionate developer with 8 years...'
+```
+
+---
+
+## Providers
+
+FixtureForge auto-detects your provider from environment variables:
+
+```bash
+export ANTHROPIC_API_KEY=...   # → Claude (default: claude-haiku-4-5-20251001)
+export OPENAI_API_KEY=...      # → GPT    (default: gpt-4o-mini)
+export GOOGLE_API_KEY=...      # → Gemini (default: gemini-2.0-flash)
+export GROQ_API_KEY=...        # → Groq   (default: llama-3.3-70b-versatile)
+# No key? → Ollama (localhost:11434) → Deterministic-only
+```
+
+Or be explicit:
+
+```python
+forge = Forge(provider_name="anthropic", model="claude-sonnet-4-6")
+forge = Forge(provider_name="ollama", model="llama3.2")
+forge = Forge(use_ai=False)  # zero cost, zero network
+```
+
+---
+
+## Foreign Key Relationships
+
+Register parent records first — child FKs resolve automatically:
+
+```python
+# Step 1: generate customers
+customers = forge.create_batch(Customer, count=10)
+
+# Step 2: orders automatically reference real customer IDs
+orders = forge.create_batch(Order, count=100)
+# order.customer_id → always a valid customer.id
+```
+
+---
+
+## DataSwarms — Parallel Multi-Model Generation
+
+Generate multiple models in parallel with shared AI cache.  
+The first model warms the cache; every subsequent model inherits it (~90% cheaper per model).
+
+```python
+results = forge.swarm(
+    models=[User, Order, Product, Payment],
+    counts=[10,   50,    100,     30],
+    contexts=["SaaS users", "E-commerce orders", None, None],
+)
+
+# returns:
+# {
+#   "User":    [...10 users...],
+#   "Order":   [...50 orders...],
+#   "Product": [...100 products...],
+#   "Payment": [...30 payments...],
+# }
+```
+
+5 models ≈ cost of 1.5 models.
+
+---
+
+## Permission Gates
+
+FixtureForge classifies models by data sensitivity and gates dangerous operations:
+
+```python
+class SafeUser(BaseModel):
+    id: int
+    name: str          # SAFE — auto-approved
+
+class CustomerProfile(BaseModel):
+    id: int
+    ssn: str           # SENSITIVE — requires FORGE_ALLOW_PII=1
+    salary: float      # SENSITIVE
+
+class SecurityTest(BaseModel):
+    id: int
+    sql_injection: str # DANGEROUS — requires interactive confirmation
+```
+
+```python
+# PII auto-approved
+forge = Forge(allow_pii=True)
+
+# CI/headless — dangerous ops silently rejected
+forge = Forge(interactive=False)
+```
+
+Three levels: `safe` (auto) → `sensitive` (env gate) → `dangerous` (human prompt).
+
+---
+
+## Domain Rules — ForgeMemory
+
+Persist business rules that survive across sessions.  
+Rules are re-read on every generation call — update a rule, next call respects it immediately.
+
+```python
+forge.memory.add_rule("financial", "Users under 18 get restricted account type")
+forge.memory.add_rule("user", "Israeli phone numbers use format 05x-xxx-xxxx")
+forge.memory.add_rule("orders", "Max 3 active loans per customer at any time")
+
+# Rules inject into AI prompts automatically
+users = forge.create_batch(User, count=50, context="Israeli SaaS platform")
+```
+
+**Skeptical Memory** — rules are hints, not truth. FixtureForge validates stored rules against the live schema before every generation call.
+
+**Progressive Forgetting** — field names and types are never stored (re-derivable from the model). Only business rules that exist nowhere else in the code are kept.
+
+---
+
+## ForgeDream — Coverage Analysis
+
+Find gaps in your test-data coverage automatically:
+
+```python
+import os
+os.environ["FORGE_FLAG_DREAM"] = "1"
+
+report = forge.dream(models=[User, Order], force=True)
+print(report.summary())
+
+# ForgeDream Report - 2026-04-08
+#   Coverage gaps found  : 3
+#   Rule conflicts found : 0
+#   Top gaps:
+#     [User.age]   no_boundary : No boundary-value rules for numeric field 'age'
+#     [User.email] no_invalid  : No invalid-data rules for well-known field 'email'
+#     [Order.total] no_boundary: No boundary-value rules for numeric field 'total'
+```
+
+Four phases: **Orient** (read index) → **Gather** (find gaps) → **Consolidate** (merge rules) → **Prune** (trim to ≤200 lines).
+
+Report saved as `.forge/coverage_gaps.json`.
+
+---
+
+## Streaming — Memory-Safe Large Datasets
+
+```python
+# Lazy evaluation — writes to disk one record at a time
+for user in forge.create_stream(User, count=1_000_000, filename="users.json"):
+    pass  # process one record, never loads all into memory
+```
+
+Supports `.json`, `.csv`, `.sql` output formats.
+
+---
+
+## Export
+
+```python
+from fixtureforge.core.exporter import DataExporter
+
+users = forge.create_batch(User, count=100)
+DataExporter.to_json(users, "users.json")
+DataExporter.to_csv(users, "users.csv")
+DataExporter.to_sql(users, "users.sql", table_name="users")
+```
+
+---
+
+## Response Cache
+
+AI responses are cached locally for 7 days. Identical requests cost nothing after the first call.
+
+```python
+forge = Forge(use_cache=True)   # default — saves to ~/.fixtureforge/cache/
+forge = Forge(use_cache=False)  # disable caching
+```
+
+---
+
+## Feature Flags
+
+```python
+from fixtureforge.config import is_enabled, flag_summary
+
+flag_summary()
+# {
+#   'FORGE_SWARMS':      True,   # shipped
+#   'FORGE_PERMISSIONS': True,   # shipped
+#   'FORGE_COMPRESSION': True,   # shipped
+#   'FORGE_MCP':         True,   # shipped
+#   'FORGE_DREAM':       False,  # enable with FORGE_FLAG_DREAM=1
+#   'FORGE_KAIROS':      False,  # coming in v2.x
+#   'FORGE_ULTRAPLAN':   False,  # coming in v2.x
+# }
+```
+
+Enable any staged feature with an env var:
+
+```bash
+FORGE_FLAG_DREAM=1 python run_tests.py
+```
+
+---
+
+## Stats & Diagnostics
+
+```python
+forge.stats()
+# {
+#   "registry": {"user": 50, "order": 200},
+#   "session_tokens": 1240,
+#   "memory": {"topics": 3, "total_kb": 2.4},
+#   "flags": {"FORGE_SWARMS": True, "FORGE_PERMISSIONS": True}
+# }
+
+forge.clear_registry()  # reset FK registry between independent test scenarios
+```
+
+---
+
+## Architecture
+
+```
+FixtureForge v2.0
+├── Config Layer        feature flags, env-var overrides
+├── Security Layer      safe / sensitive / dangerous gates, mailbox pattern
+├── Memory Layer        FORGE.md pointer index, on-demand topic files
+├── Generation Layer    IntelligentRouter, SmartBatchEngine, DataSwarms
+├── Compression Layer   Micro → Auto → Full (three-layer pipeline)
+├── Export Layer        JSON / CSV / SQL / streaming
+└── Background Layer    ForgeDream coverage analysis (feature-flagged)
+```
+
+**Provider-agnostic**: Claude, GPT, Gemini, Groq, Ollama, or no AI at all.  
+**Pydantic v2 native**: full support for `@computed_field`, validators, and constrained types.  
+**CI-safe**: `seed=` parameter guarantees identical output across runs.
+
+---
+
+## Comparison
+
+| | FixtureForge | factory_boy | faker | hypothesis |
+|---|---|---|---|---|
+| AI-generated context | Yes | No | No | No |
+| Deterministic (seed=) | Yes | Yes | Yes | Yes |
+| FK relationships | Auto | Manual | No | No |
+| Coverage analysis | Yes | No | No | Partial |
+| CI-safe mode | Yes | Yes | Yes | Yes |
+| Large datasets | Yes (100k+) | Manual | Manual | No |
+| Permission gates | Yes | No | No | No |
+
+FixtureForge is not a replacement for `faker` — it uses `faker` internally. It's not a replacement for `hypothesis` — it solves a different problem. It adds the layer between "I need realistic data" and "I need it to feel like production".
+
+---
+
+## Requirements
+
+- Python 3.11+
+- pydantic >= 2.5
+- faker >= 22.0
+
+AI providers are optional extras — the core works with zero dependencies beyond pydantic and faker.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Links
+
+- **PyPI**: https://pypi.org/project/fixtureforge/
+- **Repository**: https://github.com/Yaniv2809/fixtureforge
+- **Issues**: https://github.com/Yaniv2809/fixtureforge/issues

{fixtureforge-2.0.0 → fixtureforge-2.0.2}/pyproject.toml

@@ -1,78 +1,78 @@
-[tool.poetry]
-name = "fixtureforge"
-version = "2.0.0"
-description = "Agentic Test Data Harness: memory, multi-agent swarms, permission gates, coverage analysis. Provider-agnostic (Gemini, OpenAI, Anthropic, Ollama)."
-authors = ["Yaniv Metuku"]
-license = "MIT"
-readme = "README.md"
-homepage = "https://fixtureforge.dev"
-repository = "https://github.com/Yaniv2809/fixtureforge"
-keywords = ["testing", "fixtures", "test-data", "qa", "automation", "synthetic-data", "llm"]
-
-# ---------------------------------------------------------------------------
-# Core dependencies — always installed, no AI required
-# ---------------------------------------------------------------------------
-[tool.poetry.dependencies]
-python    = "^3.11"
-pydantic  = "^2.5.0"
-faker     = "^22.0.0"
-pyyaml    = "^6.0"
-click     = "^8.1.0"
-rich      = "^13.7.0"
-requests  = "^2.31.0"    # used by OllamaProvider + general HTTP
-
-# SQLAlchemy is optional but common enough to keep as a soft dependency
-sqlalchemy = { version = "^2.0.0", optional = true }
-
-# ---------------------------------------------------------------------------
-# AI provider extras  — install only what you need
-#
-#   pip install fixtureforge[gemini]       → Google Gemini
-#   pip install fixtureforge[openai]       → OpenAI / Azure OpenAI
-#   pip install fixtureforge[anthropic]    → Anthropic Claude
-#   pip install fixtureforge[all]          → all cloud providers
-#
-#   Ollama (local) needs no extra pip package — just run Ollama locally.
-# ---------------------------------------------------------------------------
-google-genai = { version = "^1.0.0",  optional = true }
-openai       = { version = "^1.0.0",  optional = true }
-anthropic    = { version = "^0.18.0", optional = true }
-
-[tool.poetry.extras]
-gemini    = ["google-genai"]
-openai    = ["openai"]
-anthropic = ["anthropic"]
-sql       = ["sqlalchemy"]
-all       = ["google-genai", "openai", "anthropic", "sqlalchemy"]
-
-# ---------------------------------------------------------------------------
-# Development dependencies
-# ---------------------------------------------------------------------------
-[tool.poetry.group.dev.dependencies]
-pytest          = "^7.4.0"
-pytest-asyncio  = "^0.23.0"
-pytest-cov      = "^4.1.0"
-black           = "^23.12.0"
-ruff            = "^0.1.9"
-mypy            = "^1.8.0"
-
-# ---------------------------------------------------------------------------
-# CLI entry point
-# ---------------------------------------------------------------------------
-[tool.poetry.scripts]
-forge = "fixtureforge.cli.commands:cli"
-
-[build-system]
-requires      = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
-
-# ---------------------------------------------------------------------------
-# Ruff (linting) config
-# ---------------------------------------------------------------------------
-[tool.ruff]
-line-length = 100
-target-version = "py311"
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP"]
-ignore = ["E501"]
+[tool.poetry]
+name = "fixtureforge"
+version = "2.0.2"
+description = "Agentic Test Data Harness: memory, multi-agent swarms, permission gates, coverage analysis. Provider-agnostic (Gemini, OpenAI, Anthropic, Ollama)."
+authors = ["Yaniv Metuku"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://fixtureforge.dev"
+repository = "https://github.com/Yaniv2809/fixtureforge"
+keywords = ["testing", "fixtures", "test-data", "qa", "automation", "synthetic-data", "llm"]
+
+# ---------------------------------------------------------------------------
+# Core dependencies — always installed, no AI required
+# ---------------------------------------------------------------------------
+[tool.poetry.dependencies]
+python    = "^3.11"
+pydantic  = "^2.5.0"
+faker     = "^22.0.0"
+pyyaml    = "^6.0"
+click     = "^8.1.0"
+rich      = "^13.7.0"
+requests  = "^2.31.0"    # used by OllamaProvider + general HTTP
+
+# SQLAlchemy is optional but common enough to keep as a soft dependency
+sqlalchemy = { version = "^2.0.0", optional = true }
+
+# ---------------------------------------------------------------------------
+# AI provider extras  — install only what you need
+#
+#   pip install fixtureforge[gemini]       → Google Gemini
+#   pip install fixtureforge[openai]       → OpenAI / Azure OpenAI
+#   pip install fixtureforge[anthropic]    → Anthropic Claude
+#   pip install fixtureforge[all]          → all cloud providers
+#
+#   Ollama (local) needs no extra pip package — just run Ollama locally.
+# ---------------------------------------------------------------------------
+google-genai = { version = "^1.0.0",  optional = true }
+openai       = { version = "^1.0.0",  optional = true }
+anthropic    = { version = "^0.18.0", optional = true }
+
+[tool.poetry.extras]
+gemini    = ["google-genai"]
+openai    = ["openai"]
+anthropic = ["anthropic"]
+sql       = ["sqlalchemy"]
+all       = ["google-genai", "openai", "anthropic", "sqlalchemy"]
+
+# ---------------------------------------------------------------------------
+# Development dependencies
+# ---------------------------------------------------------------------------
+[tool.poetry.group.dev.dependencies]
+pytest          = "^7.4.0"
+pytest-asyncio  = "^0.23.0"
+pytest-cov      = "^4.1.0"
+black           = "^23.12.0"
+ruff            = "^0.1.9"
+mypy            = "^1.8.0"
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+[tool.poetry.scripts]
+forge = "fixtureforge.cli.commands:cli"
+
+[build-system]
+requires      = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+# ---------------------------------------------------------------------------
+# Ruff (linting) config
+# ---------------------------------------------------------------------------
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+ignore = ["E501"]

{fixtureforge-2.0.0 → fixtureforge-2.0.2}/src/fixtureforge/__init__.py

@@ -59,7 +59,7 @@ from .security.permissions import (
     ForgeCoordinator,
 )
 
-__version__ = "2.0.0"
+__version__ = "2.0.2"
 
 T = TypeVar("T", bound=BaseModel)
 
@@ -103,6 +103,8 @@ class Forge:
         use_ai: bool = True,
         use_cache: bool = True,
         locale: str = "en_US",
+        seed: Optional[int] = None,
+        verbose: bool = False,
         allow_pii: Optional[bool] = None,
         interactive: bool = True,
         memory_dir: Optional[Path] = None,
@@ -124,15 +126,22 @@ class Forge:
                         **provider_kwargs,
                     )
                 except Exception as exc:
-                    print(f"⚠️  Could not initialise AI provider: {exc}")
+                    print(f"Warning: Could not initialise AI provider: {exc}")
                     print("   Running in deterministic-only mode.")
                     resolved_provider = None
 
         self._provider = resolved_provider
+        self._seed = seed
+        self._verbose = verbose
 
         # ── Core generation stack ────────────────────────────────────────
         self.ai_engine = AIEngine(provider=resolved_provider, use_cache=use_cache)
-        self.generator = BasicGenerator(locale=locale, ai_engine=self.ai_engine)
+        self.generator = BasicGenerator(
+            locale=locale,
+            ai_engine=self.ai_engine,
+            seed=seed,
+            verbose=verbose,
+        )
         self.batch_engine = SmartBatchEngine(
             generator=self.generator, ai_engine=self.ai_engine
         )
@@ -197,8 +206,10 @@ class Forge:
         domain_rules = self.memory.get_rules_for_prompt(model_name=model.__name__)
 
         for i in range(count):
-            if count > 1:
+            if count > 1 and not self._verbose:
                 print(f"   ...generating {i + 1}/{count}...")
+            if self._verbose and count > 1:
+                print(f"\n  --- record {i + 1}/{count} ---")
             item = self.generator.generate(model, context=context, **overrides)
             self._register(model, item)
             results.append(item)

{fixtureforge-2.0.0 → fixtureforge-2.0.2}/src/fixtureforge/core/batch_engine.py

@@ -29,6 +29,10 @@ class SmartBatchEngine:
         self.ai_engine = ai_engine
         self.router = IntelligentRouter()
 
+    @property
+    def verbose(self) -> bool:
+        return self.generator.verbose
+
     def generate_many(
         self,
         model: Type,
@@ -51,13 +55,18 @@ class SmartBatchEngine:
         # Each call returns a list[str] of length `count`.
         semantic_pools: Dict[str, List[str]] = {}
         for field in semantic:
-            print(f"   🧠 Generating {count} values for '{field.name}' via AI...")
+            print(f"   [ai] Generating {count} values for '{field.name}'...")
             semantic_pools[field.name] = self.ai_engine.generate_semantic_batch(
                 field_name=field.name,
                 context=context or "",
                 count=count,
             )
 
+        if self.verbose and structural:
+            print(f"   [structural] fields: {[f.name for f in structural]}")
+        if self.verbose and standard:
+            print(f"   [faker]      fields: {[f.name for f in standard]}")
+
         # --- Step 2: assemble N instances ---
         results: List[Any] = []
         for i in range(count):

{fixtureforge-2.0.0 → fixtureforge-2.0.2}/src/fixtureforge/core/generator.py

@@ -26,6 +26,8 @@ class BasicGenerator:
         self,
         locale: str = "en_US",
         ai_engine: Optional[AIEngine] = None,
+        seed: Optional[int] = None,
+        verbose: bool = False,
         # Legacy: accept api_key for backwards compatibility
         api_key: Optional[str] = None,
     ):
@@ -33,6 +35,11 @@ class BasicGenerator:
         self.router = IntelligentRouter()
         self._id_counters: Dict[str, int] = {}
         self.registry: Dict[str, List[Any]] = {}
+        self.verbose = verbose
+
+        if seed is not None:
+            Faker.seed(seed)
+            random.seed(seed)
 
         if ai_engine is not None:
             self.ai_engine = ai_engine
@@ -72,15 +79,26 @@ class BasicGenerator:
         tier = self.router.classify(field)
 
         if tier == FieldTier.STRUCTURAL:
-            return self._generate_structural(field)
+            val = self._generate_structural(field)
+            if self.verbose:
+                print(f"  [structural] {field.name} = {val!r}")
+            return val
 
         if tier == FieldTier.COMPUTED:
-            return _SKIP  # Pydantic computes this automatically
+            if self.verbose:
+                print(f"  [computed]   {field.name} = <pydantic>")
+            return _SKIP
 
         if tier == FieldTier.SEMANTIC:
-            return self._generate_semantic_content(field, context)
+            val = self._generate_semantic_content(field, context)
+            if self.verbose:
+                print(f"  [ai]         {field.name} = {str(val)[:80]!r}")
+            return val
 
-        return self._generate_standard(field)
+        val = self._generate_standard(field)
+        if self.verbose:
+            print(f"  [faker]      {field.name} = {val!r}")
+        return val
 
     # ------------------------------------------------------------------
     # Structural (IDs / FKs)

fixtureforge-2.0.0/PKG-INFO

@@ -1,50 +0,0 @@
-Metadata-Version: 2.4
-Name: fixtureforge
-Version: 2.0.0
-Summary: Agentic Test Data Harness: memory, multi-agent swarms, permission gates, coverage analysis. Provider-agnostic (Gemini, OpenAI, Anthropic, Ollama).
-License: MIT
-License-File: LICENSE
-Keywords: testing,fixtures,test-data,qa,automation,synthetic-data,llm
-Author: Yaniv Metuku
-Requires-Python: >=3.11,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Provides-Extra: all
-Provides-Extra: anthropic
-Provides-Extra: gemini
-Provides-Extra: openai
-Provides-Extra: sql
-Requires-Dist: anthropic (>=0.18.0,<0.19.0) ; extra == "anthropic" or extra == "all"
-Requires-Dist: click (>=8.1.0,<9.0.0)
-Requires-Dist: faker (>=22.0.0,<23.0.0)
-Requires-Dist: google-genai (>=1.0.0,<2.0.0) ; extra == "gemini" or extra == "all"
-Requires-Dist: openai (>=1.0.0,<2.0.0) ; extra == "openai" or extra == "all"
-Requires-Dist: pydantic (>=2.5.0,<3.0.0)
-Requires-Dist: pyyaml (>=6.0,<7.0)
-Requires-Dist: requests (>=2.31.0,<3.0.0)
-Requires-Dist: rich (>=13.7.0,<14.0.0)
-Requires-Dist: sqlalchemy (>=2.0.0,<3.0.0) ; extra == "sql" or extra == "all"
-Project-URL: Homepage, https://fixtureforge.dev
-Project-URL: Repository, https://github.com/Yaniv2809/fixtureforge
-Description-Content-Type: text/markdown
-
-# FixtureForge 🛠️
-
-**Generate realistic, AI-powered test data using Google Gemini.**
-Stop using "Lorem Ipsum" or "Test User 1". Generate context-aware data for your QA & Development environments.
-
-## 🚀 Features
-
-* **Context-Aware:** Generate "Angry Customers" or "High-Value Orders" using AI.
-* **Structured Output:** Exports directly to SQL, JSON, or CSV.
-* **Lazy Streaming:** Can generate massive datasets (1GB+) without crashing memory.
-* **Smart Relationships:** Automatically links Orders to Customers.
-
-## 📦 Installation
-
-```bash
-pip install fixtureforge

fixtureforge-2.0.0/README.md

@@ -1,16 +0,0 @@
-# FixtureForge 🛠️
-
-**Generate realistic, AI-powered test data using Google Gemini.**
-Stop using "Lorem Ipsum" or "Test User 1". Generate context-aware data for your QA & Development environments.
-
-## 🚀 Features
-
-* **Context-Aware:** Generate "Angry Customers" or "High-Value Orders" using AI.
-* **Structured Output:** Exports directly to SQL, JSON, or CSV.
-* **Lazy Streaming:** Can generate massive datasets (1GB+) without crashing memory.
-* **Smart Relationships:** Automatically links Orders to Customers.
-
-## 📦 Installation
-
-```bash
-pip install fixtureforge