fixtureforge 0.1.0__tar.gz

fixtureforge-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+`LICENSE`
+```text
+MIT License
+
+Copyright (c) 2026 Yaniv
+
+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.

fixtureforge-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: fixtureforge
+Version: 0.1.0
+Summary: AI-powered realistic test data generation
+License: MIT
+License-File: LICENSE
+Keywords: testing,fixtures,test-data,qa,automation
+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
+Requires-Dist: anthropic (>=0.18.0,<0.19.0)
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: faker (>=22.0.0,<23.0.0)
+Requires-Dist: google-genai (>=1.62.0,<2.0.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.5.0,<3.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Requires-Dist: rich (>=13.7.0,<14.0.0)
+Requires-Dist: sqlalchemy (>=2.0.0,<3.0.0)
+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-0.1.0/README.md

@@ -0,0 +1,16 @@
+# 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-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[tool.poetry]
+name = "fixtureforge"
+version = "0.1.0"
+description = "AI-powered realistic test data generation"
+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"]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pydantic = "^2.5.0"
+sqlalchemy = "^2.0.0"
+anthropic = "^0.18.0"
+faker = "^22.0.0"
+click = "^8.1.0"
+rich = "^13.7.0"
+httpx = "^0.28.1"
+pyyaml = "^6.0"
+google-genai = "^1.62.0"
+
+[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"
+
+[tool.poetry.scripts]
+forge = "fixtureforge.cli.commands:cli"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

fixtureforge-0.1.0/src/fixtureforge/__init__.py

@@ -0,0 +1,70 @@
+from typing import Type, Any, List, Optional, Generator
+import os
+from .core.generator import BasicGenerator
+from .core.streamer import DataStreamer
+
+__version__ = "0.1.0"
+
+class Forge:
+    def __init__(self, api_key: Optional[str] = None, use_ai: bool = True, locale: str = "en_US"):
+        self.use_ai = use_ai
+        key = api_key or os.getenv("GOOGLE_API_KEY")
+        self.generator = BasicGenerator(locale=locale, api_key=key)
+
+    def create(self, model: Type, count: int = 1, context: str = None, **overrides) -> Any:
+        """Standard creation (In-Memory). Good for small batches."""
+        results = []
+        if count == 1:
+            item = self.generator.generate(model, context=context, **overrides)
+            self._add_to_registry(model, item)
+            return item
+        
+        for i in range(count):
+            print(f"   ...generating {i+1}/{count}...") 
+            item = self.generator.generate(model, context=context, **overrides)
+            self._add_to_registry(model, item)
+            results.append(item)
+            
+        return results
+
+    def create_stream(self, model: Type, count: int, filename: str, context: str = None, **overrides) -> Generator[Any, None, None]:
+        """
+        Lazy Evaluation: Generates data and writes immediately to disk.
+        Prevents Memory Explosion for large datasets.
+        """
+        streamer = DataStreamer(filename)
+        streamer.start()
+        
+        print(f"🌊 Starting stream to {filename} ({count} items)...")
+        
+        for i in range(count):
+            # 1. Generate
+            item = self.generator.generate(model, context=context, **overrides)
+            
+            # 2. Write to Disk (Immediately!)
+            streamer.write(item)
+            
+            # 3. Register (Optional - needed if this model is a parent for others)
+            self._add_to_registry(model, item)
+            
+            # 4. Yield for real-time consumption (if needed)
+            yield item
+
+        streamer.close()
+        print(f"✅ Stream complete! Data saved to {filename}")
+
+    def _add_to_registry(self, model: Type, item: Any):
+        """Helper to register items for relationships"""
+        model_name = model.__name__.lower()
+        if model_name not in self.generator.registry:
+            self.generator.registry[model_name] = []
+        self.generator.registry[model_name].append(item)
+
+    def create_batch(self, model: Type, count: int, context: str = None, **overrides) -> List[Any]:
+        return self.create(model, count=count, context=context, **overrides)
+    
+    def stats(self):
+        return {k: len(v) for k, v in self.generator.registry.items()}
+
+# Global instance
+forge = Forge()

fixtureforge-0.1.0/src/fixtureforge/ai/__init__.py

@@ -0,0 +1,10 @@
+"""
+AI-powered generation
+"""
+from .engine import AIEngine
+from .cache import ResponseCache
+
+__all__ = [
+    "AIEngine",
+    "ResponseCache",
+]

fixtureforge-0.1.0/src/fixtureforge/ai/cache.py

@@ -0,0 +1,86 @@
+"""
+Cache AI responses to save costs and speed
+"""
+import hashlib
+import json
+# import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+from datetime import datetime, timedelta
+
+
+class ResponseCache:
+    """Cache AI responses locally"""
+    
+    def __init__(self, cache_dir: Optional[str] = None):
+        if cache_dir:
+            self.cache_dir = Path(cache_dir)
+        else:
+            # Default: ~/.fixtureforge/cache
+            self.cache_dir = Path.home() / ".fixtureforge" / "cache"
+        
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.ttl = timedelta(days=7)  # Cache for 7 days
+    
+    def _hash_key(self, model_name: str, context: str, overrides: Dict) -> str:
+        """Generate cache key"""
+        key_data = {
+            "model": model_name,
+            "context": context,
+            "overrides": overrides
+        }
+        key_str = json.dumps(key_data, sort_keys=True)
+        return hashlib.sha256(key_str.encode()).hexdigest()
+    
+    def get(
+        self,
+        model_name: str,
+        context: Optional[str],
+        overrides: Dict[str, Any]
+    ) -> Optional[Any]:
+        """Get from cache"""
+        key = self._hash_key(model_name, context or "", overrides)
+        cache_file = self.cache_dir / f"{key}.json"
+        
+        if not cache_file.exists():
+            return None
+        
+        # Check if expired
+        mod_time = datetime.fromtimestamp(cache_file.stat().st_mtime)
+        if datetime.now() - mod_time > self.ttl:
+            cache_file.unlink()  # Delete expired
+            return None
+        
+        # Load
+        with open(cache_file, 'r') as f:
+            return json.load(f)
+    
+    def set(
+        self,
+        model_name: str,
+        context: Optional[str],
+        overrides: Dict[str, Any],
+        data: Any
+    ):
+        """Save to cache"""
+        key = self._hash_key(model_name, context or "", overrides)
+        cache_file = self.cache_dir / f"{key}.json"
+        
+        with open(cache_file, 'w') as f:
+            json.dump(data, f, indent=2, default=str)
+    
+    def clear(self):
+        """Clear all cache"""
+        for cache_file in self.cache_dir.glob("*.json"):
+            cache_file.unlink()
+    
+    def stats(self) -> Dict[str, Any]:
+        """Get cache statistics"""
+        files = list(self.cache_dir.glob("*.json"))
+        total_size = sum(f.stat().st_size for f in files)
+        
+        return {
+            "entries": len(files),
+            "size_mb": round(total_size / 1024 / 1024, 2),
+            "location": str(self.cache_dir)
+        }

fixtureforge-0.1.0/src/fixtureforge/ai/engine.py

@@ -0,0 +1,44 @@
+import os
+import time
+from typing import Optional
+from google import genai
+
+
+class AIEngine:
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.getenv("GOOGLE_API_KEY")
+        self.client = None
+        
+        if not self.api_key:
+            return
+
+        try:
+            self.client = genai.Client(api_key=self.api_key)
+        except Exception as e:
+            print(f"⚠️ AI Config Error: {e}")
+
+    def generate_text(self, prompt: str, retries: int = 5) -> str:
+        if not self.api_key or not self.client:
+            return "[AI Error: Missing API Key]"
+
+        attempt = 0
+        while attempt < retries:
+            try:
+                # הקריאה החדשה והרשמית
+                response = self.client.models.generate_content(
+                    model='gemini-2.0-flash', 
+                    contents=prompt
+                )
+                return response.text.strip()
+            
+            except Exception as e:
+                error_msg = str(e)
+                if "429" in error_msg or "quota" in error_msg.lower() or "503" in error_msg or "400" in error_msg: 
+                    wait_time = 10 * (attempt + 1)
+                    print(f"⏳ Server busy (Quota). Waiting {wait_time}s... (Attempt {attempt + 1}/{retries})")
+                    time.sleep(wait_time)
+                    attempt += 1
+                else:
+                    return f"[AI Error: {error_msg}]"
+        
+        return "[AI Error: Timeout - Failed after retries]"

fixtureforge-0.1.0/src/fixtureforge/ai/prompts.py

@@ -0,0 +1,31 @@
+"""
+System Prompts for the AI Engine.
+Defines how the AI should behave and format data.
+"""
+
+SYSTEM_PROMPT = """
+You are FixtureForge, an advanced test data generator.
+Your goal is to generate realistic, context-aware synthetic data for developers and QA engineers.
+
+RULES:
+1. OUTPUT FORMAT: You must output ONLY valid JSON. No Markdown, no explanations, no code blocks (```json).
+2. REALISM: Data must look real (names, addresses, emails). Use the requested locale if specified.
+3. CONSISTENCY: If generating multiple fields, they must match (e.g., email should match the name).
+4. CONTEXT: Pay attention to the user's specific scenario (e.g., "Angry customer", "Medical patient").
+5. ARRAY ONLY: The output must always be a JSON array of objects, even if requesting 1 item.
+"""
+
+def build_prompt(model_schema: dict, count: int, context: str = "") -> str:
+    """Builds the final prompt for the AI"""
+    return f"""
+    {SYSTEM_PROMPT}
+
+    REQUEST:
+    Generate {count} items based on this schema:
+    {model_schema}
+
+    CONTEXT/SCENARIO:
+    {context if context else "General realistic data"}
+
+    Remember: Output strictly a JSON list of objects.
+    """

fixtureforge-0.1.0/src/fixtureforge/cli/__init__.py

@@ -0,0 +1,6 @@
+"""
+CLI interface
+"""
+from .commands import cli
+
+__all__ = ["cli"]

fixtureforge-0.1.0/src/fixtureforge/cli/commands.py

@@ -0,0 +1,90 @@
+"""CLI interface for FixtureForge"""
+import click
+import sys
+import importlib.util
+from pathlib import Path
+from rich.console import Console
+from rich.table import Table
+from fixtureforge import Forge
+from fixtureforge.core.exporter import DataExporter
+
+console = Console()
+
+@click.group()
+def cli():
+    """FixtureForge - AI-powered test data generation"""
+    pass
+
+@cli.command()
+@click.argument('model_path')
+@click.option('--count', '-n', default=1, help='Number of instances')
+@click.option('--no-ai', is_flag=True, default=False, help='Disable AI features')
+@click.option('--output', '-o', help='Output file (e.g., data.json)')
+@click.option('--context', '-c', help='Context for AI generation (Director Mode)')
+def generate(model_path, count, no_ai, output, context):
+    """
+    Generate test data.
+    """
+    try:
+        console.print(f"[bold blue]🔮 Loading model: {model_path}[/bold blue]")
+        model_class = load_model_from_string(model_path)
+        
+        forge = Forge(use_ai=not no_ai)
+        
+        if context:
+             console.print(f"[bold yellow]🎬 Director Mode: {context}[/bold yellow]")
+
+        console.print(f"[bold blue]📦 Generating {count} instances...[/bold blue]")
+        
+        instances = forge.create_batch(model_class, count=count, context=context)
+        
+        display_table(instances)
+
+        if output:
+            console.print(f"[yellow]💾 Saving to {output}...[/yellow]")
+            DataExporter.export(instances, output)
+        
+    except Exception as e:
+        console.print(f"[bold red]❌ Error:[/bold red] {e}")
+        sys.exit(1)
+
+def load_model_from_string(model_path: str):
+    try:
+        module_name, class_name = model_path.split(":")
+    except ValueError:
+        raise ValueError("Model path must be in format 'filename:ClassName'")
+    
+    sys.path.append(str(Path.cwd()))
+    
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        spec = importlib.util.spec_from_file_location(module_name, f"{module_name}.py")
+        if spec and spec.loader:
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+        else:
+            raise ImportError(f"Could not find module '{module_name}'")
+
+    if not hasattr(module, class_name):
+        raise AttributeError(f"Class '{class_name}' not found in {module_name}")
+        
+    return getattr(module, class_name)
+
+def display_table(instances):
+    if not instances:
+        return
+        
+    first_item = instances[0]
+    headers = first_item.model_dump().keys()
+    
+    table = Table(show_header=True, header_style="bold magenta")
+
+    for h in headers:
+        table.add_column(h)
+        
+    for item in instances:
+        row = [str(getattr(item, h)) for h in headers]
+        table.add_row(*row)
+        
+    console.print(table)

fixtureforge-0.1.0/src/fixtureforge/core/__init__.py

@@ -0,0 +1,11 @@
+"""
+Core functionality for FixtureForge
+"""
+from .parser import ModelParser, FieldInfo
+from .generator import BasicGenerator
+
+__all__ = [
+    "ModelParser",
+    "FieldInfo",
+    "BasicGenerator",
+]

fixtureforge-0.1.0/src/fixtureforge/core/exporter.py

@@ -0,0 +1,96 @@
+import json
+import csv
+from pathlib import Path
+from typing import List, Any
+from pydantic import BaseModel
+from datetime import date, datetime
+
+class DataExporter:
+    """Handles exporting generated data to files (JSON, CSV, SQL)"""
+
+    @staticmethod
+    def export(data: List[Any], filename: str):
+        """Export data based on file extension"""
+        path = Path(filename)
+        extension = path.suffix.lower()
+
+        if extension == ".json":
+            DataExporter._to_json(data, path)
+        elif extension == ".csv":
+            DataExporter._to_csv(data, path)
+        elif extension == ".sql":
+            DataExporter._to_sql(data, path)
+        else:
+            raise ValueError(f"Unsupported format: {extension}")
+
+    @staticmethod
+    def _to_json(data: List[Any], path: Path):
+        """Save as JSON"""
+        json_ready = [
+            item.model_dump() if isinstance(item, BaseModel) else item.__dict__
+            for item in data
+        ]
+        
+        # המרה של תאריכים למחרוזות כדי ש-JSON לא ייכשל
+        json_ready = json.loads(json.dumps(json_ready, default=str))
+
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(json_ready, f, indent=2)
+        
+        print(f"✅ Successfully exported {len(data)} items to {path}")
+
+    @staticmethod
+    def _to_csv(data: List[Any], path: Path):
+        """Save as CSV"""
+        if not data:
+            return
+
+        first_item = data[0]
+        if isinstance(first_item, BaseModel):
+            headers = first_item.model_dump().keys()
+            rows = [item.model_dump() for item in data]
+        else:
+            headers = first_item.__dict__.keys()
+            rows = [item.__dict__ for item in data]
+
+        with open(path, "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=headers)
+            writer.writeheader()
+            writer.writerows(rows)
+            
+        print(f"✅ Successfully exported {len(data)} items to {path}")
+
+    @staticmethod
+    def _to_sql(data: List[Any], path: Path):
+        """Save as SQL INSERT statements"""
+        if not data:
+            return
+
+        table_name = data[0].__class__.__name__.lower() + "s" # Customer -> customers
+        
+        with open(path, "w", encoding="utf-8") as f:
+            f.write("-- Auto-generated by FixtureForge\n")
+            f.write(f"-- Target Table: {table_name}\n\n")
+
+            for item in data:
+                # המרה למילון
+                record = item.model_dump() if isinstance(item, BaseModel) else item.__dict__
+                
+                columns = ", ".join(record.keys())
+                values = []
+                
+                for v in record.values():
+                    if isinstance(v, (str, date, datetime)):
+                  
+                        clean_v = str(v).replace("'", "''")
+                        values.append(f"'{clean_v}'")
+                    elif v is None:
+                        values.append("NULL")
+                    else:
+                        values.append(str(v))
+                
+                vals_str = ", ".join(values)
+                sql_stmt = f"INSERT INTO {table_name} ({columns}) VALUES ({vals_str});\n"
+                f.write(sql_stmt)
+
+        print(f"✅ Successfully exported {len(data)} SQL statements to {path}")

fixtureforge-0.1.0/src/fixtureforge/core/generator.py

@@ -0,0 +1,135 @@
+"""Basic data generation using Faker & AI"""
+from typing import Any, Type, Optional, Dict, List
+from faker import Faker
+import random
+import uuid
+from .parser import ModelParser, FieldInfo
+from .router import IntelligentRouter, FieldTier
+from ..ai.engine import AIEngine 
+
+class BasicGenerator:
+    """Generate data using Faker based on Intelligent Routing"""
+    
+    def __init__(self, locale: str = "en_US", api_key: Optional[str] = None):
+        self.faker = Faker(locale)
+        self.router = IntelligentRouter()
+        self._id_counters = {}
+        self.registry: Dict[str, List[Any]] = {} 
+        
+        if api_key:
+            self.ai_engine = AIEngine(api_key)
+        else:
+            self.ai_engine = None
+
+    def generate(self, model: Type, context: str = None, **overrides) -> Any:
+        """Generate a model instance with optional context"""
+        parser = ModelParser()
+        fields = parser.parse(model)
+        
+        data = {}
+        for field in fields:
+            if field.name in overrides:
+                data[field.name] = overrides[field.name]
+            else:
+                data[field.name] = self._generate_smart_value(field, context)
+        
+        instance = model(**data)
+        return instance
+
+    def _generate_smart_value(self, field: FieldInfo, context: str = None) -> Any:
+        tier = self.router.classify(field)
+
+        if tier == FieldTier.STRUCTURAL:
+            return self._generate_structural(field)
+        
+        if tier == FieldTier.SEMANTIC:
+            return self._generate_semantic_content(field, context)
+        
+        return self._generate_standard(field)
+
+    def _generate_structural(self, field: FieldInfo) -> Any:
+        """Handle IDs and Foreign Keys"""
+        name = field.name.lower()
+
+        # 1
+        if name.endswith("_id") and name != "id":
+            target_model = name.replace("_id", "")
+            
+            if target_model in self.registry and self.registry[target_model]:
+                random_record = random.choice(self.registry[target_model])
+                return getattr(random_record, "id")
+
+        # 2
+        if "int" in field.type_name.lower():
+            if field.name not in self._id_counters:
+                self._id_counters[field.name] = 1
+            
+            val = self._id_counters[field.name]
+            self._id_counters[field.name] += 1
+            return val
+            
+        return str(uuid.uuid4())
+
+    def _generate_semantic_content(self, field: FieldInfo, context: str = None) -> str:
+        """Generate REAL content using AI with Context"""
+        if not self.ai_engine or not self.ai_engine.api_key:
+             return f"[AI Placeholder for {field.name}]"
+        
+        prompt = f"Generate a realistic value for a database field named '{field.name}'."
+        
+        if context:
+            prompt += f" IMPORTANT CONTEXT: {context}."
+            
+        prompt += " Output ONLY the value, no quotes."
+        
+        return self.ai_engine.generate_text(prompt)
+
+    def _generate_standard(self, field: FieldInfo) -> Any:
+        """Standard Faker generation - Strictly Cleaned for Linter"""
+        name = field.name.lower()
+        type_name = field.type_name.lower()
+        
+        # Heuristics - Broken down line by line
+        if "email" in name:
+            return self.faker.email()
+            
+        if "name" in name:
+            return self.faker.name()
+            
+        if "address" in name:
+            return self.faker.address()
+            
+        if "phone" in name:
+            return self.faker.phone_number()
+            
+        if "date" in name or "time" in name:
+            return self.faker.date_time_this_year()
+            
+        if "city" in name:
+            return self.faker.city()
+            
+        if "country" in name:
+            return self.faker.country()
+        
+        # Type fallback
+        if "int" in type_name:
+            return self._generate_int(field)
+            
+        if "bool" in type_name:
+            return self.faker.boolean()
+            
+        if "float" in type_name:
+            return random.uniform(0, 1000)
+            
+        return self.faker.word()
+
+    def _generate_int(self, field: FieldInfo) -> int:
+        min_val, max_val = 0, 10000
+        if field.constraints:
+            min_val = field.constraints.get("ge", field.constraints.get("gt", -1) + 1)
+            max_val = field.constraints.get("le", field.constraints.get("lt", 10001) - 1)
+        
+        if min_val > max_val:
+            max_val = min_val + 100
+            
+        return random.randint(min_val, max_val)

fixtureforge-0.1.0/src/fixtureforge/core/parser.py

@@ -0,0 +1,108 @@
+"""
+Model introspection and field extraction (Pydantic Edition)
+"""
+from typing import Any, Dict, List, Type, get_origin, get_args
+from pydantic import BaseModel
+
+# --- SQLAlchemy Support Check ---
+try:
+    from sqlalchemy import inspect as sa_inspect
+    from sqlalchemy.orm import DeclarativeMeta
+    HAS_SQLALCHEMY = True
+except ImportError:
+    HAS_SQLALCHEMY = False
+    # SQLA
+    DeclarativeMeta = type("DeclarativeMeta", (), {}) 
+    sa_inspect = None
+
+class FieldInfo:
+    """Information about a model field"""
+    
+    def __init__(
+        self,
+        name: str,
+        field_type: Type,
+        required: bool = True,
+        default: Any = None,
+        constraints: Dict[str, Any] = None,
+        metadata: Dict[str, Any] = None
+    ):
+        self.name = name
+        self.field_type = field_type
+        self.required = required
+        self.default = default
+        self.constraints = constraints or {}
+        self.metadata = metadata or {}
+    
+    @property
+    def type_name(self) -> str:
+        """Get human-readable type name"""
+        try:
+            origin = get_origin(self.field_type)
+            if origin:
+                args = get_args(self.field_type)
+                if args:
+                    # args
+                    args_str = ', '.join(
+                        a.__name__ if hasattr(a, '__name__') else str(a) 
+                        for a in args
+                    )
+                    return f"{origin.__name__}[{args_str}]"
+                return origin.__name__
+            return self.field_type.__name__
+        except Exception: 
+            return str(self.field_type)
+
+class ModelParser:
+    """Parse Pydantic models"""
+    
+    @classmethod
+    def parse(cls, model: Type[BaseModel]) -> List[FieldInfo]:
+        """Parse Pydantic V2 model"""
+        fields = []
+        
+        for field_name, field_info in model.model_fields.items():
+            # Extract type
+            field_type = field_info.annotation
+            
+            # Check if required
+            required = field_info.is_required()
+            
+            # Get default
+            default = field_info.default if not required else None
+            
+            # Extract constraints 
+            constraints = {}
+            if field_info.metadata:
+                for meta in field_info.metadata:
+                    if hasattr(meta, 'ge') and meta.ge is not None:
+                        constraints['ge'] = meta.ge
+                    if hasattr(meta, 'le') and meta.le is not None:
+                        constraints['le'] = meta.le
+                    if hasattr(meta, 'gt') and meta.gt is not None:
+                        constraints['gt'] = meta.gt
+                    if hasattr(meta, 'lt') and meta.lt is not None:
+                        constraints['lt'] = meta.lt
+                    if hasattr(meta, 'min_length') and meta.min_length is not None:
+                        constraints['min_length'] = meta.min_length
+                    if hasattr(meta, 'max_length') and meta.max_length is not None:
+                        constraints['max_length'] = meta.max_length
+                    if hasattr(meta, 'pattern') and meta.pattern is not None:
+                        constraints['pattern'] = meta.pattern
+
+            # Extract metadata description
+            metadata = {
+                "description": field_info.description,
+                "examples": field_info.examples if hasattr(field_info, 'examples') else None
+            }
+            
+            fields.append(FieldInfo(
+                name=field_name,
+                field_type=field_type,
+                required=required,
+                default=default,
+                constraints=constraints,
+                metadata=metadata
+            ))
+        
+        return fields

fixtureforge-0.1.0/src/fixtureforge/core/recipe.py

@@ -0,0 +1,76 @@
+"""
+Recipe Runner: Executes YAML-based data generation scenarios.
+"""
+import yaml
+from typing import Dict, Type
+from pydantic import create_model, Field
+from fixtureforge import forge
+
+class RecipeRunner:
+    """Parses YAML recipes and executes generation steps"""
+
+    def __init__(self, recipe_path: str):
+        self.recipe_path = recipe_path
+        self.type_mapping = {
+            "int": int,
+            "str": str,
+            "float": float,
+            "bool": bool,
+            "list": list,
+            "dict": dict
+        }
+
+    def run(self):
+        """Execute the recipe"""
+        with open(self.recipe_path, 'r', encoding='utf-8') as f:
+            recipe = yaml.safe_load(f)
+
+        print(f"📜 Running Recipe: {self.recipe_path}")
+        
+        steps = recipe.get("steps", [])
+        results = {}
+
+        for step in steps:
+            model_name = step["model"]
+            count = step.get("count", 1)
+            context = step.get("context", None)
+            fields_config = step.get("fields", {})
+
+            # 1
+            dynamic_model = self._create_dynamic_model(model_name, fields_config)
+
+            print(f"\n🏗️  Step: Creating {count} x {model_name}...")
+            if context:
+                print(f"   🎬 Context: {context}")
+
+            # 2
+            generated_data = forge.create_batch(
+                dynamic_model, 
+                count=count, 
+                context=context
+            )
+            
+            results[model_name] = generated_data
+            
+            # 3
+            self._print_sample(generated_data)
+
+        return results
+
+    def _create_dynamic_model(self, name: str, fields_config: Dict[str, str]) -> Type:
+        """Dynamically build a Pydantic model from YAML definitions"""
+        pydantic_fields = {}
+        
+        for field_name, field_type_str in fields_config.items():
+ 
+            py_type = self.type_mapping.get(field_type_str, str)
+ 
+            pydantic_fields[field_name] = (py_type, Field(description=f"Dynamic field {field_name}"))
+
+        return create_model(name, **pydantic_fields)
+
+    def _print_sample(self, data: list):
+        """Print a summary of generated data"""
+        for item in data[:3]: # Print only first 3 items for brevity
+            d = item.model_dump()
+            print(f"   ✅ {d}")

fixtureforge-0.1.0/src/fixtureforge/core/router.py

@@ -0,0 +1,50 @@
+from enum import Enum, auto 
+from .parser import FieldInfo
+
+class FieldTier(Enum):
+    STRUCTURAL = auto()  # IDs, PKs
+    STANDARD = auto()    # Faker (Name, Email, Dates)
+    SEMANTIC = auto()    # AI (Bio, Reviews, Descriptions)
+
+class IntelligentRouter:
+    """
+    The Brain: Classifies fields into generation tiers based on metadata.
+    """
+
+    def classify(self, field: FieldInfo) -> FieldTier:
+        name = field.name.lower()
+        type_str = field.type_name.lower()
+        constraints = field.constraints
+
+        # --- Tier 0: Structural 
+        if ("id" == name or "_id" in name) and "valid" not in name and "uuid" not in name:
+             return FieldTier.STRUCTURAL
+        
+        if constraints.get("primary_key"):
+            return FieldTier.STRUCTURAL
+
+        standard_keywords = [
+            "name", "email", "phone", "address", "city", 
+            "country", "date", "time", "url", "link"
+        ]
+        if any(k in name for k in standard_keywords):
+            return FieldTier.STANDARD
+
+        # --- Tier 2: Semantic ---
+        semantic_keywords = [
+            "description", "bio", "review", "comment", "reason", 
+            "message", "content", "summary", "feedback", "about", "story"
+        ]
+        
+        if "str" in type_str:
+           
+            if any(keyword in name for keyword in semantic_keywords):
+                return FieldTier.SEMANTIC
+            
+            
+            max_len = constraints.get("max_length", 1000)
+            if max_len > 200:
+                return FieldTier.SEMANTIC
+
+        # --- Tier 1: Standard ---
+        return FieldTier.STANDARD

fixtureforge-0.1.0/src/fixtureforge/core/streamer.py

@@ -0,0 +1,83 @@
+"""
+Data Streamer - The heart of Lazy Evaluation.
+Handles writing data incrementally to avoid Memory Explosion.
+"""
+import csv
+import json
+from pathlib import Path
+from typing import  Any
+from pydantic import BaseModel
+
+class DataStreamer:
+    def __init__(self, filename: str):
+        self.path = Path(filename)
+        self.extension = self.path.suffix.lower()
+        self.file_handle = None
+        self.writer = None
+        self.first_item = True
+        self.is_open = False
+
+    def start(self):
+        """Opens the file stream"""
+        self.file_handle = open(self.path, "w", encoding="utf-8", newline="")
+        self.is_open = True
+        
+        if self.extension == ".json":
+            self.file_handle.write("[\n")  # Start of JSON array
+        elif self.extension == ".sql":
+            self.file_handle.write("-- Auto-generated Stream by FixtureForge\n")
+
+    def write(self, item: Any):
+        """Writes a single item to the stream"""
+        if not self.is_open:
+            raise RuntimeError("Stream is not open. Call start() first.")
+
+        data = item.model_dump() if isinstance(item, BaseModel) else item.__dict__
+
+        if self.extension == ".json":
+            self._write_json_item(data)
+        elif self.extension == ".csv":
+            self._write_csv_item(data)
+        elif self.extension == ".sql":
+            self._write_sql_item(data, item)
+
+    def close(self):
+        """Closes the stream properly"""
+        if self.extension == ".json":
+            self.file_handle.write("\n]")  # End of JSON array
+        
+        if self.file_handle:
+            self.file_handle.close()
+        self.is_open = False
+        print(f"✅ Stream closed. Data saved to {self.path}")
+
+    def _write_json_item(self, data: dict):
+        if not self.first_item:
+            self.file_handle.write(",\n")
+        json_str = json.dumps(data, default=str, indent=2)
+        # Indent the internal lines to make it valid pretty JSON
+        self.file_handle.write(json_str)
+        self.first_item = False
+
+    def _write_csv_item(self, data: dict):
+        if self.first_item:
+            self.writer = csv.DictWriter(self.file_handle, fieldnames=data.keys())
+            self.writer.writeheader()
+        
+        self.writer.writerow(data)
+        self.first_item = False
+
+    def _write_sql_item(self, data: dict, original_obj: Any):
+        table_name = original_obj.__class__.__name__.lower() + "s"
+        columns = ", ".join(data.keys())
+        values = []
+        
+        for v in data.values():
+            if v is None:
+                values.append("NULL")
+            else:
+                clean_v = str(v).replace("'", "''")
+                values.append(f"'{clean_v}'")
+        
+        vals_str = ", ".join(values)
+        self.file_handle.write(f"INSERT INTO {table_name} ({columns}) VALUES ({vals_str});\n")

fixtureforge-0.1.0/src/fixtureforge/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "fixtureforge"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "Your Name",email = "you@example.com"}
+]
+requires-python = ">=3.11"
+dependencies = [
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"