====== ell ======

**ell** is a lightweight, functional prompt engineering framework for Python that treats prompts as composable programs rather than static strings. Created by William Guss (formerly of OpenAI), it provides automatic versioning, visualization via Ell Studio, and multimodal support with a minimal, elegant API. It has 5.9K+ stars on GitHub and is licensed under MIT.

===== Overview =====

ell is built on the principle that **prompts are programs, not strings**. Every prompt is a Python function decorated with '@ell.simple' or '@ell.complex', turning LLM interactions into first-class, composable, versionable code. This functional approach enables developers to decompose complex AI tasks into modular, chainable language model programs (LMPs).

Core principles:

  * **Prompts are programs** -- Encapsulate prompt logic in Python functions with full IDE support (autocomplete, type checking, refactoring)
  * **Auto-versioning** -- Every change to an LMP triggers a new version stored locally, with diffs, commit history, and invocation logs
  * **Ell Studio** -- Local web UI (like TensorBoard for prompts) for visualizing traces, comparing versions, and inspecting multimodal I/O
  * **Multimodal first-class** -- Rich type coercion for text, images, and audio inputs/outputs
  * **Lightweight** -- Minimal dependencies, no heavy abstractions, no boilerplate

===== Installation =====

<code bash>
pip install -U "ell-ai[all]"
</code>

===== Code Examples =====

**Basic usage with @ell.simple:**

<code python>
import ell

# Initialize versioning store
ell.init(store="./ell_store", autocommit=True)

@ell.simple(model="gpt-4o-mini")
def write_poem(topic: str) -> str:
    # System message set via docstring
    "You are a creative poet."
    return f"Write a short poem about {topic}"

# Each call is traced, versioned, and logged
poem = write_poem("distributed systems")
print(poem)


@ell.simple(model="gpt-4o")
def summarize(text: str) -> str:
    "You are a concise summarizer."
    return f"Summarize in 2 sentences: {text}"

# Chain LMPs together naturally
summary = summarize(poem)
print(summary)
</code>

**Advanced usage with @ell.complex (tools, multimodal):**

<code python>
import ell
from PIL import Image

@ell.complex(model="gpt-4o")
def describe_image(image: Image.Image) -> str:
    return [
        ell.system("You are an image analyst."),
        ell.user(["Describe this image:", image])
    ]

# Multimodal: pass images directly
img = Image.open("chart.png")
description = describe_image(img)
print(description.text)


# Tool use with @ell.complex
@ell.tool()
def get_weather(city: str) -> str:
    "Get current weather for a city."
    return f"72F and sunny in {city}"

@ell.complex(model="gpt-4o", tools=[get_weather])
def weather_assistant(query: str):
    return [
        ell.system("Help users with weather queries."),
        ell.user(query)
    ]

response = weather_assistant("Whats the weather in Tokyo?")
</code>

===== Ell Studio =====

Ell Studio is a local web application that provides a visual interface for prompt engineering:

<mermaid>
graph LR
    subgraph Studio["Ell Studio"]
        A[LMP Browser: write_poem / summarize / describe_img]
        B[Version Diff View: v1 vs v2]
        C[Invocation History: Traces and Latency]
    end
    D[Execution Trace] --> Studio
    D --> E["write_poem AI --> summarize result"]
</mermaid>

Launch with:

<code bash>
ell-studio --storage ./ell_store
</code>

===== Auto-Versioning =====

ell uses lexical closures to automatically detect when an LMP changes. Every modification -- prompt text, model parameters, or function logic -- creates a new version with:

  * Full source code snapshot
  * Diff against previous version
  * Invocation logs (inputs, outputs, latency, token usage)
  * Dependency graph (which LMPs call which)

This enables empirical prompt optimization: compare version performance, revert regressions, and track iteration history without manual version control.

===== How It Differs from LangChain =====

| ^ ell ^ LangChain ^
| **Philosophy** | Prompts as functions | Chains as abstractions |
| **Weight** | Lightweight, minimal deps | Heavy, many dependencies |
| **Versioning** | Built-in auto-versioning | External (LangSmith) |
| **Learning curve** | Minimal -- just decorators | Steep -- many concepts |
| **IDE support** | Full (native Python) | Partial |
| **Focus** | Prompt engineering | Full LLM app framework |

===== References =====

  * [[https://github.com/MadcowD/ell|ell on GitHub]]
  * [[https://docs.ell.so/|ell Documentation]]
  * [[https://docs.ell.so/reference/studio.html|Ell Studio Docs]]

===== See Also =====

  * [[langsmith|LangSmith]] -- LLM observability and evaluation
  * [[marvin|Marvin]] -- Structured LLM outputs framework
  * [[dspy|DSPy]] -- Programmatic prompt optimization