hexdag-forge 0.2.0.dev2__py3-none-any.whl

hexdag_forge/generator/template_engine.py

@@ -0,0 +1,27 @@
+"""Jinja2 template rendering engine for code generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+_TEMPLATE_DIR = Path(__file__).parent.parent / "templates"
+
+
+def create_env() -> Environment:
+    """Create a Jinja2 environment configured for code generation."""
+    return Environment(  # nosec B701 — code generation templates, not HTML
+        loader=FileSystemLoader(str(_TEMPLATE_DIR)),
+        keep_trailing_newline=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        autoescape=False,
+    )
+
+
+def render_template(template_name: str, **context: object) -> str:
+    """Render a Jinja2 template with the given context."""
+    env = create_env()
+    template = env.get_template(template_name)
+    return template.render(**context)

hexdag_forge/mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for running the forge MCP server via `python -m hexdag_forge.mcp`."""
+
+from hexdag_forge.mcp.server import mcp
+
+mcp.run(transport="stdio")

hexdag_forge/mcp/server.py

@@ -0,0 +1,180 @@
+"""MCP server for hexdag-forge.
+
+Exposes forge tools via FastMCP so Claude Code can generate
+and manage operational systems.
+
+Usage:
+    hexdag-forge mcp serve              # stdio (for Claude Code)
+    hexdag-forge mcp serve --transport sse --port 3001
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from hexdag_forge.domain.business_profile import BusinessProfile
+from hexdag_forge.generator.assembler import assemble, validate_system
+from hexdag_forge.generator.business_analyzer import create_default_profile
+
+mcp = FastMCP(
+    "hexdag-forge",
+    instructions="Generate operational systems (ERP/TMS/CRM) from business descriptions. "
+    "Use forge_generate to create a system, forge_get_schema to inspect it, "
+    "forge_list_stubs to find methods that need implementation.",
+)
+
+
+@mcp.tool()
+async def forge_generate(description: str, output_dir: str = "./generated") -> str:
+    """Generate a complete operational system from a business description.
+
+    Creates YAML pipelines, Python services, Django models, state machines,
+    and a kind: System manifest in the output directory.
+    """
+    profile = create_default_profile(description)
+    result = assemble(profile, Path(output_dir))
+
+    summary = {
+        "output_dir": str(output_dir),
+        "business_name": result.profile.business_name,
+        "entities": [
+            {
+                "name": e.name,
+                "display_name": e.display_name,
+                "fields": len(e.fields),
+                "states": e.states,
+            }
+            for e in result.profile.entities
+        ],
+        "pipelines": list(result.pipelines.keys()),
+        "services": list(result.services.keys()),
+    }
+    return json.dumps(summary, indent=2)
+
+
+@mcp.tool()
+async def forge_generate_from_profile(profile_json: str, output_dir: str = "./generated") -> str:
+    """Generate a system from a pre-built BusinessProfile JSON.
+
+    Use this when you've already extracted the entities, fields, states,
+    and relationships — pass the full BusinessProfile as JSON.
+    """
+    profile = BusinessProfile.model_validate_json(profile_json)
+    result = assemble(profile, Path(output_dir))
+
+    return json.dumps(
+        {
+            "output_dir": str(output_dir),
+            "entities": [e.name for e in result.profile.entities],
+            "pipelines": list(result.pipelines.keys()),
+            "services": list(result.services.keys()),
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+async def forge_validate(output_dir: str) -> str:
+    """Validate all generated files in a directory.
+
+    Checks: required files exist, Python syntax valid, profile.json valid.
+    """
+    errors = validate_system(Path(output_dir))
+    return json.dumps({"valid": len(errors) == 0, "errors": errors}, indent=2)
+
+
+@mcp.tool()
+async def forge_get_schema(output_dir: str) -> str:
+    """Read the BusinessProfile from a generated system.
+
+    Returns the full schema: entities with fields, states, transitions, relationships.
+    """
+    profile_path = Path(output_dir) / "profile.json"
+    if not profile_path.exists():
+        return json.dumps({"error": f"No profile.json found in {output_dir}"})
+
+    profile = BusinessProfile.model_validate_json(profile_path.read_text())
+    return json.dumps(profile.model_dump(), indent=2, default=str)
+
+
+@mcp.tool()
+async def forge_list_stubs(output_dir: str) -> str:
+    """List all NotImplementedError stubs in generated services.
+
+    Shows methods that need actual business logic implementation.
+    """
+    import ast
+
+    stubs: list[dict[str, str]] = []
+    services_dir = Path(output_dir) / "services"
+    if not services_dir.exists():
+        return json.dumps([])
+
+    for py_file in services_dir.glob("*.py"):
+        tree = ast.parse(py_file.read_text())
+        for node in ast.walk(tree):
+            if isinstance(node, ast.AsyncFunctionDef):
+                for stmt in ast.walk(node):
+                    if isinstance(stmt, ast.Raise) and isinstance(stmt.exc, ast.Call):
+                        func = stmt.exc.func
+                        if isinstance(func, ast.Name) and func.id == "NotImplementedError":
+                            stubs.append({
+                                "service": py_file.stem,
+                                "method": node.name,
+                                "file": str(py_file.relative_to(output_dir)),
+                                "docstring": ast.get_docstring(node) or "",
+                            })
+
+    return json.dumps(stubs, indent=2)
+
+
+@mcp.tool()
+async def forge_implement_stub(
+    output_dir: str,
+    service_name: str,
+    method_name: str,
+    implementation: str,
+) -> str:
+    """Replace a NotImplementedError stub with actual implementation code.
+
+    The implementation should be the method body lines (properly indented with 8 spaces).
+    """
+    import ast
+    import re
+
+    service_path = Path(output_dir) / "services" / f"{service_name}.py"
+    if not service_path.exists():
+        return json.dumps({"error": f"Service file not found: {service_name}.py"})
+
+    source = service_path.read_text()
+
+    pattern = rf"(        raise NotImplementedError\([^)]*{re.escape(method_name)}[^)]*\))"
+    match = re.search(pattern, source)
+    if not match:
+        return json.dumps({"error": f"Stub for {method_name} not found"})
+
+    new_source = source[: match.start()] + implementation + source[match.end() :]
+
+    try:
+        ast.parse(new_source)
+    except SyntaxError as e:
+        return json.dumps({"error": f"Syntax error in implementation: {e}"})
+
+    service_path.write_text(new_source)
+    return json.dumps({"success": True, "file": str(service_path)})
+
+
+def run_server(transport: str = "stdio", port: int = 3001) -> None:
+    """Start the MCP server."""
+    if transport == "stdio":
+        mcp.run(transport="stdio")
+    elif transport == "sse":
+        mcp.run(
+            transport="sse",
+            sse_params={"host": "0.0.0.0", "port": port},  # nosec B104
+        )
+    else:
+        mcp.run(transport=transport)

hexdag_forge/skills/forge.md

@@ -0,0 +1,34 @@
+---
+name: forge
+description: Generate an operational system from a business description
+---
+
+Use the forge MCP server to generate a complete operational system.
+
+## Steps
+
+1. Call `forge_generate` with the user's business description and an output directory.
+   - If the user provides a detailed BusinessProfile JSON, use `forge_generate_from_profile` instead.
+
+2. Show the user a summary of what was generated:
+   - Entity names, their fields and states
+   - Generated pipeline files
+   - Generated service files (with CRUD + domain stubs)
+
+3. Ask if the user wants to refine the generated system:
+   - If yes, call `forge_refine` with their instructions
+   - Show what changed
+
+4. List any stubs that need implementation:
+   - Call `forge_list_stubs` to show NotImplementedError methods
+   - Ask if the user wants to implement any of them
+
+5. Validate the output:
+   - Call `forge_validate` to check all files are valid
+
+## Notes
+
+- The generated system includes: system.yaml, YAML pipelines, Python services, Django models, state machines
+- Services have `@tool`/`@step` decorated CRUD methods (fully implemented) and domain-specific stubs (NotImplementedError)
+- The system.yaml uses hexDAG's `kind: System` with LifecycleRunner (state machine driven)
+- profile.json is saved for future refinement

hexdag_forge/skills/forge_entity.md

@@ -0,0 +1,25 @@
+---
+name: forge:entity
+description: Add or modify an entity type in a generated forge system
+---
+
+Use the forge MCP server to add or modify entities in a generated system.
+
+## Adding an entity
+
+1. Call `forge_get_schema` to see the current entities in the system
+2. Build the entity spec from the user's description (name, fields, states, transitions, relationships)
+3. Load the current profile, add the new entity, and call `forge_generate_from_profile` to regenerate
+
+## Modifying an entity
+
+1. Call `forge_get_schema` to see current entity definition
+2. Modify the profile JSON with the user's requested changes
+3. Call `forge_generate_from_profile` with the updated profile to regenerate all files
+
+## Notes
+
+- Entity names must be valid Python identifiers (snake_case)
+- Every entity needs at least 2 states and a valid initial_state
+- Transitions must only reference declared states
+- Relationships use: belongs_to, has_many, has_one

hexdag_forge/skills/forge_implement.md

@@ -0,0 +1,39 @@
+---
+name: forge:implement
+description: Implement a service stub method with business logic
+---
+
+Use the forge MCP server to fill in NotImplementedError stubs with actual implementations.
+
+## Steps
+
+1. Call `forge_list_stubs` to see all stubs that need implementation
+   - Shows: service name, method name, docstring with expected behavior
+
+2. If the user specifies which stub, proceed. Otherwise ask them to pick one.
+
+3. Call `forge_get_schema` to understand the entity fields, states, and relationships — this provides context for writing the implementation.
+
+4. Write the implementation code:
+   - The code should replace the `raise NotImplementedError(...)` line
+   - Keep the same indentation level (8 spaces)
+   - Use `self._db` for database operations
+   - Return a dict with the result
+
+5. Call `forge_implement_stub` with the service name, method name, and implementation code.
+
+6. Call `forge_validate` to verify the implementation has valid syntax.
+
+## Example
+
+For a stub like `negotiate_rate_with_carrier`:
+```python
+        # Compare offered rate vs target
+        load = await self._db.get("load", load_id)
+        target = load.get("target_rate", 0)
+        offered = kwargs.get("offered_rate", 0)
+        if offered <= target:
+            return {"action": "accept", "rate": offered}
+        counter = target * 1.05
+        return {"action": "counter", "counter_rate": counter}
+```

hexdag_forge/skills/forge_test.md

@@ -0,0 +1,23 @@
+---
+name: forge:test
+description: Validate and test a generated forge system
+---
+
+Use the forge MCP server to validate generated files.
+
+## Steps
+
+1. Call `forge_validate` with the output directory
+   - Checks: required files exist, Python syntax valid, profile.json valid, YAML files present
+
+2. If there are errors, show them and suggest fixes.
+
+3. For deeper testing:
+   - Read the generated pipeline YAML files and check they reference valid services
+   - Read the system.yaml and verify state machines and processes are consistent
+   - Check that all entity states referenced in transitions are declared
+
+## Notes
+
+- `forge_validate` does not execute pipelines — it only checks file structure and syntax
+- For runtime testing, the user needs to install the generated system and run it with hexDAG

hexdag_forge/templates/django_admin.py.j2

@@ -0,0 +1,21 @@
+"""Django admin registration for {{ profile.business_name }}.
+
+Auto-generated by hexdag-forge.
+"""
+
+from django.contrib import admin
+
+from models.models import (
+{% for entity in profile.entities %}
+    {{ entity.name | capitalize }},
+{% endfor %}
+)
+
+{% for entity in profile.entities %}
+
+@admin.register({{ entity.name | capitalize }})
+class {{ entity.name | capitalize }}Admin(admin.ModelAdmin):
+    list_display = ("__str__", "status"{% for field in entity.fields[:3] %}, "{{ field.name }}"{% endfor %}, "updated_at")
+    list_filter = ("status",)
+    search_fields = ({% for field in entity.fields[:3] %}"{{ field.name }}", {% endfor %})
+{% endfor %}

hexdag_forge/templates/django_manage.py.j2

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+"""Django management script for {{ profile.business_name }}.
+
+Auto-generated by hexdag-forge.
+"""
+
+import os
+import sys
+
+
+def main() -> None:
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "settings")
+    from django.core.management import execute_from_command_line
+
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

hexdag_forge/templates/django_model.py.j2

@@ -0,0 +1,62 @@
+"""Generated Django models for {{ profile.business_name }}.
+
+Auto-generated by hexdag-forge. Modify as needed.
+"""
+
+from django.db import models
+
+
+{% for entity in profile.entities %}
+class {{ entity.name | capitalize }}(models.Model):
+    """{{ entity.display_name }}{% if entity.description %} — {{ entity.description }}{% endif %}"""
+
+{% for field in entity.fields %}
+{% if field.type == "str" %}
+    {{ field.name }} = models.CharField(max_length=255{% if not field.required %}, blank=True, null=True{% endif %}{% if field.default is not none %}, default="{{ field.default }}"{% endif %})
+{% elif field.type == "text" %}
+    {{ field.name }} = models.TextField({% if not field.required %}blank=True, null=True{% endif %}{% if field.default is not none %}, default="{{ field.default }}"{% endif %})
+{% elif field.type == "int" %}
+    {{ field.name }} = models.IntegerField({% if not field.required %}null=True, blank=True{% endif %}{% if field.default is not none %}, default={{ field.default }}{% endif %})
+{% elif field.type == "float" %}
+    {{ field.name }} = models.FloatField({% if not field.required %}null=True, blank=True{% endif %}{% if field.default is not none %}, default={{ field.default }}{% endif %})
+{% elif field.type == "Decimal" %}
+    {{ field.name }} = models.DecimalField(max_digits=12, decimal_places=2{% if not field.required %}, null=True, blank=True{% endif %}{% if field.default is not none %}, default={{ field.default }}{% endif %})
+{% elif field.type == "bool" %}
+    {{ field.name }} = models.BooleanField(default={% if field.default is not none %}{{ field.default }}{% else %}False{% endif %})
+{% elif field.type == "datetime" %}
+    {{ field.name }} = models.DateTimeField({% if not field.required %}null=True, blank=True{% endif %})
+{% elif field.type == "date" %}
+    {{ field.name }} = models.DateField({% if not field.required %}null=True, blank=True{% endif %})
+{% elif field.type == "email" %}
+    {{ field.name }} = models.EmailField({% if not field.required %}blank=True, null=True{% endif %})
+{% elif field.type == "url" %}
+    {{ field.name }} = models.URLField({% if not field.required %}blank=True, null=True{% endif %})
+{% elif field.type == "json" %}
+    {{ field.name }} = models.JSONField(default=dict{% if not field.required %}, blank=True, null=True{% endif %})
+{% else %}
+    {{ field.name }} = models.CharField(max_length=255{% if not field.required %}, blank=True, null=True{% endif %})
+{% endif %}
+{% endfor %}
+{% for rel in entity.relationships %}
+{% if rel.kind == "belongs_to" %}
+    {{ rel.field_name }} = models.ForeignKey("{{ rel.target | capitalize }}", on_delete=models.SET_NULL, null=True, blank=True, related_name="{{ entity.name }}_set")
+{% endif %}
+{% endfor %}
+
+    STATUS_CHOICES = [
+{% for state in entity.states %}
+        ("{{ state }}", "{{ state }}"),
+{% endfor %}
+    ]
+    status = models.CharField(max_length=50, choices=STATUS_CHOICES, default="{{ entity.initial_state }}")
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["-updated_at"]
+
+    def __str__(self) -> str:
+        return f"{{ entity.display_name }} #{ '{' }self.pk{ '}' } [{ '{' }self.status{ '}' }]"
+
+
+{% endfor %}

hexdag_forge/templates/django_settings.py.j2

@@ -0,0 +1,63 @@
+"""Django settings for {{ profile.business_name }}.
+
+Auto-generated by hexdag-forge. Modify as needed.
+"""
+
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+
+SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "change-me-in-production")
+DEBUG = os.environ.get("DJANGO_DEBUG", "True").lower() in ("true", "1")
+ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "*").split(",")
+
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+]
+
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+]
+
+ROOT_URLCONF = "urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ],
+        },
+    },
+]
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": BASE_DIR / "db.sqlite3",
+    }
+}
+
+LANGUAGE_CODE = "en-us"
+TIME_ZONE = "UTC"
+USE_I18N = True
+USE_TZ = True
+STATIC_URL = "static/"
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

hexdag_forge/templates/django_urls.py.j2

@@ -0,0 +1,11 @@
+"""URL configuration for {{ profile.business_name }}.
+
+Auto-generated by hexdag-forge.
+"""
+
+from django.contrib import admin
+from django.urls import path
+
+urlpatterns = [
+    path("admin/", admin.site.urls),
+]

hexdag_forge/templates/pipeline.yaml.j2

@@ -0,0 +1,40 @@
+apiVersion: hexdag/v1
+kind: Pipeline
+metadata:
+  name: {{ entity.name }}-lifecycle
+  description: "Lifecycle pipeline for {{ entity.display_name }}"
+
+spec:
+  services:
+    db:
+      class: "services.{{ entity.name | capitalize }}Service"
+
+  nodes:
+    - kind: service_call_node
+      metadata:
+        name: get_{{ entity.name }}
+      spec:
+        service: db
+        method: get_{{ entity.name }}
+        input_mapping:
+          {{ entity.name }}_id: "$input.{{ entity.name }}_id"
+
+    - kind: expression_node
+      metadata:
+        name: validate_transition
+      spec:
+        expressions:
+          current_state: "get_{{ entity.name }}.status"
+          target_state: "$input.target_state"
+        output_fields: [current_state, target_state]
+
+    - kind: service_call_node
+      metadata:
+        name: do_transition
+      spec:
+        service: db
+        method: transition_{{ entity.name }}
+        input_mapping:
+          {{ entity.name }}_id: "$input.{{ entity.name }}_id"
+          to_state: "validate_transition.target_state"
+          reason: "$input.reason"

hexdag_forge/templates/service.py.j2

@@ -0,0 +1,97 @@
+"""Generated service for {{ entity.display_name }} entity.
+
+Auto-generated by hexdag-forge. CRUD methods are fully implemented.
+Domain-specific stubs (marked with NotImplementedError) should be filled
+in by a developer or the builder agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hexdag.kernel.service import Service, step, tool
+
+
+class {{ entity.name | capitalize }}Service(Service):
+    """Service for {{ entity.display_name }} operations.
+
+    {{ entity.description }}
+    """
+
+    def __init__(self, db: Any) -> None:
+        self._db = db
+
+    # ── CRUD (fully implemented) ──────────────────────────────
+
+    @tool
+    @step
+    async def create_{{ entity.name }}(self{% for field in entity.fields %}, {{ field.name }}: {{ field.type }}{% if not field.required %} | None = None{% endif %}{% endfor %}) -> dict:
+        """Create a new {{ entity.display_name }}.
+
+        Returns:
+            Dict with the created record ID and initial state.
+        """
+        data = {
+{% for field in entity.fields %}
+            "{{ field.name }}": {{ field.name }},
+{% endfor %}
+        }
+        record = await self._db.create("{{ entity.name }}", data, initial_state="{{ entity.initial_state }}")
+        return record
+
+    @tool
+    @step
+    async def get_{{ entity.name }}(self, {{ entity.name }}_id: str) -> dict:
+        """Get {{ entity.display_name }} by ID."""
+        return await self._db.get("{{ entity.name }}", {{ entity.name }}_id)
+
+    @tool
+    @step
+    async def list_{{ entity.name }}s(self, status: str | None = None, limit: int = 50) -> list[dict]:
+        """List {{ entity.display_name }} records, optionally filtered by status."""
+        return await self._db.list_all("{{ entity.name }}", status=status, limit=limit)
+
+    @tool
+    @step
+    async def update_{{ entity.name }}(self, {{ entity.name }}_id: str, **data: Any) -> dict:
+        """Update {{ entity.display_name }} fields."""
+        return await self._db.update("{{ entity.name }}", {{ entity.name }}_id, data)
+
+    @tool
+    @step
+    async def delete_{{ entity.name }}(self, {{ entity.name }}_id: str) -> dict:
+        """Delete {{ entity.display_name }} by ID."""
+        return await self._db.delete("{{ entity.name }}", {{ entity.name }}_id)
+
+    @tool
+    @step
+    async def transition_{{ entity.name }}(self, {{ entity.name }}_id: str, to_state: str, reason: str = "") -> dict:
+        """Transition {{ entity.display_name }} to a new state.
+
+        Valid transitions from each state:
+{% for from_state, to_states in entity.transitions.items() %}
+          {{ from_state }} → {{ to_states | join(", ") }}
+{% endfor %}
+        """
+        return await self._db.transition("{{ entity.name }}", {{ entity.name }}_id, to_state, reason=reason)
+
+{% for workflow in workflows %}
+    # ── Domain stub: {{ workflow }} ───────────────────────────
+
+    @step
+    async def {{ workflow | replace(" ", "_") | lower }}(self, {{ entity.name }}_id: str, **kwargs: Any) -> dict:
+        """{{ workflow }}.
+
+        TODO: Implement this method with actual business logic.
+        The builder agent or a developer should fill this in.
+
+        Args:
+            {{ entity.name }}_id: The {{ entity.display_name }} ID.
+            **kwargs: Additional parameters.
+
+        Returns:
+            Dict with operation result.
+        """
+        raise NotImplementedError("Implement: {{ workflow }}")
+
+{% endfor %}