Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Juglans

Juglans is a language where the graph topology IS the program.

Others write code to draw graphs. We write graphs as code.

[classifier]: { "model": "gpt-4o-mini", "temperature": 0.0, "system_prompt": "Classify intent. Return JSON." }
[qa]: { "model": "gpt-4o-mini", "system_prompt": "Answer questions accurately." }
[executor]: { "model": "gpt-4o-mini", "system_prompt": "Execute tasks step by step." }
[reviewer]: { "model": "gpt-4o-mini", "system_prompt": "Review and improve responses." }

[classify]: chat(agent=classifier, format="json")
[answer]: chat(agent=qa, message=input.query)
[execute]: chat(agent=executor, message=input.task)
[fallback]: print(message="Unknown intent")
[review]: chat(agent=reviewer, message=output)

[classify] -> switch output.intent {
    "question": [answer]
    "task": [execute]
    default: [fallback]
}
[answer] -> [review]
[execute] -> [review]

This code IS the architecture diagram. The branching, routing, and convergence are explicit in the syntax — no separate drawing needed.

Why Juglans?

In the era of AI agents, how agents interact — who talks to whom, in what order, with what branching — matters more than any individual agent’s capability. Traditional tools make this structure implicit:

ApproachProblem
Airflow / PrefectPython code generates the DAG; graph is a second-class artifact
LangGraph / CrewAIState machines between agents; no true topological composition
TerraformDeclarative graph, but no control flow or functions
BPMNVerbose XML; not composable
JuglansGraph topology is the program — composable, verifiable, executable

Two File Types

ExtensionPurposeExample
.jgWorkflowNodes, edges, branching, loops, inline agent definitions
.jgxPrompt TemplateJinja-style variable interpolation

Key Features

  • Declarative DSL — Define workflows as graphs, not imperative code
  • Functions as Nodes — [name(params)]: { steps } — reusable parameterized blocks
  • Topology-Preserving Composition — flows: merges sub-graphs without losing structure
  • Expression Language — Python-like expressions with 100+ built-in functions
  • Built-in AI — chat() for LLM calls, p() for prompt rendering
  • Channels — Telegram (polling or webhook), Discord, Feishu (event subscription / incoming webhook), WeChat all configured as [channels.<kind>.<id>] and run together by juglans serve in one process; inbound chat_id auto-injects for multi-turn memory; workflows write reply() / chat() and the runtime routes back to the originating channel automatically
  • Platform messaging — telegram.send_message, discord.send_message, wechat.send_message, feishu.send_message (and friends) — push from any node
  • Conversation history — JSONL / SQLite / memory backends, auto-loaded into chat() when chat_id is set
  • HTTP Backend — serve() + response() (and @get / @post decorators) turn workflows into APIs
  • MCP Integration — Extend with any Model Context Protocol tool via inline chat(mcp={...})
  • Python Ecosystem — Call pandas, sklearn, etc. directly from workflows

Quick Install

# Prebuilt binary (recommended) — latest GitHub release
curl -fsSL https://raw.githubusercontent.com/juglans-ai/juglans/main/install.sh | sh

# From source (requires git clone first, Rust 1.80+)
git clone https://github.com/juglans-ai/juglans.git && cd juglans
cargo install --path .

Verify:

juglans --version

Hello World

Create hello.jg:

[greet]: print(message="Hello, Juglans!")
[done]: print(message="Workflow complete.")
[greet] -> [done]

Run it:

juglans hello.jg

Learning Path

You want to…Start here
Get running in 5 minutesQuick Start
Learn the language step by stepTutorial 1: Hello Workflow
Look up a specific tool or syntaxReference: Built-in Tools
See real-world examplesTutorial 9: Full Project
Deploy to productionDeploy with Docker

Architecture

┌─────────────────────────────────────────────────┐
│                   Juglans CLI                    │
├─────────────────────────────────────────────────┤
│  .jg Parser          .jgx Parser            │
│       │                     │                    │
│       ▼                     ▼                    │
│  ┌─────────────────────────────────────────┐    │
│  │         Workflow Executor (DAG)          │    │
│  └────────────────────┬────────────────────┘    │
│         ┌─────────────┼─────────────┐           │
│         ▼             ▼             ▼           │
│    Builtins      LLM Providers   MCP Tools      │
│  (chat, print,    (OpenAI,      (filesystem,    │
│   bash, etc.)    Anthropic,      browser)       │
│                  DeepSeek...)                   │
└─────────────────────────────────────────────────┘

License

MIT License