telize 0.2.3

Automate with flows, not loose prompts. Chain LLM, shell, and code in one YAML pipeline.

Telize

Build reproducible, structured AI workflows with YAML and run them from your terminal, combining LLMs, shell, Python, and more—fully under your control.

Telize is a low-code framework for building agent-style pipelines: chain shell commands, file I/O, LLM calls, Python functions, and nested flows in a single workflow file. Configuration is validated before execution, and the CLI shows live progress as each step completes.

CI · Python 3.12+ · License

---

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Motivation
• How it works
• Workflow reference
• Examples
• CLI
• Development
• Contributing
• License

Features

• YAML workflows — one file defines config, named models, flows, and steps
• Composable steps — input, llm, shell, python, flow, and yaml actions
• Jinja templating — wire step outputs together with {{ steps.name.output }}
• Loops and sub-flows — iterate LLM steps over split lists; call nested flows with uses: flow
• Validated upfront — Pydantic models catch schema errors before any step runs
• Rich CLI output — progress, step panels, and errors in the terminal
• OpenAI-compatible LLMs — official OpenAI API or local Ollama via the same client

Requirements

• Python 3.12+
• LLM endpoint for uses: llm steps — OpenAI or Ollama; set api_url on each model profile (default http://localhost:11434)
• Optional: uv for fast local development

Installation

pip install telize

From source:

git clone https://github.com/telize-ai/telize.git
cd telize
uv sync
uv pip install -e .

Check the install:

telize --version

Quick start

1. For local models, start Ollama and pull a model:

ollama pull qwen3.5:4b   # or any model id you set under models.*.model

For OpenAI Cloud, set OPENAI_API_KEY and point a model profile at the API, for example api_url: https://api.openai.com/v1.

2. Create hello.yaml:

config:
  entrypoint: main

models:
  default:
    provider: openai
    model: qwen3.5:4b
    api_url: http://localhost:11434

flows:
  main:
    steps:
      - name: greet
        uses: llm
        model: default
        prompt: Say hello in one friendly sentence.

3. Run it:

telize -f hello.yaml

Validate the file without executing steps:

telize -f hello.yaml --validate-only

Run the bundled examples:

telize -f examples/minimal_llm.yaml
telize -f examples/spec_reference.yaml --validate-only

🚀 Motivation

Telize addresses a massive pain point in the current AI engineering landscape:
✨ unpredictability and unnecessary complexity.

Many popular frameworks force developers to write complex, nested Python code (LangChain, CrewAI, AutoGen) just to string together a few API calls, a bash script, and an LLM prompt.
This results in heavy, hard-to-maintain codebases that frequently break when APIs change.

Telize essentially acts as the “GitHub Actions or Ansible for AI.”
By treating LLMs as just another step in a standard automation pipeline, it brings sanity back to the engineering process.

---

✨ Why it works:

• Deterministic Structure + Non-Deterministic AI:
  It keeps the overall architecture rigid and predictable (YAML), while allowing the AI to handle the fuzzy, creative tasks (text generation, summarization) within strict boundaries.
• Upfront Validation:
  Running LLM pipelines can be expensive and time-consuming; catching a syntax or configuration error before wasting API credits is a huge win.
• Low Friction:
  Local-first by default (Ollama-ready) and zero-code setup means a developer can prototype an agentic workflow in 5 minutes without dealing with dependency hell.

---

👥 Who may choose Telize over Classic Agents?

• DevOps and System Administrators:
  People who already love Ansible, Docker Compose, or CI/CD pipelines may want to gravitate toward Telize or similar sollutions.
  They don't want an AI Agent guessing how to deploy code; they want a script that runs a test, summarizes the failure using an LLM, and posts it to Slack.
• Enterprise & Production Environments:
  Companies hate unpredictability. Classic agents are too risky for production because they can behave wildly.
  Telize provides guardrails. You know exactly what the workflow is going to do because you mapped out the steps.
• Data Pipelines:
  For ETL (Extract, Transform, Load) tasks where text needs to be scraped, cleaned by an LLM, and saved to a database, a YAML flow is infinitely better than a multi-agent swarm.

---

⚡ Where Telize Might Struggle (The Limitations)

While it is great for structured automation, it isn’t a silver bullet:

• Dynamic Decision Making:
  If a task requires an AI to dynamically look at a problem, decide it needs to create 3 new files, write code, test it, and self-correct on the fly, Telize’s static YAML structure will feel too restrictive.
• Complex State Management:
  For highly conversational applications (like a customer support chatbot that needs to maintain a complex state over days), a linear flow runner isn't the right tool.

---

How it works

1. Telize loads your YAML and validates it against typed Pydantic models.
2. The flow named in config.entrypoint runs first.
3. Each step executes through a registered action (input, llm, shell, …); llm steps resolve their model: profile from the top-level models map.
4. Later steps can reference earlier outputs via Jinja templates.
5. The CLI prints progress and results as the workflow runs.

Workflow reference

Top-level structure

Key	Description
config	Global settings: entrypoint (which flow runs first)
models	Named LLM profiles; referenced by model: on each uses: llm step
flows	Named flows; config.entrypoint must match one of these keys

config

Field	Description
entrypoint	Name of the flow to run when the file is executed

models

Each key under models is a profile name (for example default, creative). LLM steps pick a profile with model: <name>.

Field	Required	Description
provider	no (default openai)	Registered provider id
model	yes	Model id passed to the provider (e.g. qwen3.5:4b, gpt-4o-mini)
temperature	no	Sampling temperature (0–2)
api_url	no (default http://localhost:11434)	OpenAI-compatible API base URL (/v1 is appended automatically)
api_key	no	API key; use {{ env.OPENAI_API_KEY }} or rely on the OPENAI_API_KEY env var
system_prompt	no	System message for steps using this profile (Jinja at runtime)

Example — multiple profiles:

models:
  factual:
    model: qwen3.5:4b
    temperature: 0.2
    api_url: http://localhost:11434
    system_prompt: Be concise and factual.

  creative:
    model: qwen3.5:4b
    temperature: 1.0
    api_url: http://localhost:11434
    system_prompt: Be witty but brief.

Load-time env in api_url (see examples/env_config.yaml):

models:
  default:
    model: qwen3.5:4b
    api_url: http://{{ env.OLLAMA_HOST }}:11434

Flow

Field	Description
steps	List of steps (unique name per flow), executed in order

Steps (uses)

uses	Description
input	Read a file or a directory (with glob include)
llm	Send a prompt using a named model from models; optional output_to, loop
shell	Run run commands; optional envs (supports templates)
python	Call call (module.function) with args
flow	Run another flow via run
yaml	Run an external workflow from file (own config, models, and flows); optional input map passed to the child as {{ input.key }}

Templating

Telize uses Jinja2 in step fields.

When	What you can use
Load time	{{ env.VAR }} — expanded when the file is parsed
Runtime	{{ steps.<name>.output }}, {{ models.<name>.model }}, {{ input.<key> }}, {{ item }} (inside loops)

Workflow input is provided when invoking Telize from the shell (--input, --input-file, --input-stdin) or by a parent yaml step's input map when running a nested workflow.

With --input-stdin or --input-file, input may be a YAML/JSON mapping ({"name": "Ada"} → {{ input.name }}) or plain text (echo Hello or a .txt file → {{ input.text }}).

Example — chain a shell step into an LLM step:

- name: fetch_data
  uses: shell
  run: cat ./data.txt

- name: summarize
  uses: llm
  model: default
  prompt: |
    Summarize this:
    {{ steps.fetch_data.output }}

Examples

File	What it demonstrates
examples/spec_reference.yaml	Full specification reference (all step types and fields)
examples/minimal_llm.yaml	Smallest runnable LLM workflow
examples/shell_to_llm.yaml	Shell → LLM with {{ steps.*.output }}
examples/read_file.yaml	uses: input — single file
examples/read_directory.yaml	uses: input — directory glob
examples/llm_save_output.yaml	output_to — persist LLM text to disk
examples/llm_loop.yaml	loop — split output and iterate
examples/call_subflow.yaml	uses: flow — sub-flow in the same file
examples/nested_workflow.yaml	uses: yaml — external workflow + input
examples/python_step.yaml	uses: python — call a Python function
examples/multi_model.yaml	Multiple named models profiles
examples/shell_with_env.yaml	Shell envs and load-time {{ env.* }}
examples/env_config.yaml	{{ env.VAR }} in the models section at load time

CLI

usage: telize [-h] [--version] [-f FILE] [--validate-only]

options:
  -h, --help         show help
  --version          show version
  -f, --file FILE    path to workflow YAML
  --validate-only    parse and validate without running steps

Development

uv sync
uv run pytest
uv run ruff check .
uv run ruff format .
uv run mypy

See CONTRIBUTING.md for pull request guidelines and CHANGELOG.md for release notes.

Contributing

Contributions are welcome — bug reports, docs, and pull requests. Please read CONTRIBUTING.md and open an issue before large changes.

License

Apache License 2.0 — see LICENSE.

GitHub · Issues · Changelog