hexdag-forge 0.2.0.dev2__tar.gz → 0.2.0.dev4__tar.gz

hexdag_forge-0.2.0.dev4/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: hexdag-forge
+Version: 0.2.0.dev4
+Summary: Generate operational systems from prompts — code generator powered by hexDAG
+Project-URL: Homepage, https://hexdag.ai
+Project-URL: Repository, https://github.com/omniviser/hexdag
+Project-URL: Documentation, https://hexdag.ai/docs/forge
+Project-URL: Bug Reports, https://github.com/omniviser/hexdag/issues
+Author-email: hexDAG Team <developers@omniviser.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,code-generation,crm,erp,forge,hexdag,operational-systems,tms
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.12
+Requires-Dist: hexdag>=0.7.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# hexDAG Forge
+
+**Generate operational systems from prompts.** Describe your business, get a complete system with YAML pipelines, Python services, Django models, state machines, and auto-migrations.
+
+## How it works
+
+1. You describe your business to Claude Code (via `/forge` or the MCP server)
+2. Claude analyzes the description and builds a `BusinessProfile` JSON (entities, fields, states, transitions, relationships)
+3. Forge generates the complete system from that profile
+4. When you change the ontology, `forge_migrate` diffs the profiles and generates Django migrations automatically
+
+## Output
+
+```
+./generated/
+├── system.yaml              # kind: System manifest (LifecycleRunner)
+├── profile.json              # BusinessProfile (source of truth)
+├── settings.py / manage.py   # Django project scaffold
+├── admin.py / urls.py        # Django admin auto-registration
+├── models/
+│   └── models.py             # Django ORM models with fields + state choices
+├── migrations/
+│   └── 0001_auto.py          # Initial Django migration (auto-generated)
+├── state_machines.py         # StateMachineConfig definitions
+├── pipelines/
+│   ├── load_lifecycle.yaml   # hexDAG pipeline per entity
+│   └── carrier_lifecycle.yaml
+└── services/
+    ├── load_service.py       # @tool/@step CRUD (implemented) + domain stubs
+    └── carrier_service.py
+```
+
+## What it generates
+
+- **YAML Pipelines** -- entity lifecycle workflows using hexDAG nodes
+- **Python Services** -- `@tool`/`@step` CRUD methods (implemented) + domain-specific stubs (`NotImplementedError`) for the builder agent to fill
+- **Django Models** -- ORM models with fields, relationships, state choices
+- **System Manifest** -- `kind: System` with state machines, `on_enter` process mappings, terminal states
+- **State Machines** -- `StateMachineConfig` definitions with validated transitions
+- **Django Migrations** -- auto-generated from profile diffs (CreateModel, AddField, AlterField, etc.)
+
+## MCP + Claude Code
+
+```bash
+pip install hexdag-forge
+hexdag-forge mcp serve
+```
+
+### Skills
+
+- `/forge "I run a freight brokerage"` -- generate a new system
+- `/forge:entity "add Carrier with mc_number, score"` -- add/modify entity (with automigration)
+- `/forge:implement "fill in negotiate_rate"` -- implement a service stub
+- `/forge:test` -- validate generated files
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `forge_profile_schema` | Get the BusinessProfile JSON schema |
+| `forge_generate` | Generate a new system from a BusinessProfile JSON |
+| `forge_migrate` | Update an existing system -- diffs profiles, regenerates, writes migration |
+| `forge_get_profile` | Read the profile from a generated system |
+| `forge_validate` | Validate generated files (syntax, structure) |
+| `forge_list_stubs` | List NotImplementedError methods in services |
+| `forge_implement_stub` | Replace a stub with implementation code |
+
+## CLI
+
+```bash
+# Generate from a profile JSON file
+hexdag-forge generate profile.json --output ./my-erp/
+
+# Validate generated files
+hexdag-forge validate ./my-erp/
+
+# Start MCP server for Claude Code
+hexdag-forge mcp serve
+```
+
+## Automigration
+
+When you modify the ontology (add entities, change fields, rename states), forge automatically generates Django migration files:
+
+```
+# Initial generation creates 0001_auto.py with CreateModel for each entity
+/forge "freight brokerage with loads and carriers"
+→ migrations/0001_auto.py (CreateModel: Load, Carrier)
+
+# Adding a field via /forge:entity creates 0002_auto.py
+/forge:entity "add weight_limit field to carrier"
+→ migrations/0002_auto.py (AddField: carrier.weight_limit)
+
+# Changing states creates another migration
+/forge:entity "add SUSPENDED state to carrier"
+→ migrations/0003_auto.py (AlterField: carrier.status choices)
+```
+
+Supported operations: `CreateModel`, `DeleteModel`, `AddField`, `RemoveField`, `AlterField` (type changes, option changes, state changes), `ForeignKey` additions/removals.
+
+## License
+
+Apache 2.0

hexdag_forge-0.2.0.dev4/README.md

@@ -0,0 +1,103 @@
+# hexDAG Forge
+
+**Generate operational systems from prompts.** Describe your business, get a complete system with YAML pipelines, Python services, Django models, state machines, and auto-migrations.
+
+## How it works
+
+1. You describe your business to Claude Code (via `/forge` or the MCP server)
+2. Claude analyzes the description and builds a `BusinessProfile` JSON (entities, fields, states, transitions, relationships)
+3. Forge generates the complete system from that profile
+4. When you change the ontology, `forge_migrate` diffs the profiles and generates Django migrations automatically
+
+## Output
+
+```
+./generated/
+├── system.yaml              # kind: System manifest (LifecycleRunner)
+├── profile.json              # BusinessProfile (source of truth)
+├── settings.py / manage.py   # Django project scaffold
+├── admin.py / urls.py        # Django admin auto-registration
+├── models/
+│   └── models.py             # Django ORM models with fields + state choices
+├── migrations/
+│   └── 0001_auto.py          # Initial Django migration (auto-generated)
+├── state_machines.py         # StateMachineConfig definitions
+├── pipelines/
+│   ├── load_lifecycle.yaml   # hexDAG pipeline per entity
+│   └── carrier_lifecycle.yaml
+└── services/
+    ├── load_service.py       # @tool/@step CRUD (implemented) + domain stubs
+    └── carrier_service.py
+```
+
+## What it generates
+
+- **YAML Pipelines** -- entity lifecycle workflows using hexDAG nodes
+- **Python Services** -- `@tool`/`@step` CRUD methods (implemented) + domain-specific stubs (`NotImplementedError`) for the builder agent to fill
+- **Django Models** -- ORM models with fields, relationships, state choices
+- **System Manifest** -- `kind: System` with state machines, `on_enter` process mappings, terminal states
+- **State Machines** -- `StateMachineConfig` definitions with validated transitions
+- **Django Migrations** -- auto-generated from profile diffs (CreateModel, AddField, AlterField, etc.)
+
+## MCP + Claude Code
+
+```bash
+pip install hexdag-forge
+hexdag-forge mcp serve
+```
+
+### Skills
+
+- `/forge "I run a freight brokerage"` -- generate a new system
+- `/forge:entity "add Carrier with mc_number, score"` -- add/modify entity (with automigration)
+- `/forge:implement "fill in negotiate_rate"` -- implement a service stub
+- `/forge:test` -- validate generated files
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `forge_profile_schema` | Get the BusinessProfile JSON schema |
+| `forge_generate` | Generate a new system from a BusinessProfile JSON |
+| `forge_migrate` | Update an existing system -- diffs profiles, regenerates, writes migration |
+| `forge_get_profile` | Read the profile from a generated system |
+| `forge_validate` | Validate generated files (syntax, structure) |
+| `forge_list_stubs` | List NotImplementedError methods in services |
+| `forge_implement_stub` | Replace a stub with implementation code |
+
+## CLI
+
+```bash
+# Generate from a profile JSON file
+hexdag-forge generate profile.json --output ./my-erp/
+
+# Validate generated files
+hexdag-forge validate ./my-erp/
+
+# Start MCP server for Claude Code
+hexdag-forge mcp serve
+```
+
+## Automigration
+
+When you modify the ontology (add entities, change fields, rename states), forge automatically generates Django migration files:
+
+```
+# Initial generation creates 0001_auto.py with CreateModel for each entity
+/forge "freight brokerage with loads and carriers"
+→ migrations/0001_auto.py (CreateModel: Load, Carrier)
+
+# Adding a field via /forge:entity creates 0002_auto.py
+/forge:entity "add weight_limit field to carrier"
+→ migrations/0002_auto.py (AddField: carrier.weight_limit)
+
+# Changing states creates another migration
+/forge:entity "add SUSPENDED state to carrier"
+→ migrations/0003_auto.py (AlterField: carrier.status choices)
+```
+
+Supported operations: `CreateModel`, `DeleteModel`, `AddField`, `RemoveField`, `AlterField` (type changes, option changes, state changes), `ForeignKey` additions/removals.
+
+## License
+
+Apache 2.0

{hexdag_forge-0.2.0.dev2 → hexdag_forge-0.2.0.dev4}/hexdag_forge/cli.py

@@ -19,17 +19,17 @@ app.add_typer(mcp_app, name="mcp")
 
 @app.command()
 def generate(
-    description: Annotated[str, typer.Argument(help="Business description")],
+    profile: Annotated[Path, typer.Argument(help="Path to BusinessProfile JSON file")],
     output: Annotated[
         Path, typer.Option(help="Output directory for generated files")
     ] = "./generated",
 ) -> None:
-    """Generate an operational system from a business description."""
+    """Generate an operational system from a BusinessProfile JSON file."""
+    from hexdag_forge.domain.business_profile import BusinessProfile
     from hexdag_forge.generator.assembler import assemble
-    from hexdag_forge.generator.business_analyzer import create_default_profile
 
-    profile = create_default_profile(description)
-    result = assemble(profile, output)
+    bp = BusinessProfile.model_validate_json(profile.read_text())
+    result = assemble(bp, output)
     typer.echo(f"Generated system in {output}/")
     typer.echo(f"  Entities: {', '.join(e.name for e in result.profile.entities)}")
     typer.echo(f"  Pipelines: {len(result.pipelines)} files")

{hexdag_forge-0.2.0.dev2 → hexdag_forge-0.2.0.dev4}/hexdag_forge/domain/__init__.py

@@ -8,13 +8,25 @@ from hexdag_forge.domain.business_profile import (
 )
 from hexdag_forge.domain.enums import FieldType, RelationshipKind
 from hexdag_forge.domain.generated_system import GeneratedSystem
+from hexdag_forge.domain.profile_diff import (
+    EntityChange,
+    FieldChange,
+    ProfileDiff,
+    RelationshipChange,
+    StateChange,
+)
 
 __all__ = [
     "BusinessProfile",
+    "EntityChange",
     "EntitySpec",
+    "FieldChange",
     "FieldSpec",
     "FieldType",
     "GeneratedSystem",
+    "ProfileDiff",
+    "RelationshipChange",
     "RelationshipKind",
     "RelationshipSpec",
+    "StateChange",
 ]

{hexdag_forge-0.2.0.dev2 → hexdag_forge-0.2.0.dev4}/hexdag_forge/domain/business_profile.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
+import re
 from typing import Any
 
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel, field_validator, model_validator
 
 
 class FieldSpec(BaseModel):
@@ -98,3 +99,27 @@ class BusinessProfile(BaseModel):
     entities: list[EntitySpec]
     workflows: list[str] = []
     modules: list[str] = []
+    app_label: str = ""
+
+    @model_validator(mode="before")
+    @classmethod
+    def derive_app_label(cls, data: Any) -> Any:
+        """Derive app_label from business_name if not provided."""
+        if isinstance(data, dict) and not data.get("app_label"):
+            name = data.get("business_name", "app")
+            # "Freight Brokerage" → "freight_brokerage"
+            label = re.sub(r"[^a-zA-Z0-9]+", "_", name).strip("_").lower()
+            data["app_label"] = label
+        return data
+
+    @field_validator("app_label")
+    @classmethod
+    def validate_app_label(cls, v: str) -> str:
+        """Ensure app_label is a valid lowercase Python identifier."""
+        if not v.isidentifier():
+            msg = f"app_label must be a valid Python identifier, got: {v!r}"
+            raise ValueError(msg)
+        if v != v.lower():
+            msg = f"app_label must be lowercase, got: {v!r}"
+            raise ValueError(msg)
+        return v

hexdag_forge-0.2.0.dev4/hexdag_forge/domain/profile_diff.py

@@ -0,0 +1,67 @@
+"""Domain models for profile diffing — captures schema changes between two BusinessProfiles."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from hexdag_forge.domain.business_profile import (  # noqa: TC001
+    EntitySpec,
+    FieldSpec,
+    RelationshipSpec,
+)
+
+
+class FieldChange(BaseModel):
+    """A single field-level change within an entity."""
+
+    entity_name: str
+    field_name: str
+    change_type: str  # "add" | "remove" | "alter_type" | "alter_options"
+    old_field: FieldSpec | None = None
+    new_field: FieldSpec | None = None
+
+
+class RelationshipChange(BaseModel):
+    """A relationship added or removed."""
+
+    entity_name: str
+    field_name: str
+    change_type: str  # "add" | "remove"
+    old_rel: RelationshipSpec | None = None
+    new_rel: RelationshipSpec | None = None
+
+
+class StateChange(BaseModel):
+    """Change in an entity's status choices or initial state."""
+
+    entity_name: str
+    old_states: list[str]
+    new_states: list[str]
+    old_initial: str
+    new_initial: str
+
+
+class EntityChange(BaseModel):
+    """An entire entity added or removed."""
+
+    change_type: str  # "add" | "remove"
+    entity: EntitySpec
+
+
+class ProfileDiff(BaseModel):
+    """Complete diff between two BusinessProfile versions."""
+
+    entity_changes: list[EntityChange] = []
+    field_changes: list[FieldChange] = []
+    relationship_changes: list[RelationshipChange] = []
+    state_changes: list[StateChange] = []
+
+    @property
+    def has_changes(self) -> bool:
+        """Return True if any schema changes were detected."""
+        return bool(
+            self.entity_changes
+            or self.field_changes
+            or self.relationship_changes
+            or self.state_changes
+        )

{hexdag_forge-0.2.0.dev2 → hexdag_forge-0.2.0.dev4}/hexdag_forge/generator/assembler.py

@@ -18,12 +18,19 @@ from hexdag_forge.generator.service_generator import generate_services
 from hexdag_forge.generator.system_generator import generate_system
 
 
-def assemble(profile: BusinessProfile, output_dir: Path) -> GeneratedSystem:
+def assemble(
+    profile: BusinessProfile,
+    output_dir: Path,
+    *,
+    skip_migration: bool = False,
+) -> GeneratedSystem:
     """Generate all files from a BusinessProfile and write to output_dir.
 
     Args:
         profile: The business profile to generate from.
         output_dir: Directory to write generated files to.
+        skip_migration: If True, skip migration generation (used when the
+            caller has already generated the migration, e.g. ``forge_migrate``).
 
     Returns:
         GeneratedSystem with metadata about what was generated.
@@ -57,8 +64,39 @@ def assemble(profile: BusinessProfile, output_dir: Path) -> GeneratedSystem:
         file_path.parent.mkdir(parents=True, exist_ok=True)
         file_path.write_text(content)
 
-    # Write models/__init__.py
-    (output_dir / "models" / "__init__.py").write_text("")
+    # Write app __init__.py
+    app_dir = output_dir / profile.app_label
+    app_dir.mkdir(parents=True, exist_ok=True)
+    (app_dir / "__init__.py").write_text("")
+
+    # Write migrations dir + initial migration
+    migrations_dir = app_dir / "migrations"
+    migrations_dir.mkdir(exist_ok=True)
+    (migrations_dir / "__init__.py").write_text("")
+
+    if not skip_migration:
+        from hexdag_forge.generator.migration_generator import generate_migration
+
+        # Use existing profile.json (from a previous run) as the old state so
+        # that diff_profiles produces incremental operations (AddField, etc.)
+        # instead of CreateModel for every entity.  On the first run the file
+        # does not exist yet, so we fall back to an empty profile.
+        profile_path = output_dir / "profile.json"
+        if profile_path.exists():
+            old_profile = BusinessProfile.model_validate_json(profile_path.read_text())
+        else:
+            old_profile = BusinessProfile(
+                business_name=profile.business_name,
+                business_type=profile.business_type,
+                description=profile.description,
+                entities=[],
+                app_label=profile.app_label,
+            )
+
+        result = generate_migration(old_profile, profile, migrations_dir)
+        if result is not None:
+            filename, migration_content = result
+            (migrations_dir / filename).write_text(migration_content)
 
     # Write profile.json for refinement
     (output_dir / "profile.json").write_text(profile.model_dump_json(indent=2))
@@ -67,7 +105,9 @@ def assemble(profile: BusinessProfile, output_dir: Path) -> GeneratedSystem:
         profile=profile,
         pipelines=pipelines,
         services=services,
-        models_source={"models/models.py": django_files["models/models.py"]},
+        models_source={
+            f"{profile.app_label}/models.py": django_files[f"{profile.app_label}/models.py"]
+        },
         state_machines={e.name: e.transitions for e in profile.entities},
         system_yaml=system_yaml,
     )
@@ -83,7 +123,7 @@ def validate_system(output_dir: Path) -> list[str]:
     output_dir = Path(output_dir)
 
     # Check required files exist
-    required = ["system.yaml", "profile.json", "settings.py", "manage.py"]
+    required = ["system.yaml", "profile.json", "settings.py", "manage.py", "views.py", "forms.py"]
     errors.extend(f"Missing required file: {f}" for f in required if not (output_dir / f).exists())
 
     # Check pipelines directory

hexdag_forge-0.2.0.dev4/hexdag_forge/generator/diff.py

@@ -0,0 +1,157 @@
+"""Profile diffing engine — compares two BusinessProfiles and produces a ProfileDiff."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hexdag_forge.domain.profile_diff import (
+    EntityChange,
+    FieldChange,
+    ProfileDiff,
+    RelationshipChange,
+    StateChange,
+)
+
+if TYPE_CHECKING:
+    from hexdag_forge.domain.business_profile import BusinessProfile, EntitySpec
+
+
+def diff_profiles(old: BusinessProfile, new: BusinessProfile) -> ProfileDiff:
+    """Compare two BusinessProfiles and return a structured diff.
+
+    Entity matching is by ``name`` (the Python identifier).
+    Field matching is by ``field.name``. Relationship matching by ``field_name``.
+    Renames are treated as remove + add.
+    """
+    old_entities = {e.name: e for e in old.entities}
+    new_entities = {e.name: e for e in new.entities}
+
+    # Added / removed entities
+    entity_changes = [
+        EntityChange(change_type="add", entity=new_entities[n])
+        for n in new_entities
+        if n not in old_entities
+    ] + [
+        EntityChange(change_type="remove", entity=old_entities[n])
+        for n in old_entities
+        if n not in new_entities
+    ]
+
+    # Compare internals for entities present in both
+    field_changes: list[FieldChange] = []
+    relationship_changes: list[RelationshipChange] = []
+    state_changes: list[StateChange] = []
+
+    for name in old_entities:
+        if name in new_entities:
+            old_e = old_entities[name]
+            new_e = new_entities[name]
+            field_changes.extend(_diff_fields(name, old_e, new_e))
+            relationship_changes.extend(_diff_relationships(name, old_e, new_e))
+            sc = _diff_states(name, old_e, new_e)
+            if sc is not None:
+                state_changes.append(sc)
+
+    return ProfileDiff(
+        entity_changes=entity_changes,
+        field_changes=field_changes,
+        relationship_changes=relationship_changes,
+        state_changes=state_changes,
+    )
+
+
+def _diff_fields(entity_name: str, old: EntitySpec, new: EntitySpec) -> list[FieldChange]:
+    """Compare fields between two versions of the same entity."""
+    old_fields = {f.name: f for f in old.fields}
+    new_fields = {f.name: f for f in new.fields}
+    changes: list[FieldChange] = []
+
+    for fname in new_fields:
+        if fname not in old_fields:
+            changes.append(
+                FieldChange(
+                    entity_name=entity_name,
+                    field_name=fname,
+                    change_type="add",
+                    new_field=new_fields[fname],
+                )
+            )
+        else:
+            old_f = old_fields[fname]
+            new_f = new_fields[fname]
+            if old_f.type != new_f.type:
+                changes.append(
+                    FieldChange(
+                        entity_name=entity_name,
+                        field_name=fname,
+                        change_type="alter_type",
+                        old_field=old_f,
+                        new_field=new_f,
+                    )
+                )
+            elif old_f.required != new_f.required or old_f.default != new_f.default:
+                changes.append(
+                    FieldChange(
+                        entity_name=entity_name,
+                        field_name=fname,
+                        change_type="alter_options",
+                        old_field=old_f,
+                        new_field=new_f,
+                    )
+                )
+
+    changes.extend(
+        FieldChange(
+            entity_name=entity_name,
+            field_name=fname,
+            change_type="remove",
+            old_field=old_fields[fname],
+        )
+        for fname in old_fields
+        if fname not in new_fields
+    )
+
+    return changes
+
+
+def _diff_relationships(
+    entity_name: str,
+    old: EntitySpec,
+    new: EntitySpec,
+) -> list[RelationshipChange]:
+    """Compare relationships between two versions of the same entity."""
+    old_rels = {r.field_name: r for r in old.relationships}
+    new_rels = {r.field_name: r for r in new.relationships}
+
+    return [
+        RelationshipChange(
+            entity_name=entity_name,
+            field_name=fname,
+            change_type="add",
+            new_rel=new_rels[fname],
+        )
+        for fname in new_rels
+        if fname not in old_rels
+    ] + [
+        RelationshipChange(
+            entity_name=entity_name,
+            field_name=fname,
+            change_type="remove",
+            old_rel=old_rels[fname],
+        )
+        for fname in old_rels
+        if fname not in new_rels
+    ]
+
+
+def _diff_states(entity_name: str, old: EntitySpec, new: EntitySpec) -> StateChange | None:
+    """Compare states and initial_state between two versions of the same entity."""
+    if old.states == new.states and old.initial_state == new.initial_state:
+        return None
+    return StateChange(
+        entity_name=entity_name,
+        old_states=old.states,
+        new_states=new.states,
+        old_initial=old.initial_state,
+        new_initial=new.initial_state,
+    )