flo-lang 0.1.0__py3-none-any.whl

flo/__init__.py

@@ -0,0 +1,12 @@
+"""FLO package public surface.
+
+Keep the package import lightweight: importing the top-level package should
+not import CLI-related heavy dependencies (like `click`). Use the console
+entrypoint (`flo`) or import from `flo.core.cli` explicitly where needed,
+instead of exposing CLI modules at package import time.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+

flo/adapters/__init__.py

@@ -0,0 +1,41 @@
+"""Adapters package: YAML/other input adapters for FLO."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+import yaml
+
+
+from .yaml_loader import load_adapter_from_yaml
+from .composition import resolve_includes
+
+
+def parse_adapter(content: str, source_path: str | None = None) -> Dict[str, Any]:
+	"""Parse adapter content and return a validated mapping.
+
+	This dispatcher currently supports YAML input via
+	`load_adapter_from_yaml`. The loader returns an `AdapterModel`
+	which we convert to a plain dict (`model_dump`) so downstream
+	compiler code can continue to operate on mappings.
+	"""
+	try:
+		model = load_adapter_from_yaml(content)
+	except ValueError:
+		# If the content is YAML mapping-shaped FLO, return it directly.
+		# Otherwise preserve the previous permissive text fallback.
+		parsed = yaml.safe_load(content)
+		if isinstance(parsed, dict):
+			return resolve_includes(parsed, source_path=source_path)
+		return {"name": "parsed", "content": content}
+
+	# `model` supports `model_dump()` for Pydantic compatibility
+	try:
+		return model.model_dump()
+	except Exception:
+		# Fallback: if the model does not implement `model_dump`, try
+		# converting via `dict()` for compatibility with lightweight
+		# fallback models.
+		return dict(model)
+
+
+__all__ = ["load_adapter_from_yaml", "parse_adapter"]

flo/adapters/composition.py

@@ -0,0 +1,211 @@
+"""Composition helpers for include-based FLO source documents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_RESOURCE_KEYS = ("materials", "equipment", "locations", "workers")
+_LIST_KEYS = ("steps", "transitions", "edges", "lanes")
+
+
+def resolve_includes(document: dict[str, Any], source_path: str | None = None) -> dict[str, Any]:
+    """Resolve include directives and return a composed mapping.
+
+    Include syntax:
+
+    includes:
+      - relative/or/absolute/path.yaml
+    """
+    root_path = Path(source_path).resolve() if source_path else None
+    return _compose_document(document=document, current_path=root_path, include_stack=[])
+
+
+def _compose_document(
+    document: dict[str, Any],
+    current_path: Path | None,
+    include_stack: list[Path],
+) -> dict[str, Any]:
+    include_paths = _normalize_include_entries(document)
+    composed: dict[str, Any] = {}
+
+    for include_ref in include_paths:
+        include_path = _resolve_include_path(include_ref=include_ref, current_path=current_path)
+        include_doc = _load_include_mapping(include_path=include_path, include_stack=include_stack)
+        nested = _compose_document(
+            document=include_doc,
+            current_path=include_path,
+            include_stack=[*include_stack, include_path],
+        )
+        composed = _merge_documents(base=composed, incoming=nested)
+
+    local = dict(document)
+    local.pop("include", None)
+    local.pop("includes", None)
+    composed = _merge_documents(base=composed, incoming=local)
+
+    _validate_unique_ids(composed)
+    return composed
+
+
+def _normalize_include_entries(document: dict[str, Any]) -> list[str]:
+    include_value = document.get("includes")
+    if include_value is None:
+        include_value = document.get("include")
+
+    if include_value is None:
+        return []
+
+    if isinstance(include_value, str):
+        text = include_value.strip()
+        return [text] if text else []
+
+    if not isinstance(include_value, list):
+        raise ValueError("include/includes must be a string or list of strings")
+
+    out: list[str] = []
+    for idx, entry in enumerate(include_value):
+        if not isinstance(entry, str) or not entry.strip():
+            raise ValueError(f"includes[{idx}] must be a non-empty string path")
+        out.append(entry.strip())
+    return out
+
+
+def _resolve_include_path(include_ref: str, current_path: Path | None) -> Path:
+    raw = Path(include_ref)
+    if raw.is_absolute():
+        return raw.resolve()
+
+    base_dir = current_path.parent if current_path is not None else Path.cwd()
+    return (base_dir / raw).resolve()
+
+
+def _load_include_mapping(include_path: Path, include_stack: list[Path]) -> dict[str, Any]:
+    if include_path in include_stack:
+        chain = " -> ".join(str(path) for path in [*include_stack, include_path])
+        raise ValueError(f"include cycle detected: {chain}")
+
+    if not include_path.exists():
+        raise ValueError(f"include file not found: {include_path}")
+
+    try:
+        content = include_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"unable to read include file '{include_path}': {exc}") from exc
+
+    parsed = yaml.safe_load(content)
+    if not isinstance(parsed, dict):
+        raise ValueError(f"include file '{include_path}' must contain a YAML mapping")
+
+    return parsed
+
+
+def _merge_documents(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+
+    for key, value in incoming.items():
+        if key in _LIST_KEYS:
+            merged[key] = _merge_list_values(key=key, base_value=merged.get(key), incoming_value=value)
+            continue
+
+        if key in _RESOURCE_KEYS:
+            merged[key] = _merge_resource_values(key=key, base_value=merged.get(key), incoming_value=value)
+            continue
+
+        if key == "process":
+            merged[key] = _merge_process(base_value=merged.get(key), incoming_value=value)
+            continue
+
+        if key == "spec_version":
+            merged.setdefault(key, value)
+            continue
+
+        merged[key] = value
+
+    return merged
+
+
+def _merge_list_values(key: str, base_value: Any, incoming_value: Any) -> list[Any]:
+    if incoming_value is None:
+        return list(base_value) if isinstance(base_value, list) else []
+    if not isinstance(incoming_value, list):
+        raise ValueError(f"{key} must be a list")
+
+    out: list[Any] = []
+    if isinstance(base_value, list):
+        out.extend(base_value)
+    elif base_value is not None:
+        raise ValueError(f"{key} must be a list")
+
+    out.extend(incoming_value)
+    return out
+
+
+def _merge_resource_values(key: str, base_value: Any, incoming_value: Any) -> Any:
+    if base_value is None:
+        return incoming_value
+    if incoming_value is None:
+        return base_value
+
+    if isinstance(base_value, list) and isinstance(incoming_value, list):
+        return [*base_value, *incoming_value]
+
+    if isinstance(base_value, dict) and isinstance(incoming_value, dict):
+        merged = dict(base_value)
+        for child_key, child_value in incoming_value.items():
+            if child_key == "name":
+                merged.setdefault("name", child_value)
+                continue
+            if child_key in merged:
+                merged[child_key] = _merge_resource_values(
+                    key=f"{key}.{child_key}",
+                    base_value=merged[child_key],
+                    incoming_value=child_value,
+                )
+            else:
+                merged[child_key] = child_value
+        return merged
+
+    raise ValueError(f"{key} include merge type mismatch: expected list/list or dict/dict")
+
+
+def _merge_process(base_value: Any, incoming_value: Any) -> Any:
+    if base_value is None:
+        return incoming_value
+    if incoming_value is None:
+        return base_value
+    if not isinstance(base_value, dict) or not isinstance(incoming_value, dict):
+        raise ValueError("process must be an object when present")
+
+    merged = dict(base_value)
+    for key, value in incoming_value.items():
+        if key == "metadata" and isinstance(merged.get("metadata"), dict) and isinstance(value, dict):
+            merged["metadata"] = {**merged["metadata"], **value}
+            continue
+        merged[key] = value
+    return merged
+
+
+def _validate_unique_ids(document: dict[str, Any]) -> None:
+    _ensure_unique_id_list(document=document, key="steps")
+    _ensure_unique_id_list(document=document, key="lanes")
+
+
+def _ensure_unique_id_list(document: dict[str, Any], key: str) -> None:
+    value = document.get(key)
+    if not isinstance(value, list):
+        return
+
+    seen: set[str] = set()
+    for idx, item in enumerate(value):
+        if not isinstance(item, dict):
+            continue
+        item_id = item.get("id")
+        if item_id is None:
+            continue
+        item_id_text = str(item_id)
+        if item_id_text in seen:
+            raise ValueError(f"duplicate {key[:-1]} id '{item_id_text}' detected at {key}[{idx}]")
+        seen.add(item_id_text)

flo/adapters/models.py

@@ -0,0 +1,20 @@
+"""Adapter models for FLO inputs.
+
+Prefer Pydantic v2 models for runtime validation and parsing. If
+Pydantic isn't available the module will still import but some helper
+callers may choose a dict-based fallback.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class AdapterModel(BaseModel):
+    """Pydantic-backed AdapterModel used for adapter inputs."""
+
+    name: str
+    content: str
+
+    # Pydantic v2 provides `model_validate` and `model_dump` so callers
+    # can use the same API as before without needing a runtime fallback.

flo/adapters/yaml_loader.py

@@ -0,0 +1,26 @@
+"""YAML adapter loader.
+
+Parses YAML content and returns an `AdapterModel` instance when
+Pydantic is available, otherwise returns a simple fallback model.
+"""
+from __future__ import annotations
+
+import yaml
+
+from .models import AdapterModel
+
+
+def load_adapter_from_yaml(content: str) -> AdapterModel:
+    """Parse YAML content and return an `AdapterModel`.
+
+    Expects the YAML to be a mapping containing at least `name` and
+    `content` keys. Returns an `AdapterModel` instance via the
+    model-compatible `model_validate` API (works with Pydantic and
+    our fallback model).
+    """
+    data = yaml.safe_load(content)
+    if not isinstance(data, dict):
+        raise ValueError("YAML content must be a mapping with keys 'name' and 'content'")
+
+    # Both the Pydantic model and our fallback implement `model_validate`.
+    return AdapterModel.model_validate(data)

flo/compiler/__init__.py

@@ -0,0 +1,7 @@
+"""Compiler package: transforms adapter models to canonical IR."""
+
+from __future__ import annotations
+
+from .compile import compile_adapter
+
+__all__ = ["compile_adapter"]

flo/compiler/analysis/__init__.py

@@ -0,0 +1,20 @@
+"""Analysis package nested under the compiler layer."""
+from .scc import scc_condense
+from .movement import (
+    infer_material_movements,
+    aggregate_material_movements,
+    infer_people_movements,
+    aggregate_people_movements,
+    aggregate_people_movements_by_worker,
+    extract_location_spatial_index,
+)
+
+__all__ = [
+    "scc_condense",
+    "infer_material_movements",
+    "aggregate_material_movements",
+    "infer_people_movements",
+    "aggregate_people_movements",
+    "aggregate_people_movements_by_worker",
+    "extract_location_spatial_index",
+]