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

hexdag_forge/__init__.py

@@ -0,0 +1,3 @@
+"""hexdag-forge — Build operational systems from prompts."""
+
+__version__ = "0.1.0"

hexdag_forge/cli.py

@@ -0,0 +1,71 @@
+"""CLI entry point for hexdag-forge — a code generator for operational systems."""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003 — needed at runtime by typer
+from typing import Annotated
+
+import typer
+
+app = typer.Typer(
+    name="hexdag-forge",
+    help="Generate operational systems from prompts — powered by hexDAG",
+    no_args_is_help=True,
+)
+
+mcp_app = typer.Typer(help="MCP server commands")
+app.add_typer(mcp_app, name="mcp")
+
+
+@app.command()
+def generate(
+    description: Annotated[str, typer.Argument(help="Business description")],
+    output: Annotated[
+        Path, typer.Option(help="Output directory for generated files")
+    ] = "./generated",
+) -> None:
+    """Generate an operational system from a business description."""
+    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)
+    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")
+    typer.echo(f"  Services: {len(result.services)} files")
+
+
+@app.command()
+def validate(
+    output: Annotated[Path, typer.Argument(help="Path to generated system")],
+) -> None:
+    """Validate generated files (YAML pipelines, Python syntax, system manifest)."""
+    from hexdag_forge.generator.assembler import validate_system
+
+    errors = validate_system(output_dir=output)
+    if errors:
+        for err in errors:
+            typer.echo(f"  ERROR: {err}", err=True)
+        raise typer.Exit(1)
+    typer.echo("All generated files are valid.")
+
+
+@mcp_app.command("serve")
+def mcp_serve(
+    transport: Annotated[str, typer.Option(help="Transport: stdio or sse")] = "stdio",
+    port: Annotated[int, typer.Option(help="Port for SSE transport")] = 3001,
+) -> None:
+    """Start the forge MCP server for Claude Code integration."""
+    from hexdag_forge.mcp.server import run_server
+
+    run_server(transport=transport, port=port)
+
+
+def main() -> None:
+    """Entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

hexdag_forge/domain/__init__.py

@@ -0,0 +1,20 @@
+"""Domain models for hexdag-forge."""
+
+from hexdag_forge.domain.business_profile import (
+    BusinessProfile,
+    EntitySpec,
+    FieldSpec,
+    RelationshipSpec,
+)
+from hexdag_forge.domain.enums import FieldType, RelationshipKind
+from hexdag_forge.domain.generated_system import GeneratedSystem
+
+__all__ = [
+    "BusinessProfile",
+    "EntitySpec",
+    "FieldSpec",
+    "FieldType",
+    "GeneratedSystem",
+    "RelationshipKind",
+    "RelationshipSpec",
+]

hexdag_forge/domain/business_profile.py

@@ -0,0 +1,100 @@
+"""Domain models for business profiles and entity specifications."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, field_validator
+
+
+class FieldSpec(BaseModel):
+    """Specification for a single field on an entity."""
+
+    name: str
+    type: str = "str"
+    required: bool = True
+    default: Any = None
+    description: str = ""
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        if not v.isidentifier():
+            msg = f"Field name must be a valid Python identifier, got: {v!r}"
+            raise ValueError(msg)
+        return v
+
+
+class RelationshipSpec(BaseModel):
+    """Specification for a relationship between entities."""
+
+    target: str
+    kind: str = "belongs_to"
+    field_name: str
+    description: str = ""
+
+    @field_validator("kind")
+    @classmethod
+    def validate_kind(cls, v: str) -> str:
+        valid = {"belongs_to", "has_many", "has_one"}
+        if v not in valid:
+            msg = f"Relationship kind must be one of {valid}, got: {v!r}"
+            raise ValueError(msg)
+        return v
+
+
+class EntitySpec(BaseModel):
+    """Specification for an entity type in the generated system."""
+
+    name: str
+    display_name: str
+    fields: list[FieldSpec]
+    relationships: list[RelationshipSpec] = []
+    states: list[str]
+    initial_state: str
+    transitions: dict[str, list[str]]
+    description: str = ""
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        if not v.isidentifier():
+            msg = f"Entity name must be a valid Python identifier, got: {v!r}"
+            raise ValueError(msg)
+        return v
+
+    @field_validator("initial_state")
+    @classmethod
+    def validate_initial_state(cls, v: str, info: Any) -> str:
+        states = info.data.get("states", [])
+        if states and v not in states:
+            msg = f"Initial state {v!r} must be one of the declared states: {states}"
+            raise ValueError(msg)
+        return v
+
+    @field_validator("transitions")
+    @classmethod
+    def validate_transitions(cls, v: dict[str, list[str]], info: Any) -> dict[str, list[str]]:
+        states = set(info.data.get("states", []))
+        if not states:
+            return v
+        for from_state, to_states in v.items():
+            if from_state not in states:
+                msg = f"Transition source state {from_state!r} not in declared states"
+                raise ValueError(msg)
+            for to_state in to_states:
+                if to_state not in states:
+                    msg = f"Transition target state {to_state!r} not in declared states"
+                    raise ValueError(msg)
+        return v
+
+
+class BusinessProfile(BaseModel):
+    """Complete business profile extracted from a natural language description."""
+
+    business_name: str
+    business_type: str
+    description: str
+    entities: list[EntitySpec]
+    workflows: list[str] = []
+    modules: list[str] = []

hexdag_forge/domain/enums.py

@@ -0,0 +1,29 @@
+"""Enums for hexdag-forge domain models."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class FieldType(StrEnum):
+    """Supported field types for entity fields."""
+
+    STR = "str"
+    INT = "int"
+    FLOAT = "float"
+    DECIMAL = "Decimal"
+    BOOL = "bool"
+    DATETIME = "datetime"
+    DATE = "date"
+    TEXT = "text"
+    EMAIL = "email"
+    URL = "url"
+    JSON = "json"
+
+
+class RelationshipKind(StrEnum):
+    """Types of entity relationships."""
+
+    BELONGS_TO = "belongs_to"
+    HAS_MANY = "has_many"
+    HAS_ONE = "has_one"

hexdag_forge/domain/generated_system.py

@@ -0,0 +1,23 @@
+"""Domain model for a fully generated operational system."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from hexdag_forge.domain.business_profile import BusinessProfile  # noqa: TC001
+
+
+class GeneratedSystem(BaseModel):
+    """The complete output artifact of the forge generation process.
+
+    Contains the business profile that was analyzed, plus all generated
+    artifacts: YAML pipelines, Python service source code, Django model
+    source (for export), state machine configs, and the system manifest.
+    """
+
+    profile: BusinessProfile
+    pipelines: dict[str, str] = {}
+    services: dict[str, str] = {}
+    models_source: dict[str, str] = {}
+    state_machines: dict[str, dict] = {}
+    system_yaml: str = ""

hexdag_forge/generator/__init__.py

@@ -0,0 +1 @@
+"""hexdag-forge generator engine — transforms BusinessProfile into runnable code."""

hexdag_forge/generator/assembler.py

@@ -0,0 +1,121 @@
+"""Assembler — orchestrates all generators and writes output files.
+
+This is the main entry point for code generation. It takes a BusinessProfile
+(from LLM analysis or manual construction) and produces a complete runnable
+system in the output directory.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from hexdag_forge.domain.business_profile import BusinessProfile
+from hexdag_forge.domain.generated_system import GeneratedSystem
+from hexdag_forge.generator.django_generator import generate_django
+from hexdag_forge.generator.pipeline_generator import generate_pipelines
+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:
+    """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.
+
+    Returns:
+        GeneratedSystem with metadata about what was generated.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate all artifacts
+    pipelines = generate_pipelines(profile)
+    services = generate_services(profile)
+    system_yaml = generate_system(profile)
+    django_files = generate_django(profile)
+
+    # Write pipelines
+    pipelines_dir = output_dir / "pipelines"
+    pipelines_dir.mkdir(exist_ok=True)
+    for filename, content in pipelines.items():
+        (pipelines_dir / filename).write_text(content)
+
+    # Write services
+    services_dir = output_dir / "services"
+    services_dir.mkdir(exist_ok=True)
+    for filename, content in services.items():
+        (services_dir / filename).write_text(content)
+
+    # Write system manifest
+    (output_dir / "system.yaml").write_text(system_yaml)
+
+    # Write Django files
+    for rel_path, content in django_files.items():
+        file_path = output_dir / rel_path
+        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 profile.json for refinement
+    (output_dir / "profile.json").write_text(profile.model_dump_json(indent=2))
+
+    return GeneratedSystem(
+        profile=profile,
+        pipelines=pipelines,
+        services=services,
+        models_source={"models/models.py": django_files["models/models.py"]},
+        state_machines={e.name: e.transitions for e in profile.entities},
+        system_yaml=system_yaml,
+    )
+
+
+def validate_system(output_dir: Path) -> list[str]:
+    """Validate all generated files in an output directory.
+
+    Returns:
+        List of error messages. Empty list means valid.
+    """
+    errors: list[str] = []
+    output_dir = Path(output_dir)
+
+    # Check required files exist
+    required = ["system.yaml", "profile.json", "settings.py", "manage.py"]
+    errors.extend(f"Missing required file: {f}" for f in required if not (output_dir / f).exists())
+
+    # Check pipelines directory
+    pipelines_dir = output_dir / "pipelines"
+    if not pipelines_dir.exists():
+        errors.append("Missing pipelines/ directory")
+    elif not list(pipelines_dir.glob("*.yaml")):
+        errors.append("No YAML files in pipelines/")
+
+    # Check services directory
+    services_dir = output_dir / "services"
+    if not services_dir.exists():
+        errors.append("Missing services/ directory")
+    elif not list(services_dir.glob("*.py")):
+        errors.append("No Python files in services/")
+
+    # Validate Python syntax
+    for py_file in output_dir.rglob("*.py"):
+        try:
+            import ast
+
+            ast.parse(py_file.read_text())
+        except SyntaxError as e:
+            errors.append(f"Syntax error in {py_file.relative_to(output_dir)}: {e}")
+
+    # Validate profile.json
+    profile_path = output_dir / "profile.json"
+    if profile_path.exists():
+        try:
+            profile_data = json.loads(profile_path.read_text())
+            BusinessProfile.model_validate(profile_data)
+        except Exception as e:
+            errors.append(f"Invalid profile.json: {e}")
+
+    return errors

hexdag_forge/generator/business_analyzer.py

@@ -0,0 +1,161 @@
+"""LLM-powered business analysis — prompt → BusinessProfile.
+
+Uses hexDAG's LLM port to extract entities, fields, states,
+transitions, and relationships from a natural language description.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from hexdag_forge.domain.business_profile import BusinessProfile, EntitySpec, FieldSpec
+
+# System prompt for the LLM
+_SYSTEM_PROMPT = """You are a business systems architect. Given a business description,
+extract the operational entities, their fields, state machines, and relationships.
+
+Return a JSON object with this exact structure:
+{
+    "business_name": "short name",
+    "business_type": "freight_brokerage|retail|saas|pharma_sales"
+                     "|manufacturing|services|logistics|general",
+    "entities": [
+        {
+            "name": "snake_case_name",
+            "display_name": "Human Name",
+            "description": "what this entity represents",
+            "fields": [
+                {"name": "field_name",
+                 "type": "str|int|float|Decimal|bool|datetime|date|text|email|url",
+                 "required": true, "description": "..."}
+            ],
+            "relationships": [
+                {"target": "other_entity_name",
+                 "kind": "belongs_to|has_many|has_one",
+                 "field_name": "fk_field_name"}
+            ],
+            "states": ["STATE_A", "STATE_B", "STATE_C"],
+            "initial_state": "STATE_A",
+            "transitions": {
+                "STATE_A": ["STATE_B", "STATE_C"],
+                "STATE_B": ["STATE_C"]
+            }
+        }
+    ],
+    "workflows": ["short description of a business process that needs custom logic"],
+    "modules": ["what modules this system covers"]
+}
+
+Rules:
+- Entity names must be valid Python identifiers (snake_case)
+- Every entity must have at least 2 states and a valid initial_state
+- Transitions must only reference declared states
+- Include at least id-like fields and status-relevant fields
+- workflows should describe domain-specific logic that needs custom code (not CRUD)
+- Be thorough but practical — extract the entities that actually matter for operations"""
+
+_REFINE_PROMPT = """You are refining an existing business profile. The current profile is:
+
+{current_profile}
+
+The user wants to make this change:
+{refinement}
+
+Return the COMPLETE updated profile JSON (same structure as before), incorporating the change.
+Only modify what the user asked for. Keep everything else the same."""
+
+
+async def analyze_business(description: str, llm_adapter: Any) -> BusinessProfile:
+    """Analyze a business description and extract a BusinessProfile.
+
+    Args:
+        description: Natural language business description.
+        llm_adapter: Any hexDAG LLM adapter (OpenAI, Anthropic, mock, etc.)
+
+    Returns:
+        Validated BusinessProfile.
+    """
+    messages = [
+        {"role": "system", "content": _SYSTEM_PROMPT},
+        {"role": "user", "content": description},
+    ]
+    response = await llm_adapter.aresponse(messages)
+    profile_data = _parse_json_response(response)
+    profile_data["description"] = description
+    return BusinessProfile.model_validate(profile_data)
+
+
+async def refine_profile(
+    profile: BusinessProfile,
+    refinement: str,
+    llm_adapter: Any,
+) -> BusinessProfile:
+    """Refine an existing BusinessProfile with additional instructions.
+
+    Args:
+        profile: Current BusinessProfile.
+        refinement: What to change.
+        llm_adapter: Any hexDAG LLM adapter.
+
+    Returns:
+        Updated BusinessProfile.
+    """
+    current_json = profile.model_dump_json(indent=2)
+    prompt = _REFINE_PROMPT.format(current_profile=current_json, refinement=refinement)
+
+    messages = [
+        {"role": "system", "content": _SYSTEM_PROMPT},
+        {"role": "user", "content": prompt},
+    ]
+    response = await llm_adapter.aresponse(messages)
+    profile_data = _parse_json_response(response)
+    profile_data.setdefault("description", profile.description)
+    return BusinessProfile.model_validate(profile_data)
+
+
+def create_default_profile(description: str) -> BusinessProfile:
+    """Create a minimal default profile when no LLM is available.
+
+    Useful for testing or offline mode.
+    """
+    return BusinessProfile(
+        business_name="My Business",
+        business_type="general",
+        description=description,
+        entities=[
+            EntitySpec(
+                name="item",
+                display_name="Item",
+                fields=[
+                    FieldSpec(name="name", type="str", required=True),
+                    FieldSpec(name="description", type="text", required=False),
+                ],
+                states=["DRAFT", "ACTIVE", "COMPLETED", "ARCHIVED"],
+                initial_state="DRAFT",
+                transitions={
+                    "DRAFT": ["ACTIVE", "ARCHIVED"],
+                    "ACTIVE": ["COMPLETED", "ARCHIVED"],
+                    "COMPLETED": ["ARCHIVED"],
+                },
+            )
+        ],
+        workflows=[],
+        modules=["general"],
+    )
+
+
+def _parse_json_response(response: str) -> dict:
+    """Extract JSON from LLM response, handling markdown code blocks."""
+    text = response.strip()
+    # Handle ```json ... ``` blocks
+    if "```" in text:
+        start = text.find("```")
+        end = text.rfind("```")
+        if start != end:
+            block = text[start:end]
+            # Remove ```json or ``` prefix
+            first_newline = block.find("\n")
+            if first_newline != -1:
+                text = block[first_newline + 1 :]
+    return json.loads(text)

hexdag_forge/generator/django_generator.py

@@ -0,0 +1,27 @@
+"""Generate Django project files from a BusinessProfile."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hexdag_forge.generator.template_engine import render_template
+
+if TYPE_CHECKING:
+    from hexdag_forge.domain.business_profile import BusinessProfile
+
+
+def generate_django(profile: BusinessProfile) -> dict[str, str]:
+    """Generate Django models, settings, urls, admin, and manage.py.
+
+    Returns:
+        Dict of relative path -> file content.
+    """
+    files: dict[str, str] = {
+        "models/models.py": render_template("django_model.py.j2", profile=profile),
+        "settings.py": render_template("django_settings.py.j2", profile=profile),
+        "urls.py": render_template("django_urls.py.j2", profile=profile),
+        "admin.py": render_template("django_admin.py.j2", profile=profile),
+        "manage.py": render_template("django_manage.py.j2", profile=profile),
+        "state_machines.py": render_template("state_machines.py.j2", profile=profile),
+    }
+    return files

hexdag_forge/generator/entity_generator.py

@@ -0,0 +1,18 @@
+"""Generate StateMachineConfig definitions from a BusinessProfile."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from hexdag_forge.domain.business_profile import BusinessProfile, EntitySpec
+
+
+def detect_terminal_states(entity: EntitySpec) -> list[str]:
+    """Detect terminal states — states with no outgoing transitions."""
+    return [s for s in entity.states if s not in entity.transitions or not entity.transitions[s]]
+
+
+def generate_terminal_states_map(profile: BusinessProfile) -> dict[str, list[str]]:
+    """Return {entity_name: [terminal_states]} for all entities."""
+    return {entity.name: detect_terminal_states(entity) for entity in profile.entities}

hexdag_forge/generator/pipeline_generator.py

@@ -0,0 +1,24 @@
+"""Generate YAML pipeline files from a BusinessProfile."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hexdag_forge.generator.template_engine import render_template
+
+if TYPE_CHECKING:
+    from hexdag_forge.domain.business_profile import BusinessProfile
+
+
+def generate_pipelines(profile: BusinessProfile) -> dict[str, str]:
+    """Generate a lifecycle pipeline YAML file per entity.
+
+    Returns:
+        Dict of filename -> YAML content.
+    """
+    pipelines: dict[str, str] = {}
+    for entity in profile.entities:
+        filename = f"{entity.name}_lifecycle.yaml"
+        content = render_template("pipeline.yaml.j2", entity=entity)
+        pipelines[filename] = content
+    return pipelines

hexdag_forge/generator/service_generator.py

@@ -0,0 +1,55 @@
+"""Generate Python service files from a BusinessProfile."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hexdag_forge.generator.template_engine import render_template
+
+if TYPE_CHECKING:
+    from hexdag_forge.domain.business_profile import BusinessProfile
+
+
+def generate_services(profile: BusinessProfile) -> dict[str, str]:
+    """Generate a hexDAG Service class per entity.
+
+    Each service has:
+    - Fully implemented CRUD methods (@tool/@step)
+    - Domain-specific stub methods (NotImplementedError) from workflow descriptions
+
+    Returns:
+        Dict of filename -> Python source code.
+    """
+    services: dict[str, str] = {}
+
+    # Associate workflows with entities by keyword matching
+    entity_workflows = _match_workflows_to_entities(profile)
+
+    for entity in profile.entities:
+        filename = f"{entity.name}_service.py"
+        workflows = entity_workflows.get(entity.name, [])
+        content = render_template("service.py.j2", entity=entity, workflows=workflows)
+        services[filename] = content
+
+    return services
+
+
+def _match_workflows_to_entities(profile: BusinessProfile) -> dict[str, list[str]]:
+    """Simple keyword matching: assign workflows to entities they mention."""
+    result: dict[str, list[str]] = {e.name: [] for e in profile.entities}
+
+    for workflow in profile.workflows:
+        workflow_lower = workflow.lower()
+        matched = False
+        for entity in profile.entities:
+            if (
+                entity.name.lower() in workflow_lower
+                or entity.display_name.lower() in workflow_lower
+            ):
+                result[entity.name].append(workflow)
+                matched = True
+        # If no entity matched, assign to first entity as a catch-all
+        if not matched and profile.entities:
+            result[profile.entities[0].name].append(workflow)
+
+    return result

hexdag_forge/generator/system_generator.py

@@ -0,0 +1,21 @@
+"""Generate kind: System YAML manifest from a BusinessProfile."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hexdag_forge.generator.entity_generator import generate_terminal_states_map
+from hexdag_forge.generator.template_engine import render_template
+
+if TYPE_CHECKING:
+    from hexdag_forge.domain.business_profile import BusinessProfile
+
+
+def generate_system(profile: BusinessProfile) -> str:
+    """Generate the kind: System YAML manifest.
+
+    Uses LifecycleRunner (because state_machines is declared).
+    Each entity state maps to a process pipeline via on_enter.
+    """
+    terminal_states = generate_terminal_states_map(profile)
+    return render_template("system.yaml.j2", profile=profile, terminal_states=terminal_states)