telize 0.1.0__py3-none-any.whl

telize/__init__.py

@@ -0,0 +1,5 @@
+"""Telize — low-code agent framework."""
+
+from telize.__version__ import __version__
+
+__all__ = ["__version__"]

telize/__main__.py

@@ -0,0 +1,3 @@
+from telize.cli import main
+
+main()

telize/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

telize/cli.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from rich.console import Console
+
+from telize import __version__
+from telize.config import load_spec
+from telize.console import RichConsoleObserver, print_validation_ok
+from telize.exceptions import ConfigError, ExecutionError, TelizeError
+from telize.runtime import WorkflowRunner
+from telize.runtime.workflow_input import resolve_cli_workflow_input
+
+_ERR_CONSOLE = Console(stderr=True)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="telize",
+        description="Run agent workflows defined in YAML.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "-f",
+        "--file",
+        type=Path,
+        metavar="FILE",
+        help="Path to a workflow YAML file.",
+    )
+    parser.add_argument(
+        "--validate-only",
+        action="store_true",
+        help="Parse and validate the YAML without executing steps.",
+    )
+    parser.add_argument(
+        "--input",
+        action="append",
+        metavar="KEY=VALUE",
+        dest="input_pairs",
+        help=(
+            "Workflow input as key=value (repeatable). Merged with --input-file and --input-stdin."
+        ),
+    )
+    parser.add_argument(
+        "--input-file",
+        type=Path,
+        metavar="FILE",
+        help="YAML or JSON file with workflow input (mapping at root).",
+    )
+    parser.add_argument(
+        "--input-stdin",
+        action="store_true",
+        help="Read workflow input as YAML or JSON from stdin.",
+    )
+    return parser
+
+
+def _print_error(message: str) -> None:
+    _ERR_CONSOLE.print(f"[bold red]error[/]: {message}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.file is None:
+        parser.print_help()
+        sys.exit(0 if argv is not None else 1)
+
+    try:
+        spec = load_spec(args.file)
+        workflow_input = resolve_cli_workflow_input(
+            pairs=args.input_pairs,
+            input_file=args.input_file,
+            input_stdin=args.input_stdin,
+        )
+    except ConfigError as exc:
+        _print_error(str(exc))
+        sys.exit(1)
+
+    entrypoint = spec.config.entrypoint
+    flow = spec.flows[entrypoint]
+
+    if args.validate_only:
+        print_validation_ok(
+            workflow_file=args.file.resolve(),
+            entrypoint=entrypoint,
+            step_count=len(flow.steps),
+        )
+        sys.exit(0)
+
+    observer = RichConsoleObserver(spec, args.file.resolve())
+    try:
+        WorkflowRunner(
+            spec,
+            args.file.resolve(),
+            observer=observer,
+            workflow_input=workflow_input,
+        ).run()
+    except (ConfigError, ExecutionError) as exc:
+        _print_error(str(exc))
+        sys.exit(1)
+    except TelizeError as exc:
+        _print_error(str(exc))
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

telize/config/__init__.py

@@ -0,0 +1,21 @@
+from telize.config.loader import load_spec
+from telize.config.models import (
+    Flow,
+    GlobalConfig,
+    InputStep,
+    LlmStep,
+    ShellStep,
+    Step,
+    WorkflowSpec,
+)
+
+__all__ = [
+    "Flow",
+    "GlobalConfig",
+    "InputStep",
+    "LlmStep",
+    "ShellStep",
+    "Step",
+    "WorkflowSpec",
+    "load_spec",
+]

telize/config/loader.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from telize.config.models import WorkflowSpec
+from telize.exceptions import ConfigError, ExecutionError
+from telize.templating.load import render_env_templates
+
+
+def _apply_load_time_templates(raw: dict[str, Any]) -> dict[str, Any]:
+    """Expand `{{ env.* }}` in YAML before validation; leave runtime templates intact."""
+    try:
+        rendered = render_env_templates(raw)
+    except ExecutionError as exc:
+        raise ConfigError(str(exc)) from exc
+    if not isinstance(rendered, dict):
+        raise ConfigError("Expected a YAML mapping at the root after template rendering")
+    return rendered
+
+
+def load_spec(path: Path) -> WorkflowSpec:
+    """Load and validate a Telize workflow YAML file."""
+    if not path.is_file():
+        raise ConfigError(f"File not found: {path}")
+
+    try:
+        raw: Any = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Invalid YAML in {path}: {exc}") from exc
+
+    if raw is None:
+        raise ConfigError(f"Empty YAML file: {path}")
+    if not isinstance(raw, dict):
+        raise ConfigError(f"Expected a YAML mapping at the root of {path}")
+
+    raw = _apply_load_time_templates(raw)
+
+    try:
+        return WorkflowSpec.model_validate(raw)
+    except ValidationError as exc:
+        raise ConfigError(f"Invalid workflow spec in {path}:\n{exc}") from exc

telize/config/models/__init__.py

@@ -0,0 +1,27 @@
+from telize.config.models.actions import (
+    FlowRefStep,
+    InputStep,
+    LlmStep,
+    LoopConfig,
+    PythonStep,
+    ShellStep,
+    Step,
+    YamlStep,
+)
+from telize.config.models.config import GlobalConfig
+from telize.config.models.flow import Flow
+from telize.config.models.spec import WorkflowSpec
+
+__all__ = [
+    "Flow",
+    "FlowRefStep",
+    "GlobalConfig",
+    "InputStep",
+    "LlmStep",
+    "LoopConfig",
+    "PythonStep",
+    "ShellStep",
+    "Step",
+    "WorkflowSpec",
+    "YamlStep",
+]

telize/config/models/actions.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class LoopConfig(BaseModel):
+    """Iterate an LLM step over items produced from a prior step's output."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    items: str = Field(
+        description="Jinja template resolving to a delimited list (e.g. `{{ steps.foo.output }}`).",
+    )
+    split_by: str = Field(
+        default=",",
+        description="Delimiter used to split `items` into separate loop iterations.",
+    )
+    execution: Literal["sequential", "parallel"] = Field(
+        default="sequential",
+        description="How loop iterations are scheduled.",
+    )
+
+
+class DirectoryInput(BaseModel):
+    """Read and concatenate files from a directory."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    include: str = Field(default="*", description="Glob pattern for files to include.")
+
+
+class _StepBase(BaseModel):
+    """Fields shared by every step in a flow."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(
+        min_length=1,
+        description="Unique step id within the flow; referenced as `steps.<name>.output`.",
+    )
+
+
+class InputStep(_StepBase):
+    """Load content from a file or directory."""
+
+    uses: Literal["input"] = "input"
+    file: str | None = Field(default=None, description="Path to a single file to read.")
+    directory: DirectoryInput | None = None
+
+    @model_validator(mode="after")
+    def validate_source(self) -> InputStep:
+        has_file = self.file is not None
+        has_dir = self.directory is not None
+        if has_file == has_dir:
+            msg = "input step requires exactly one of 'file' or 'directory'"
+            raise ValueError(msg)
+        return self
+
+
+class LlmStep(_StepBase):
+    """Call an LLM with a Jinja-templated prompt."""
+
+    uses: Literal["llm"] = "llm"
+    prompt: str
+    output_to: str | None = Field(
+        default=None,
+        description="Optional path to write raw output after the step completes.",
+    )
+    loop: LoopConfig | None = None
+
+
+class ShellStep(_StepBase):
+    """Execute a shell script or command block."""
+
+    uses: Literal["shell"] = "shell"
+    run: str = Field(description="Shell commands to execute.")
+    envs: dict[str, str] = Field(
+        default_factory=dict,
+        description="Extra environment variables (values may be Jinja templates).",
+    )
+
+
+class PythonStep(_StepBase):
+    """Invoke a Python callable by import path."""
+
+    uses: Literal["python"] = "python"
+    call: str = Field(
+        description="Dotted import path to a callable, e.g. `package.module.function`.",
+    )
+    args: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Keyword arguments passed to the callable (values may be templates).",
+    )
+
+
+class FlowRefStep(_StepBase):
+    """Run another flow defined in the same workflow file."""
+
+    uses: Literal["flow"] = "flow"
+    run: str = Field(description="Name of the flow to execute.")
+
+
+class YamlStep(_StepBase):
+    """Run a workflow defined in an external YAML file."""
+
+    uses: Literal["yaml"] = "yaml"
+    file: str = Field(
+        description="Path to a Telize workflow YAML file relative to the workflow file.",
+    )
+    input: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Workflow input for the child file, rendered as Jinja in the parent then "
+            "passed as `{{ input.<key> }}` in the child."
+        ),
+    )
+
+
+Step = Annotated[
+    InputStep | LlmStep | ShellStep | PythonStep | FlowRefStep | YamlStep,
+    Field(discriminator="uses"),
+]

telize/config/models/config.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class GlobalConfig(BaseModel):
+    """Top-level defaults and entrypoint for a workflow file."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    model: str | None = Field(
+        default=None,
+        description="Default LLM model for steps that do not override it.",
+    )
+    temperature: float | None = Field(
+        default=None,
+        ge=0.0,
+        le=2.0,
+        description="Default sampling temperature.",
+    )
+    api_base_url: str = Field(
+        default="http://localhost:11434",
+        description="Ollama API base URL (default local instance).",
+    )
+    system_prompt: str | None = Field(
+        default=None,
+        description="System message for every llm step (Jinja-templated at runtime).",
+    )
+    entrypoint: str = Field(
+        description="Name of the flow in `flows` that runs when the file is executed.",
+    )

telize/config/models/flow.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from telize.config.models.actions import Step
+
+
+class Flow(BaseModel):
+    """A named workflow: ordered steps executed sequentially."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    steps: list[Step] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def validate_unique_step_names(self) -> Flow:
+        names = [step.name for step in self.steps]
+        if len(names) != len(set(names)):
+            duplicates = sorted({n for n in names if names.count(n) > 1})
+            msg = f"duplicate step name(s) in flow: {', '.join(duplicates)}"
+            raise ValueError(msg)
+        return self

telize/config/models/spec.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from telize.config.models.actions import FlowRefStep, Step
+from telize.config.models.config import GlobalConfig
+from telize.config.models.flow import Flow
+
+
+class WorkflowSpec(BaseModel):
+    """Root document loaded from a Telize workflow YAML file."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    config: GlobalConfig
+    flows: dict[str, Flow]
+
+    @model_validator(mode="after")
+    def validate_entrypoint(self) -> WorkflowSpec:
+        if self.config.entrypoint not in self.flows:
+            known = ", ".join(sorted(self.flows))
+            msg = (
+                f"config.entrypoint '{self.config.entrypoint}' not found in flows. "
+                f"Known flows: {known or '(none)'}"
+            )
+            raise ValueError(msg)
+        return self
+
+    @model_validator(mode="after")
+    def validate_flow_references(self) -> WorkflowSpec:
+        for flow_name, flow in self.flows.items():
+            for step in flow.steps:
+                if isinstance(step, FlowRefStep) and step.run not in self.flows:
+                    msg = (
+                        f"flow '{flow_name}' step '{step.name}' references unknown flow "
+                        f"'{step.run}'"
+                    )
+                    raise ValueError(msg)
+        return self
+
+    def get_step(self, flow_name: str, step_name: str) -> Step | None:
+        flow = self.flows.get(flow_name)
+        if flow is None:
+            return None
+        for step in flow.steps:
+            if step.name == step_name:
+                return step
+        return None

telize/console/__init__.py

@@ -0,0 +1,13 @@
+from telize.console.display import (
+    get_console,
+    print_validation_ok,
+    print_workflow_results,
+)
+from telize.console.observer import RichConsoleObserver
+
+__all__ = [
+    "RichConsoleObserver",
+    "get_console",
+    "print_validation_ok",
+    "print_workflow_results",
+]

telize/console/display.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.rule import Rule
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.text import Text
+
+from telize.config.models import WorkflowSpec
+from telize.runtime.state import ExecutionState, StepResult
+
+_CONSOLE: Console | None = None
+
+ACTION_LABELS: dict[str, tuple[str, str]] = {
+    "llm": ("LLM", "bold magenta"),
+    "shell": ("SHELL", "bold yellow"),
+    "python": ("PYTHON", "bold cyan"),
+    "input": ("INPUT", "bold green"),
+    "flow": ("FLOW", "bold red"),
+    "yaml": ("YAML", "bold blue"),
+}
+
+
+def get_console() -> Console:
+    global _CONSOLE
+    if _CONSOLE is None:
+        _CONSOLE = Console(highlight=False)
+    return _CONSOLE
+
+
+def print_validation_ok(
+    *,
+    workflow_file: Path,
+    entrypoint: str,
+    step_count: int,
+) -> None:
+    console = get_console()
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style="dim")
+    table.add_column()
+    table.add_row("File", str(workflow_file))
+    table.add_row("Entrypoint", f"[cyan]{entrypoint}[/]")
+    table.add_row("Steps", str(step_count))
+    console.print(
+        Panel(
+            table,
+            title="[bold green]✓ Valid workflow[/]",
+            border_style="green",
+            padding=(1, 2),
+        )
+    )
+
+
+def print_workflow_header(
+    spec_path: Path,
+    entrypoint: str,
+    model: str | None,
+    api_base_url: str,
+    *,
+    estimated_steps: int,
+) -> None:
+    console = get_console()
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style="dim", no_wrap=True)
+    table.add_column()
+    table.add_row("Workflow", f"[bold]{spec_path.name}[/]")
+    table.add_row("Entrypoint", f"[cyan]{entrypoint}[/]")
+    if model:
+        table.add_row("Model", model)
+    table.add_row("Ollama", api_base_url)
+    table.add_row("Steps", str(estimated_steps))
+    console.print()
+    console.print(
+        Panel(
+            table,
+            title="[bold #a371f7]◈ Telize[/]  [dim]running workflow[/]",
+            border_style="#a371f7",
+            padding=(1, 2),
+        )
+    )
+    console.print()
+
+
+def print_step_panel(result: StepResult, *, index: int) -> None:
+    get_console().print(_build_step_panel(result, index=index))
+
+
+def print_workflow_results(
+    spec: WorkflowSpec,
+    spec_path: Path,
+    state: ExecutionState,
+    *,
+    entrypoint: str,
+    elapsed: float,
+) -> None:
+    """Print all step results at once (used in tests and replay tooling)."""
+    console = get_console()
+    cfg = spec.config
+
+    print_workflow_header(
+        spec_path,
+        entrypoint,
+        cfg.model,
+        cfg.api_base_url,
+        estimated_steps=len(state.steps),
+    )
+
+    for index, result in enumerate(state.steps.values(), start=1):
+        print_step_panel(result, index=index)
+        console.print()
+
+    console.print(
+        Rule(
+            f"[green]{len(state.steps)} step(s)[/] in [cyan]{elapsed:.1f}s[/]",
+            style="dim",
+        )
+    )
+
+
+def _build_step_panel(result: StepResult, *, index: int) -> Panel:
+    uses = result.uses or "step"
+    label, style = ACTION_LABELS.get(uses, (uses.upper(), "bold white"))
+    title = Text()
+    title.append(f"{index:02d} ", style="dim")
+    title.append(f"{result.name} ", style="bold")
+    title.append(label, style=style)
+    if result.flow_name:
+        title.append(f"  ·  {result.flow_name}", style="dim")
+
+    subtitle_parts: list[str] = []
+    if result.output_path:
+        subtitle_parts.append(f"→ {result.output_path}")
+    subtitle = "  ".join(subtitle_parts)
+
+    if result.output:
+        body = _render_step_body(result.output, uses)
+    else:
+        body = Text("(no output)", style="dim")
+
+    return Panel(
+        body,
+        title=title,
+        subtitle=subtitle if subtitle else None,
+        border_style=_panel_border(uses),
+        padding=(1, 2),
+    )
+
+
+def _panel_border(uses: str) -> str:
+    return {
+        "llm": "magenta",
+        "shell": "yellow",
+        "python": "cyan",
+        "input": "green",
+        "flow": "red",
+        "yaml": "blue",
+    }.get(uses, "white")
+
+
+def _render_step_body(output: str, uses: str) -> Markdown | Syntax | Text:
+    text = output.rstrip()
+    if not text:
+        return Text("")
+
+    if uses == "shell":
+        return Text(text)
+    if uses == "yaml":
+        return Syntax(text, "yaml", theme="monokai", word_wrap=True)
+    if uses == "python":
+        return Syntax(text, "python", theme="monokai", word_wrap=True)
+    if uses == "llm" or (uses == "input" and _looks_like_markdown(text)):
+        return _as_markdown(text)
+    return Text(text)
+
+
+def _looks_like_markdown(text: str) -> bool:
+    markers = ("# ", "## ", "- ", "* ", "```", "**", "\n- ", "\n* ")
+    return any(marker in text for marker in markers)
+
+
+def _as_markdown(content: str) -> Markdown | Text:
+    try:
+        return Markdown(content)
+    except Exception:
+        return Text(content)