Julep

https://github.com/julep-ai/julep
Admin
Julep is an open-source platform for building agent-based AI workflows with persistent memory, tool...
Tokens:591,975
Snippets:3,513
Trust Score:9.2
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Clone and setup development environment

Source: https://github.com/julep-ai/julep/blob/main/CONTRIBUTING.md

Commands to clone the repository and install dependencies using uv.

```bash
git clone https://github.com/julep-ai/julep
cd julep
uv sync --extra dev
```

--------------------------------

### Install and run the control plane with julep[server]

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/control-plane.md

Installs the server extra and starts the API with migrations applied. The server extra includes FastAPI, Uvicorn, sse-starlette, psycopg, Temporal, cryptography, and httpx. The command builds ServerSettings.from_env(), optionally applies Postgres migrations, constructs the app, and runs Uvicorn.

```bash
pip install --pre 'julep[server]'
julep serve api --host 127.0.0.1 --port 8080 --migrate
```

--------------------------------

### Install and serve the local Julep API

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/local.md

Installs the Julep server package and starts the local API server with the --local flag. The --local flag cannot be combined with --migrate because the local execution store has no database schema to migrate. By default, the server uses deterministic echo effects.

```bash
pip install --pre 'julep[server]'
julep serve api --local --host 127.0.0.1 --port 8080
```

--------------------------------

### Run the durable execution on Temporal example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/start/next-steps.md

Start a Temporal dev server and run the temporal_durable_agent.py example to see durable execution. The controller remains keyless.

```bash
# In one terminal:
temporal server start-dev
# In another:
python examples/temporal_durable_agent.py
```

--------------------------------

### Setup and Run Commands for Wasm Pure Executor

Source: https://github.com/julep-ai/julep/blob/main/spikes/wasm_pure/LEARNINGS.md

Start by syncing dependencies with uv, then run the runner script. This runs the spike from the current directory and performs the benchmarks and assertions.

```bash
uv sync
```

```bash
uv run python runner.py
```

--------------------------------

### Install Julep with Temporal support

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/gotchas.md

Commands to install Julep with Temporal dependencies and start the local development server.

```bash
pip install --pre 'julep[temporal]'   # from PyPI
pip install -e '.[temporal]'                 # from a source checkout (contributors)
temporal server start-dev
```

--------------------------------

### Session Usage Example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/sessions-api.md

Example showing access to the session's input channel.

```python
assert counter.in_channel == "in"
```

--------------------------------

### Run sandbox setup and drive a 12-workflow burst

Source: https://github.com/julep-ai/julep/blob/main/tooling/sandbox-k8s/README.md

Executes the sandbox setup script, exports the k3s kubeconfig, and runs drive.py with 12 workflows to trigger a scaling burst. Watch the worker Deployment with `kubectl get deploy julep-worker -w` to observe scaling from 0 to 4 replicas.

```bash
sudo bash tooling/sandbox-k8s/setup.sh
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
python3 tooling/sandbox-k8s/drive.py 12   # burst; watch `kubectl get deploy julep-worker -w`
```

--------------------------------

### Install runtime extras for Temporal, providers, HTTP, OTEL, store, and WASM

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/operations.md

Install the required Python packages for Julep runtime extras. Use the --pre flag to get pre-release versions. These commands are prerequisites for operating workers.

```bash
python -m pip install --pre 'julep[temporal]'
python -m pip install --pre 'julep[providers,http,otel]'
python -m pip install --pre 'julep[store,wasm]'
```

--------------------------------

### Install Julep from source

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/authoring-flows.md

Commands to set up a virtual environment and install the Julep package from a source checkout.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
```

--------------------------------

### Verify examples parsing

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/plans/2026-07-04-julep-v3-rename-and-cutover.md

Compile examples and run example-marked tests to ensure they still parse correctly.

```bash
python -m compileall -q examples/ spikes/ tooling/ && python -m pytest -q -k example 2>/dev/null | tail -2
```

--------------------------------

### Quickstart Flow Definition

Source: https://github.com/julep-ai/julep/blob/main/README.md

Define a support triage flow using @tool, @pure, and @flow decorators. The example demonstrates local execution using dry_run with mocked reasoners.

```python
from typing import TypedDict

from julep import Reasoner, deploy, flow, pure, think, tool


class SupportReply(TypedDict):
    reply: str


@tool(effect="read", idempotent=True)
def lookup_ticket(ticket: str) -> dict[str, str]:
    return {
        "ticket": ticket,
        "queue": "billing",
        "summary": "Use the duplicate-charge runbook.",
    }


@pure("ticket_prompt")
def ticket_prompt(hit: dict[str, str]) -> dict[str, str]:
    return {"queue": hit["queue"], "context": hit["summary"]}


support_reply = Reasoner(
    name="support_reply",
    model="anthropic:claude-haiku-4-5-20251001",
    system="Draft one concise support reply as JSON.",
    reply=SupportReply,
)


@flow
def triage(ticket: str) -> dict[str, str]:
    hit = lookup_ticket(ticket, retries=2, timeout_s=5)
    prompt = ticket_prompt(hit)
    answer = think(support_reply, prompt, timeout_s=10)
    return hit | answer


def fake_support_reply(value: dict[str, str]) -> SupportReply:
    return {"reply": f"{value['queue']}: {value['context']}"}


deployment = deploy(triage, tools=[lookup_ticket], reasoners=[support_reply])
result = deployment.dry_run(
    "Customer was charged twice.",
    reasoners={"support_reply": fake_support_reply},
)

print(result.value)
```

--------------------------------

### Inline activation output example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/julep-cli.md

Example output showing a partial rollout status after using the --activate flag.

```text
activated brief-refresh            sha256:...
error: lane 'digest' activation failed: ...
traffic   partial: activated brief-refresh, summary; unchanged digest
```

--------------------------------

### Install Temporal extra

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/sessions.md

Install the required dependencies to use the Temporal backend.

```bash
python -m pip install --pre 'julep[temporal]'
```

--------------------------------

### Install julep CLI

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/using-the-cli.md

Installs the julep package with the base install, which includes the julep command. Use the --pre flag to get the pre-release version.

```bash
pip install --pre julep        # the `julep` command ships with the base install
```

--------------------------------

### Run the durable agent example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/temporal.md

Command to execute the local durable agent example script from the repository checkout.

```bash
.venv/bin/python examples/temporal_durable_agent.py
```

--------------------------------

### Run email_approval.py example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/examples.md

Executes the email approval example which demonstrates a flow with human approval and local interpreter execution.

```bash
python examples/email_approval.py
```

--------------------------------

### Run research_assistant.py example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/examples.md

Executes the research assistant example which uses a local facade with a budget guard.

```bash
python examples/research_assistant.py
```

--------------------------------

### Run cluster_labeling_flow.py

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/examples.md

Runs the cluster labeling flow example. The example is keyless and deterministic.

```bash
python examples/cluster_labeling_flow.py

```

--------------------------------

### Install Julep from PyPI

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/authoring-flows.md

Command to install the pre-release version of Julep from PyPI.

```bash
python -m pip install --pre julep
```

--------------------------------

### Run swarm.py example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/examples.md

Command to execute the swarm composition example. The script prints its own reference text when run.

```bash
python examples/elnino/swarm.py
```

--------------------------------

### Run tests and verify installation

Source: https://github.com/julep-ai/julep/blob/main/docs/plans/2026-07-01-mem-mcp-adoption-phase1-llm-prompt-core.md

Commands to install dependencies, run the test suite, and verify that the package remains importable without Yglu.

```bash
uv pip install 'yglu>=1.0'
python -m pytest tests/test_dotctx_yglu.py -v && python -m pytest && uv run mypy --strict composable_agents && ruff check composable_agents
python -c "import composable_agents"
```

--------------------------------

### Start Temporal dev server

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/temporal.md

Command to initiate a local Temporal development server instance.

```bash
temporal server start-dev
```

--------------------------------

### Run the @flow authoring examples

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/start/next-steps.md

Run the episode_summary_flow.py and cluster_labeling_flow.py examples to see the core @flow loop and fan-out patterns. Both are keyless and deterministic.

```bash
python examples/episode_summary_flow.py
python examples/cluster_labeling_flow.py
```

--------------------------------

### Run support_triage.py example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/examples.md

Executes the support triage example which demonstrates a deterministic, keyless Agent.run loop with read-only tools.

```bash
python examples/support_triage.py
```

--------------------------------

### Build and verify documentation site

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/specs/2026-06-26-docs-site-consolidation-design.md

Commands to install dependencies, perform a static build, and check types for the documentation site.

```bash
cd docs-site
npm install
npm run build          # next build, static export to out/
npm run types:check    # fumadocs-mdx + next typegen + tsc --noEmit
```

--------------------------------

### Run the demo: up.sh and drive.py

Source: https://github.com/julep-ai/julep/blob/main/tooling/k3d-cad-demo/README.md

Starts the k3d cluster, publishes the bundle, and runs the flow on Temporal. Requires the k3d-cad-demo tooling and uv.

```bash
bash tooling/k3d-cad-demo/up.sh
TEMPORAL_ADDRESS=localhost:7233 uv run python tooling/k3d-cad-demo/drive.py
```

--------------------------------

### One-time setup for julep-v2 repository

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/development/team-guide.md

Clones the julep-v2 repository, changes into its directory, and installs the package in editable mode with development dependencies. Requires Python 3.12+.

```bash
git clone git@github.com:julep-ai/julep-v2.git
cd julep-v2
python -m pip install -e '.[dev]'      # authoring + tests + lint/type tooling
```

--------------------------------

### Start the complete stack

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/local.md

Starts the full durable stack in the foreground using the local environment. The supervisor starts Temporal's local dev server, migrates and starts the durable API, publishes the application, and starts workers for each release-scoped lane queue.

```bash
julep dev up --env local
```

--------------------------------

### Dockerfile: copy repo and install framework with extras

Source: https://github.com/julep-ai/julep/blob/main/tooling/runtime-image/README.md

The Dockerfile copies the repo and installs the framework with dotctx, temporal, store, and wasm extras, then removes the source. This keeps only the installed framework in the final image.

```dockerfile
COPY julep-v2 /src/julep-v2
RUN pip install --no-cache-dir uv \
    && pip install --no-cache-dir '/src/julep-v2[dotctx,temporal,store,wasm]' \
    && rm -rf /src/julep-v2
```

--------------------------------

### Build and verify documentation site

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/plans/2026-07-04-julep-v3-rename-and-cutover.md

Commands to install dependencies, build the documentation site, and verify that no legacy 'composable' references remain.

```bash
cd docs-site && npm ci && npm run build && cd ..
grep -rin 'composable' docs-site/content docs-site/app | grep -v node_modules
```

--------------------------------

### Commit example changes

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/plans/2026-07-04-julep-v3-rename-and-cutover.md

Commit the changes made during the examples and tooling sweep.

```bash
git add -A
git commit -m "rename: sweep examples/scripts/infra/tooling/spikes to julep"
```

--------------------------------

### Update pip installation instructions in gotchas.md

Source: https://github.com/julep-ai/julep/blob/main/docs/plans/2026-06-29-ws2-executable-docs.md

Provide both PyPI and source checkout installation commands for users.

```bash
pip install 'composable-agents[cli]'   # from PyPI
pip install -e '.[cli]'                 # from a source checkout (contributors)
```

--------------------------------

### Run keyless local examples

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/examples.md

Executes a series of keyless local examples that do not require an API key or a Temporal server.

```bash
python examples/episode_summary_flow.py
python examples/cluster_labeling_flow.py
python examples/support_triage.py
python examples/research_assistant.py
python examples/email_approval.py
```

--------------------------------

### Run the session demo with local and temporal backends

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/start/next-steps.md

Source your .env file and run the session_demo.py example with either the local or temporal backend to explore long-lived stateful interactions.

```bash
# Source your .env first:
set -a; source .env; set +a
uv run --extra dev --extra providers python examples/session_demo.py local
uv run --extra dev --extra providers python examples/session_demo.py temporal
```

--------------------------------

### Install Julep CLI

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/gotchas.md

Commands to install the Julep CLI from PyPI or a source checkout.

```bash
pip install --pre julep   # from PyPI
pip install -e .          # from a source checkout (contributors)
```

--------------------------------

### Install CMA extra

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/sessions.md

Install the required dependencies to use the CMA backend.

```bash
python -m pip install --pre 'julep[cma]'
```

--------------------------------

### Build and smoke test package

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/plans/2026-07-04-julep-v3-rename-and-cutover.md

Builds the package, installs it into a clean virtual environment, and verifies the installation and CLI functionality.

```bash
uv build
python -m venv /tmp/julep-smoke && /tmp/julep-smoke/bin/pip -q install dist/julep-3.0.0rc1-py3-none-any.whl
/tmp/julep-smoke/bin/python -c "import julep; print(julep.__version__)"
/tmp/julep-smoke/bin/julep --help
/tmp/julep-smoke/bin/python -m julep.cli.artifact --help
```

--------------------------------

### Expected session output

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/sessions.md

The expected console output after running the quickstart session script.

```text
turn:started
emit:out:1:{'reply': 'ack:hello', 'seen': ['hello']}
turn:done
turn:started
emit:out:2:{'reply': 'ack:again', 'seen': ['hello', 'again']}
turn:done
carrier: ['hello', 'again']
pending: {'in': 0}
closed:done
```

--------------------------------

### Install Temporal extra

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/temporal.md

Install the Julep Temporal package extra using pip.

```bash
pip install --pre 'julep[temporal]'
```

--------------------------------

### Install Julep Runtime Packages

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/concepts/architecture.md

Installation commands for the core Julep runtime and optional feature-specific dependencies.

```bash
pip install --pre julep
pip install --pre 'julep[temporal]'
pip install --pre 'julep[dbos]'
pip install --pre 'julep[providers]'
pip install --pre 'julep[cma]'
```

--------------------------------

### Install Julep Temporal dependencies

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/operations.md

Install the necessary dependencies for running Julep with Temporal and providers.

```bash
pip install -e '.[temporal,providers]'
```

--------------------------------

### Install DBOS dependencies

Source: https://github.com/julep-ai/julep/blob/main/docs/plans/2026-06-09-dbos-backend-and-flow-runtime.md

Install the composable-agents package with DBOS support. Requires Python 3.11 or higher.

```bash
pip install 'composable-agents[dbos]'    # dbos>=2.18, Python >= 3.11
```

--------------------------------

### Start a Temporal worker

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/operations.md

Configure environment variables and start the Julep worker for the session lane.

```bash
export WORKER_CONTEXT_FACTORY=yourapp.worker:make_context
export TEMPORAL_ADDRESS=localhost:7233
export TEMPORAL_NAMESPACE=default
export TEMPORAL_TASK_QUEUE=julep
export JULEP_BLOB_STORE_URL=file:///var/lib/julep/blobs
export WORKER_HEALTH_PORT=8080
# The worker fails closed on payload encryption. Either export
# TEMPORAL_PAYLOAD_KEYS/TEMPORAL_PAYLOAD_KEY_ID, or opt out explicitly for a
# deliberately plaintext local Temporal:
export TEMPORAL_PAYLOAD_ENCRYPTION_REQUIRED=false
julep worker
```

--------------------------------

### Initialize a worker with build_worker

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/temporal.md

Example of initializing a worker when you own the temporalio.client.Client instance.

```python
from temporalio.client import Client
from julep.execution.activities import WorkerContext
from julep.execution.worker import DEFAULT_TASK_QUEUE, build_worker

client = await Client.connect("localhost:7233")
context = WorkerContext(
    tool_urls={"send_email": "https://tools.example/send_email"},
    mcp_call=my_async_mcp_caller,
    llm=my_async_llm,
    capabilities=caps,
    subflows={},
    agents={},
)
worker = build_worker(client, context, task_queue=DEFAULT_TASK_QUEUE)
await worker.run()
```

--------------------------------

### Provision Test Database

Source: https://github.com/julep-ai/julep/blob/main/docs/plans/2026-06-09-dbos-backend-and-flow-runtime.md

Commands to start a local Postgres container and set the environment variable for testing.

```bash
docker run -d --name julep-dbos-pg -e POSTGRES_PASSWORD=julep -p 5433:5432 postgres:16
export DBOS_TEST_DATABASE_URL='postgresql://postgres:ca@localhost:5433/postgres'
uv sync --extra dev
```

--------------------------------

### Install julep providers extra

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/providers-and-resilience.md

Installs the julep providers extra and the any-llm SDK with Anthropic and OpenAI support. Required before using live LLM clients.

```bash
pip install --pre 'julep[providers]' 'any-llm-sdk[anthropic,openai]'
```

--------------------------------

### Deploy and Inspect a Flow

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/start/ladder.md

This example demonstrates defining tools, pure functions, and reasoners, then deploying a triage flow and running a dry_run with a mocked reasoner.

```python
from typing import TypedDict

from julep import Reasoner, deploy, flow, pure, switch_on, think, tool


class ReturnDecision(TypedDict):
    decision: str
    note: str


@tool(effect="read", idempotent=True)
def lookup_return(order_id: str) -> dict[str, object]:
    return {
        "order_id": order_id,
        "action": "review",
        "reason": "damaged",
    }


@pure("ladder_review_prompt")
def review_prompt(req: dict[str, object]) -> dict[str, object]:
    return {"order_id": req["order_id"], "reason": req["reason"]}


@pure("ladder_auto_decision")
def auto_decision(req: dict[str, object]) -> dict[str, object]:
    return {"decision": "auto-approve", "note": f"Auto-approved {req['order_id']}."}


RETURN_REVIEWER = Reasoner(
    name="return_reviewer",
    model="anthropic:claude-haiku-4-5-20251001",
    system="Review a return request as JSON.",
    reply=ReturnDecision,
)


@flow
def review(req: dict[str, object]) -> dict[str, object]:
    prompt = review_prompt(req)
    answer = think(RETURN_REVIEWER, prompt)
    return prompt | answer


@flow
def auto(req: dict[str, object]) -> dict[str, object]:
    return auto_decision(req)


@flow
def triage(order_id: str) -> dict[str, object]:
    req = lookup_return(order_id, name="req")
    return switch_on(req, key="action", cases={"review": review, "auto": auto}, default=auto)


def fake_return_reviewer(value: dict[str, object]) -> ReturnDecision:
    return {"decision": "inspect", "note": f"Manual review for {value['reason']}."}


deployment = deploy(triage, tools=[lookup_return], reasoners=[RETURN_REVIEWER])
print(deployment.surface_shape.value)
print(deployment.prod_gap_summary())
print(
    deployment.dry_run(
        "ret-100",
        reasoners={"return_reviewer": fake_return_reviewer},
    ).value
)
```

```text
Branching
no prod gap
{'order_id': 'ret-100', 'reason': 'damaged', 'decision': 'inspect', 'note': 'Manual review for damaged.'}
```

--------------------------------

### Clone and install Julep development environment

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/development/contributing.md

Commands to clone the repository and install the package in editable mode with development dependencies.

```bash
git clone https://github.com/julep-ai/julep-v2
cd julep-v2
python -m pip install -e '.[dev]'
```

--------------------------------

### Smoke test PyPI installation

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/plans/2026-07-04-julep-v3-rename-and-cutover.md

Verifies the installation and functionality of the package from PyPI in a clean virtual environment.

```bash
python -m venv /tmp/julep-pypi && /tmp/julep-pypi/bin/pip install --pre julep
/tmp/julep-pypi/bin/python -c "import julep; print(julep.__version__)"   # 3.0.0rc1
/tmp/julep-pypi/bin/julep --help
```

--------------------------------

### Install Julep with Temporal, HTTP, and OpenTelemetry

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/start/install.md

Installs Temporal support along with httpx for HTTP tool calls and OpenTelemetry for span exporting.

```bash
pip install --pre 'julep[temporal,http,otel]'
```

--------------------------------

### Install Julep with extras

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/cheatsheet.md

Install Julep with optional extras for durable execution (temporal, dbos), multi-provider LLM support (providers), HTTP tools and OpenTelemetry (http, otel), and development dependencies. Requires Python 3.12+.

```bash
pip install --pre julep                 # authoring + compile + local run (no key)
pip install --pre 'julep[temporal]'     # durable execution on Temporal
pip install --pre 'julep[dbos]'         # durable execution on Postgres/DBOS
pip install --pre 'julep[providers]'    # multi-provider LLM (any-llm)
pip install --pre 'julep[http,otel]'    # native HTTP tools + OTel export
pip install -e '.[dev]'                        # contributing: tests + lint + types
```

--------------------------------

### Commit documentation updates

Source: https://github.com/julep-ai/julep/blob/main/docs/plans/2026-06-29-ws4-onramp-switch-on.md

Stages and commits the new ladder tutorial and updated branching examples.

```bash
git add docs-site/content/docs/start/ladder.md docs-site/content/docs/start/meta.json docs-site/content/docs/guides/authoring-flows.md
git commit -m "docs: add progressive ladder tutorial + switch_on/switch branching example"
```

--------------------------------

### Install Julep

Source: https://github.com/julep-ai/julep/blob/main/README.md

Install the Julep package using pip. The --pre flag is required for the current release candidate.

```bash
pip install --pre julep
```

--------------------------------

### Install dependencies and generate development keys

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/local.md

Installs the Julep server and store packages, creates a `.julep` directory, generates development keys, and sets the PostgreSQL DSN environment variable. The `julep keygen` command writes mode 0600, refuses to overwrite existing files unless `--force` is used, and prints shell exports to stdout when `--output` is omitted.

```bash
pip install --pre 'julep[server,store]'
mkdir -p .julep
julep keygen --output .julep/dev.env
source .julep/dev.env

export JULEP_EXECUTION_STORE_DSN='postgresql://postgres:postgres@127.0.0.1:5432/julep'
```

--------------------------------

### Install Julep with DBOS backend

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/dbos.md

Install the Julep DBOS backend with pip. Requires dbos>=2.18 and Python >= 3.11.

```bash
pip install --pre 'julep[dbos]'    # dbos>=2.18, Python >= 3.11
```

--------------------------------

### Install Temporal extra in editable mode

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/temporal.md

Install the Julep Temporal package in editable mode for local development.

```bash
pip install -e '.[temporal]'
```

--------------------------------

### Sanity check for episode summary flow

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/development/team-guide.md

Runs the episode summary flow example to verify the authoring/compile path works without needing an API key or Temporal.

```bash
python examples/episode_summary_flow.py
```

--------------------------------

### start_flow

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/python-api.md

Async function that starts a flow on a connected Temporal client and returns a workflow handle. Start options cannot override id or task_queue.

```APIDOC
## start_flow

### Description
Async function that starts a flow on a connected Temporal client and returns a workflow handle. Start options cannot override id or task_queue.

### Signature
same as run_flow, plus workflow_start_options=None

### Parameters
- **client** (Temporal client) - Required - Connected Temporal client.
- **flow_json** (any) - Required - Flow definition in JSON.
- **manifest_json** (any) - Required - Manifest in JSON.
- **session_id** (string) - Required - Session identifier.
- **input** (any) - Optional - Input data.
- **task_queue** (string) - Optional - Task queue (default "julep").
- **policy** (any) - Optional - Policy.
- **pinned_pures** (any) - Optional - Pinned pure functions.
- **max_call_limits** (any) - Optional - Maximum call limits.
- **principal** (any) - Optional - Principal.
- **root_run_id** (any) - Optional - Root run ID.
- **bundle** (any) - Optional - Bundle.
- **runtime_declarations_ref** (any) - Optional - Runtime declarations reference.
- **queue_lanes** (any) - Optional - Queue lanes.
- **run_id** (any) - Optional - Run ID.
- **emit_projection** (boolean) - Optional - Whether to emit projection (default False).
- **projection_batch_size** (integer) - Optional - Projection batch size (default 20).
- **projection_batch_interval_s** (float) - Optional - Projection batch interval in seconds (default 2.0).
- **secrets** (any) - Optional - Secrets.
- **mcp_preflight** (any) - Optional - MCP preflight.
- **workflow_start_options** (any) - Optional - Start options; cannot override id or task_queue.

### Returns
workflow handle

### Raises
same encryption/binding checks; Temporal errors

### Example
handle = await start_flow(client, d.flow_json, d.manifest_json, session_id="run-1")
```

--------------------------------

### SessionEvent Usage Example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/sessions-api.md

Demonstrates creating an emit event and verifying its type.

```python
event = SessionEvent.emit("out", 1, {"reply": "ok"}); assert event.is_emit
```

--------------------------------

### Start event consumer

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/operations.md

Create an event consumer for the session handle.

```python
agen = handle.events()
```

--------------------------------

### Declare and execute a Reasoner

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/start/ladder.md

This example demonstrates defining a Reasoner, using it within a flow, and executing a dry run with a mock reasoner function.

```python
from typing import TypedDict

from julep import Reasoner, deploy, flow, pure, think, tool


class ReturnDecision(TypedDict):
    decision: str
    note: str


@tool(effect="read", idempotent=True)
def lookup_return(order_id: str) -> dict[str, object]:
    return {
        "order_id": order_id,
        "action": "review",
        "reason": "damaged",
        "items": ["coat", "scarf"],
    }


@pure("ladder_decision_prompt")
def decision_prompt(hit: dict[str, object]) -> dict[str, object]:
    return {"order_id": hit["order_id"], "reason": hit["reason"]}


RETURN_DECIDER = Reasoner(
    name="return_decider",
    model="anthropic:claude-haiku-4-5-20251001",
    system="Classify the return request as JSON.",
    reply=ReturnDecision,
)


@flow
def triage(order_id: str) -> dict[str, object]:
    hit = lookup_return(order_id)
    prompt = decision_prompt(hit)
    answer = think(RETURN_DECIDER, prompt)
    return prompt | answer


def fake_return_decider(value: dict[str, object]) -> ReturnDecision:
    return {"decision": "inspect", "note": f"Review {value['reason']} return."}


deployment = deploy(triage, tools=[lookup_return], reasoners=[RETURN_DECIDER])
print(
    deployment.dry_run(
        "ret-100",
        reasoners={"return_decider": fake_return_decider},
    ).value
)
```

```text
{'order_id': 'ret-100', 'reason': 'damaged', 'decision': 'inspect', 'note': 'Review damaged return.'}
```

--------------------------------

### Run live full stack

Source: https://github.com/julep-ai/julep/blob/main/examples/episode_summarizer/README.md

Starts the live full stack: Temporal, an authenticated streamable-HTTP MCP server, the Julep API, and an in-process release-pinned worker. Requires ANTHROPIC_API_KEY, the temporal CLI, and PostgreSQL; uses Docker for postgres:16 if EPISODE_E2E_PG_DSN is not set.

```bash
EPISODE_E2E_PG_DSN='postgresql://...' \
  uv run --no-sync python -m examples.episode_summarizer.run_live
```

--------------------------------

### Fragment ADT and renderer registration example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/internals/prompt-fragments.md

Defines the Fragment ADT as a closed set of frozen dataclasses (Lift, Ask, Concat, Under, Map) each with a concrete render method, plus the fragments helper and an example of registering a renderer and using it in a Reasoner. Under is contravariant in Context (Reader.local), Concat is the string-monoid combine.

```python
@dataclass(frozen=True)
class Lift:    text: str;                                    # Reader unit (constant)
@dataclass(frozen=True)
class Ask:     key: str; fmt: Callable[[Any], str] = str     # read one Context field
@dataclass(frozen=True)
class Concat:  parts: tuple["Fragment", ...]                 # string-monoid op; identity = Lift("")
@dataclass(frozen=True)
class Under:   project: Callable[[Context], Context]; body: "Fragment"   # Reader.local / contramap env
@dataclass(frozen=True)
class Map:     body: "Fragment"; fn: Callable[[str], str]    # fmap on the rendered output
# each defines .render(self, ctx) -> str; Fragment = Union[Lift, Ask, Concat, Under, Map]

def fragments(*parts: "Fragment | str") -> "Fragment":
    return Concat(tuple(p if isinstance(p, (Lift, Ask, Concat, Under, Map)) else Lift(p) for p in parts))

# authoring:
register_renderer("research.system.v1", fragments(
    "You are a careful research agent.\n\n",
    Ask("persona", fmt=lambda p: f"Persona: {p}\n"),
    Under(lambda c: c["task"], TASK_BLOCK),     # render TASK_BLOCK against ctx["task"]
    Ask("trace", fmt=summarize_trace),           # fold the trace slice -> str
))
Reasoner(name="researcher", model="claude-opus-4-8", system_render="research.system.v1")
```

--------------------------------

### step_from_json usage

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/flow-api.md

Example of rebuilding a step from a JSON dictionary.

```python
step_from_json({"kind": "think", "reasoner": "r"})
```

--------------------------------

### Channel Usage Example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/sessions-api.md

Demonstrates basic channel operations including appending, receiving, emitting, and draining values.

```python
channel.append("a"); assert await channel.recv() == "a"; channel.emit("ok"); assert channel.drain() == ["ok"]
```

--------------------------------

### Define-by-construction flow example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/concepts/architecture.md

Demonstrates defining a flow using @flow, @tool, and @pure decorators, and deploying it with Reasoner and tool definitions.

```python
from typing import TypedDict

from julep import Reasoner, deploy, flow, pure, think, tool

class SupportReply(TypedDict):
    reply: str

@tool(effect="read", idempotent=True)
def lookup_ticket(ticket: str) -> dict[str, str]:
    return {"ticket": ticket, "queue": "billing", "summary": "Use the runbook."}

@pure("ticket_prompt")
def ticket_prompt(hit: dict[str, str]) -> dict[str, str]:
    return {"queue": hit["queue"], "context": hit["summary"]}

SUPPORT_REPLY = Reasoner(
    name="support_reply",
    model="anthropic:claude-haiku-4-5-20251001",
    system="Draft one concise support reply as JSON.",
    reply=SupportReply,
)

@flow
def triage(ticket: str) -> dict[str, str]:
    hit = lookup_ticket(ticket, retries=2, timeout_s=5)
    prompt = ticket_prompt(hit)
    answer = think(SUPPORT_REPLY, prompt, timeout_s=10)
    return hit | answer

deployment = deploy(triage, tools=[lookup_ticket], reasoners=[SUPPORT_REPLY])
```

--------------------------------

### Provider:model addressing examples

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/providers-and-resilience.md

Examples of provider:model strings accepted by Reasoner.model and Agent(reasoner=...). A bare model string without a provider prefix falls back to the default provider (anthropic).

```text
"openai:gpt-4o"
"anthropic:claude-sonnet-4-6"
"gemini:gemini-2.5-flash"
"groq:llama-3.3-70b"
```

--------------------------------

### Minimal End-to-End Julep Flow

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/development/team-guide.md

A complete example demonstrating the authoring loop, including tool definition, pure transforms, reasoner configuration, and a local dry run.

```python
from typing import TypedDict
from julep import Reasoner, deploy, flow, pure, think, tool


@tool(effect="read", idempotent=True)
def lookup_ticket(ticket: str) -> dict[str, str]:
    return {"queue": "billing", "summary": "Use the duplicate-charge runbook."}


@pure("ticket_prompt")
def ticket_prompt(hit: dict[str, str]) -> dict[str, str]:
    return {"queue": hit["queue"], "context": hit["summary"]}


class SupportReply(TypedDict):
    reply: str


SUPPORT_REPLY = Reasoner(
    name="support_reply",
    model="anthropic:claude-haiku-4-5-20251001",
    system="Draft one concise support reply as JSON.",
    reply=SupportReply,
)


@flow
def triage(ticket: str) -> dict[str, str]:
    hit = lookup_ticket(ticket, retries=2, timeout_s=5)   # append a tool step
    prompt = ticket_prompt(hit)                            # append a pure step
    answer = think(SUPPORT_REPLY, prompt, timeout_s=10)    # append a reasoner step
    return hit | answer                                    # `|` merges records


deployment = deploy(triage, tools=[lookup_ticket], reasoners=[SUPPORT_REPLY])
result = deployment.dry_run(
    "Customer was charged twice.",
    reasoners={"support_reply": lambda v: {"reply": f"{v['queue']}: {v['context']}"}},
)
print(result.value)
```

--------------------------------

### GET /v1/ready

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/control-plane.md

Authenticated readiness check that verifies Postgres, artifact store, and Temporal dependencies. Returns 200 when ready, 503 when unavailable.

```APIDOC
## GET /v1/ready

### Description
Authenticated readiness check that verifies Postgres, artifact store, and Temporal dependencies. Returns 200 when ready, 503 when unavailable.

### Method
GET

### Endpoint
/v1/ready

### Authentication
Bearer token required.

### Response
#### Success Response (200)
- **status** (string) - The status of the service, "ready".
- **checks** (object) - Maps each dependency to "ok" or an error class.

#### Error Response (503)
- **status** (string) - The status of the service, "unavailable".
- **checks** (object) - Maps each dependency to "ok" or an error class.

#### Response Example
{
  "status": "ready",
  "checks": {
    "postgres": "ok",
    "artifact_store": "ok",
    "temporal": "ok"
  }
}
```

--------------------------------

### Implement Branching Logic with switch and switch_on

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/authoring-flows.md

Demonstrates binary and multiway branching using explicit switch and sugar-based switch_on patterns. The example includes flow definitions and a dry run execution.

```python
from julep import deploy, flow, pure, switch, switch_on


@pure("authoring_action_selector")
def action_selector(req: dict[str, object]) -> str:
    return str(req["action"])


@pure("authoring_team_context")
def team_context_for_arm(req: dict[str, object]) -> dict[str, object]:
    team_context = req["team_context"]
    assert isinstance(team_context, dict)
    return team_context


@pure("authoring_assign_review")
def assign_review(payload: dict[str, object]) -> dict[str, object]:
    return {"route": "review", "team": payload["team"], "order_id": payload["order_id"]}


@pure("authoring_assign_auto")
def assign_auto(payload: dict[str, object]) -> dict[str, object]:
    return {"route": "auto", "team": payload["team"], "order_id": payload["order_id"]}


@flow
def review(req: dict[str, object], team_context: dict[str, object]) -> dict[str, object]:
    payload = req | team_context
    return assign_review(payload)


@flow
def auto(req: dict[str, object], team_context: dict[str, object]) -> dict[str, object]:
    payload = req | team_context
    return assign_auto(payload)


@flow
def route_explicit(req: dict[str, object]) -> dict[str, object]:
    team_context = team_context_for_arm(req, name="team_context")
    return switch(
        action_selector,
        req,
        cases={
            "review": review(team_context=team_context),
            "auto": auto(team_context=team_context),
        },
        default=auto(team_context=team_context),
    )


@flow
def route_sugar(req: dict[str, object]) -> dict[str, object]:
    team_context = team_context_for_arm(req, name="team_context")
    return switch_on(
        req,
        key="action",
        cases={
            "review": review(team_context=team_context),
            "auto": auto(team_context=team_context),
        },
        default=auto(team_context=team_context),
    )


payload = {"order_id": "ret-100", "action": "review", "team_context": {"team": "returns"}}
print(deploy(route_explicit, tools=[]).dry_run(payload).value)
print(deploy(route_sugar, tools=[]).dry_run(payload).value)
```

```text
{'route': 'review', 'team': 'returns', 'order_id': 'ret-100'}
{'route': 'review', 'team': 'returns', 'order_id': 'ret-100'}
```

--------------------------------

### Run dotctx_issue_dedup.py

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/examples.md

Executes the dotctx_issue_dedup example, which demonstrates a bounded native-tool loop using a frozen MCP tool surface.

```bash
python -m examples.dotctx_issue_dedup
```

--------------------------------

### Serve local API with a context factory

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/local.md

Starts the local API server with a configured context factory to call configured tools and reasoners instead of using echo effects. The factory must be a zero-argument sync or async function returning a WorkerContext. Configured-context execution uses normal effect implementations including real MCP discovery, binding validation, preflight, native provider tool definitions, and transcript materialization/budgeting for scoped agents.

```bash
LOCAL_JULEP_TOKEN="$(openssl rand -hex 32)"
export JULEP_API_KEYS="local-admin:${LOCAL_JULEP_TOKEN}:admin"
julep serve api --local \
  --context-factory my_project.worker:build_context
```

--------------------------------

### Helper functions for complete_reasoner testing

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/plans/2026-07-27-dotctx-skills.md

Utility functions to simulate tool calls, registry setup, and reasoner initialization for testing purposes.

```python
def _skill_call(name: str, call_id: str = "c1") -> FakeCompletion:
    return FakeCompletion(
        choices=[
            FakeChoice(
                FakeMessage(
                    tool_calls=[
                        FakeToolCall(call_id, FakeFunction(SKILL_TOOL, json.dumps({"name": name})))
                    ]
                )
            )
        ]
    )


def _registry_with(*skills: Skill) -> tuple[Registry, tuple[str, ...]]:
    reg = Registry()
    return reg, tuple(reg.register_skill(skill) for skill in skills)


def _reasoner(keys: tuple[str, ...], **kwargs: Any) -> Reasoner:
    return Reasoner(
        name="skilled",
        model="gemini:gemini-2.5-flash",   # prompt-fallback provider: one dispatch path
        system="You draft.",
        skills=list(keys),
        **kwargs,
    )
```

--------------------------------

### Dispatch with Principal

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/internals/run-principal.md

Shows how to pass a principal when starting a workflow and via the agent.deploy facade. The principal defaults to None for single-tenant deployments.

```python
await client.start_workflow(
    FlowWorkflow.run,
    FlowInput(flow_json=..., manifest_json=..., principal={"storeId": 413, "tokenRef": "cred_abc"}),
    ...,
)
# facade
agent.deploy(client, session_id=..., input=..., principal={...})
```

--------------------------------

### SessionHandle Usage Example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/sessions-api.md

Demonstrates sending a value with an idempotency key and closing the session.

```python
ack = await handle.send("a", idempotency_key="a"); await handle.close("done")
```

--------------------------------

### Execute the flow script

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/authoring-flows.md

Command to run the created quickstart_flow.py script.

```bash
python quickstart_flow.py
```

--------------------------------

### Commit Migration Changes

Source: https://github.com/julep-ai/julep/blob/main/docs/plans/2026-06-29-ws5-object-first-reasoners.md

Command to commit the migration of examples and documentation to the object-first reasoner pattern.

```bash
git add examples docs-site/content
git commit -m "docs(examples): migrate to object-first reasoners (think(obj)+deploy(reasoners=[obj]))"
```

--------------------------------

### Commit Value Example

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/reference/sessions-api.md

Demonstrates how to commit a value to the session store using a session ID, cursor, data, and its fingerprint.

```python
cursor = await store.commit_value("s1", 0, {"turn": 1}, value_fingerprint({"turn": 1}))
```

--------------------------------

### Implement minimal CLI structure

Source: https://github.com/julep-ai/julep/blob/main/docs/superpowers/plans/2026-06-23-ca-cli-v1.md

Define the package initialization and the Typer application entry point.

```python
# composable_agents/ca/__init__.py
"""ca — developer CLI for composable-agents modules."""
from composable_agents.ca.cli import main

__all__ = ["main"]
```

```python
# composable_agents/ca/cli.py
from __future__ import annotations

import typer

app = typer.Typer(add_completion=True, no_args_is_help=True, help="Developer CLI for composable-agents modules.")

VERSION = "0.1.0"


@app.callback(invoke_without_command=True)
def _root(
    ctx: typer.Context,
    version: bool = typer.Option(False, "--version", help="Print ca version and exit."),
) -> None:
    if version:
        typer.echo(f"ca {VERSION}")
        raise typer.Exit(0)


def main(argv: list[str] | None = None) -> int:
    """Entry point. Returns a process exit code (does not call sys.exit)."""
    try:
        app(args=argv, standalone_mode=False)
    except SystemExit as exc:  # argparse-style callers expect an int
        return int(exc.code or 0)
    except typer.Exit as exc:
        return int(exc.exit_code)
    return 0
```

--------------------------------

### Install Julep in editable mode

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/sessions.md

Install the Julep package in editable mode from a repository checkout.

```bash
python -m pip install -e .
```

--------------------------------

### Configure MCP server credentials

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/control-plane.md

Example TOML configuration for an MCP server using a secret reference for the Authorization header.

```toml
[tool.julep.mcp.servers.tracker]
url = "https://tracker.example/mcp"
headers = { Authorization = "secret://tracker-token" }
```

--------------------------------

### Open and drive a session with agent.open

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/guides/sessions.md

Demonstrates opening a session with a specified backend and interacting with it by sending messages, streaming events, and checking state.

```python
handle = await agent.open(session=chat, backend="temporal")   # or "local" / "cma"

await handle.send(user_msg)                  # push a message (idempotency_key optional)
async for ev in handle.events():             # stream until Closed
    if ev.is_emit:   render(ev.payload)
    elif ev.is_error: log(ev.reason)         # fatal vs non-fatal
snapshot = await handle.state()              # carrier + projection snapshot
parked   = await handle.open_receives()      # channels currently awaiting input
await handle.close(reason="done")            # terminal; events() ends on Closed
```

--------------------------------

### Install Julep CMA dependencies

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/operations.md

Install the CMA extra and configure the required Anthropic API key.

```bash
pip install -e '.[cma,providers]'
export ANTHROPIC_API_KEY=...
```

--------------------------------

### Example of an arr node with static arguments

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/internals/specification.md

Demonstrates the JSON structure for an 'arr' node carrying static arguments for a registered pure function.

```json
{"op":"arr","id":"$","pure":"std.pluck","args":{"key":"summary"}}
```

--------------------------------

### Run the worker container entrypoint

Source: https://github.com/julep-ai/julep/blob/main/docs-site/content/docs/deploy/kubernetes.md

The container entrypoint is the `julep worker` command, which reads its configuration from environment variables. It is used to start a worker replica.

```bash
julep worker
```
Tokens:
Raw