hexdag-forge 0.2.0.dev2__tar.gz

hexdag_forge-0.2.0.dev2/.gitignore

@@ -0,0 +1,102 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+.pytest_cache/
+.tox/
+coverage.xml
+*.cover
+.hypothesis/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Database
+*.db
+*.sqlite3
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment variables
+.env.*
+!.env.example
+
+# uv
+uv.lock
+
+# Development
+.pre-commit-config.yaml.bak
+outputs/
+sbom.json
+
+# MkDocs
+site/
+docs/reference/*.md
+docs/namespaces/*.md
+
+# HexDAG config (only in root, not in subdirectories or examples)
+/hexdag.toml
+
+# Plugin build artifacts
+hexdag_plugins/*/.ruff_cache/
+hexdag_plugins/*/__pycache__/
+hexdag_plugins/*/.mypy_cache/
+hexdag_plugins/*/.pytest_cache/
+hexdag_plugins/*/dist/
+hexdag_plugins/*/build/
+hexdag_plugins/*/*.egg-info/
+
+# Studio UI (React/Vite)
+hexdag/studio/ui/node_modules/
+hexdag/studio/ui/dist/
+hexdag/studio/ui/.vite/
+
+# hexdag-studio standalone package (UI)
+hexdag-studio/ui/node_modules/
+hexdag-studio/ui/.vite/

hexdag_forge-0.2.0.dev2/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2024-2026 Omniviser
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hexdag_forge-0.2.0.dev2/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: hexdag-forge
+Version: 0.2.0.dev2
+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, runnable system with YAML pipelines, Python services, Django models, and a `kind: System` manifest.
+
+```bash
+pip install hexdag-forge
+
+hexdag-forge generate "I run a freight brokerage that matches shippers with carriers"
+```
+
+Output:
+```
+./generated/
+├── system.yaml              # kind: System manifest (LifecycleRunner)
+├── pipelines/
+│   ├── load_lifecycle.yaml   # Pipeline per entity lifecycle
+│   └── escalation.yaml
+├── services/
+│   └── freight_service.py    # @tool/@step CRUD + domain stubs
+├── models/
+│   └── models.py             # Django models
+├── state_machines.py         # StateMachineConfig definitions
+├── manage.py                 # Django manage.py
+├── settings.py               # Django settings
+├── urls.py                   # URL config
+├── admin.py                  # Admin registration
+└── profile.json              # BusinessProfile (for refinement)
+```
+
+## 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** — proper 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
+
+## CLI
+
+```bash
+# Generate from prompt
+hexdag-forge generate "I run a freight brokerage" --output ./my-erp/
+
+# Refine existing system
+hexdag-forge refine ./my-erp/ "Add an Escalation entity with severity field"
+
+# Validate generated files
+hexdag-forge validate ./my-erp/
+
+# MCP server for Claude Code
+hexdag-forge mcp serve
+```
+
+## MCP + Claude Code
+
+```bash
+hexdag-forge mcp serve
+```
+
+Skills:
+- `/forge "I run a freight brokerage"` — generate system
+- `/forge:entity "add Carrier with mc_number, score"` — add entity
+- `/forge:implement "fill in negotiate_rate"` — implement stub
+
+## License
+
+Apache 2.0

hexdag_forge-0.2.0.dev2/README.md

@@ -0,0 +1,67 @@
+# hexDAG Forge
+
+**Generate operational systems from prompts.** Describe your business → get a complete, runnable system with YAML pipelines, Python services, Django models, and a `kind: System` manifest.
+
+```bash
+pip install hexdag-forge
+
+hexdag-forge generate "I run a freight brokerage that matches shippers with carriers"
+```
+
+Output:
+```
+./generated/
+├── system.yaml              # kind: System manifest (LifecycleRunner)
+├── pipelines/
+│   ├── load_lifecycle.yaml   # Pipeline per entity lifecycle
+│   └── escalation.yaml
+├── services/
+│   └── freight_service.py    # @tool/@step CRUD + domain stubs
+├── models/
+│   └── models.py             # Django models
+├── state_machines.py         # StateMachineConfig definitions
+├── manage.py                 # Django manage.py
+├── settings.py               # Django settings
+├── urls.py                   # URL config
+├── admin.py                  # Admin registration
+└── profile.json              # BusinessProfile (for refinement)
+```
+
+## 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** — proper 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
+
+## CLI
+
+```bash
+# Generate from prompt
+hexdag-forge generate "I run a freight brokerage" --output ./my-erp/
+
+# Refine existing system
+hexdag-forge refine ./my-erp/ "Add an Escalation entity with severity field"
+
+# Validate generated files
+hexdag-forge validate ./my-erp/
+
+# MCP server for Claude Code
+hexdag-forge mcp serve
+```
+
+## MCP + Claude Code
+
+```bash
+hexdag-forge mcp serve
+```
+
+Skills:
+- `/forge "I run a freight brokerage"` — generate system
+- `/forge:entity "add Carrier with mc_number, score"` — add entity
+- `/forge:implement "fill in negotiate_rate"` — implement stub
+
+## License
+
+Apache 2.0

hexdag_forge-0.2.0.dev2/hexdag_forge/__init__.py

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

hexdag_forge-0.2.0.dev2/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-0.2.0.dev2/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-0.2.0.dev2/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-0.2.0.dev2/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-0.2.0.dev2/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-0.2.0.dev2/hexdag_forge/generator/__init__.py

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

hexdag_forge-0.2.0.dev2/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