Guide

This directory is the home of OpenProgram's own programming model — the concepts you will not find in a generic LLM-framework tutorial, collected in one place. If you are writing functions for OpenProgram (or deciding whether to), read here first; the generic project docs (install, API index, troubleshooting) live in the other tabs. For the paradigm's background, see the philosophy.

Learning path

Read in order; each step builds on the previous one.

#	Doc	What it teaches
1	philosophy.md	Why "agentic programming" — the rationale behind the model
2	writing-functions/agentic-function.md	@agentic_function: wrap a Python function whose body runs single LLM calls via llm(); composition patterns
3	writing-functions/function-metadata.md	Parameter descriptions, placeholders, hidden arguments, render_range — the source of truth for function metadata
4	writing-functions/pure-python.md	When NOT to use the decorator: plain deterministic helpers
5	embedding-in-your-own-stack.md	Using the model as a plain library inside your own app or framework — bring your own LLM call, point state at your own directory

Choosing the next step

OpenProgram gives you three ways to decide "what runs next" inside a function. They are not alternatives to learn once and forget — picking the right one per task is the core skill:

Doc	Mechanism	Use when
choosing-the-next-step/fixed-order-calls.md	Python code calls sub-functions in a fixed order	The step order is known ahead of time (pipelines: draft → review → revise)
choosing-the-next-step/tool-calling.md	Provider-native tool use: the model picks a function each turn, loop until it answers in text	Open-ended work where the model decides how many and which calls to make
choosing-the-next-step/next-step-decision.md	decision.make(prompt, options) / runtime.exec(..., choices=...): a text menu of options, the choice itself resolves into the next result	Routing / finite branches; options may be plain values, not just functions; no provider tool-use support needed

Reference

• ../../reference/api/agentic-function.md — decorator API quick reference
• ../../reference/api/runtime.md — Runtime.exec() parameters and behaviour
• Agentic function API — authoring and validation conventions for functions
• ../../reference/design/function/calling-unification.md — internal design notes on the function-calling framework (evolution / refactor plans, not needed for authoring)
• LLM-as-Code: Agentic Programming for Agent Harness (arXiv:2606.15874) — the paper describing the paradigm, accepted at the KDD 2026 AgenticSE workshop