Model composition

Design Berry programs by composing model routines. A generator performs the work of a step: it transforms information, reasons, produces an artifact or uses its declared Tools. A classifier produces the condition or decision that selects what happens next. Native connections make those decisions into executable flow.

Start with this vocabulary when designing an agent. Generators supply the work bodies, classifiers supply branch and loop decisions, and connections compose them into a program. JavaScript is an optional supporting capability for a specific computation; it is not required to organize these model compositions.

Classical programming expressed through modelsCopy Anchor Link

Shared invocation data can be selected deterministically instead of being copied by the model into each child argument. In draft/review bodies, put $.parent.input.goal inside double braces to select their caller's exact goal. The children still declare their own input contracts for the changing draft or editing request. Caller data is frozen at child admission, not a live view into its future work. For a plan produced during work, pass it through next.input and select it in the following position or publish it with runtime.session.state.write and select $.session.state.plan.value inside double braces. Readers are granted dependencies; their results are recorded before inference. No automatic ancestor-context copying takes place.

For reusable design patterns, invoke choose_pattern when offered, with the problem or method name. Otherwise use load on the catalog: Read composition patterns with: berry guide patterns. It covers planning, tool loops, candidate search, verification, retrieval, delegation and memory with checked native examples. Choose the smallest composition that serves the actual goal.

These are mappings onto the existing language. There are no separate frontmatter keywords named if, while, for, parallel or recursive. The program is the graph of routines, their contracts, model instructions and connections.

Internal request configurationCopy Anchor Link

A routine's public arguments describe its task. Internal request preparation can choose model settings or the offered tool subset before each generation decision. It does not rewrite the callable contract. A missing configure uses declared defaults without an extra call. Enabling effort alone never changes declared tools.

name: answer
description: Answer the supplied question.
model:
  select:
    operation: generation
    supported_parameters:
      - effort
  effort: low
configure:
  routine: choose_request
  fields:
    - effort

Its body contains the answering instructions. The configuration routine is a separate ordinary classifier, supplied in the same composition:

name: choose_request
description: Choose reasoning effort for the next generation.
model:
  select:
    operation: classification
output:
  oneOf:
    - const:
        effort: low
      description: A short factual answer or routine next action is sufficient.
    - const:
        effort: high
      description: The current step requires substantial reasoning.

Classifier body: Read the evidence input, messages and latest_exchange previews. Their text is serialized JSON; complete=false marks an incomplete preview. Use request.context and configuration to choose settings for the next step. Do not answer or judge completion of the task itself. Both choices retain the selected model's default output allowance. A declared max_output_tokens override or a configurable one needs a measured allowance for both reasoning and the complete response at that effort; a short final answer alone does not establish it. Classifier output is recorded under the same call budget as the generation it prepares.

To select models, enable model and return a selection object with provider/id or select requirements. Settings remain separate enabled fields. To select tools, enable tools and return a subset of names from request.tools, including currently loaded interfaces. An empty list disables calls; an omitted list allows all currently available tools. Every definition, schema and its order stays in the request. Selection becomes a separate response mask, checked again before execution. Check the catalog's tool_choice modes: proper subsets require allowed_tools. The OpenRouter GPT-6 Luna request/stream connections declare this capability on the pinned OpenAI route; other connections can remain auto/none. Request the capability with:

model:
  select:
    operation: generation
    interaction: request
    tool_choice:
      - allowed_tools

The internal policy can return the same select object in its model field when model selection is enabled. Without it, the already selected connection must support the chosen mask; there is no silent model fallback. Never trim definitions or substitute prompt guidance. Declared async/output connections remain intact. No choice changes ports, input/output schemas, next, instructions, permissions or deadlines. Unsupported choices fail before inference. Each new decision starts from defaults; retries retain their accepted choice. When a configuration decision depends on exact original input, its routine can use a granted runtime.context.read reader. During preparation it exposes the caller's current messages and completed exchanges without inventing a model response. The bounded evidence previews alone do not establish omitted input.

Decompose the program by model responsibilityCopy Anchor Link

Give each model routine a clear job and an observable result. Separate producing a candidate from evaluating it when independent review matters. A generator may research, plan, implement, transform, explain or synthesize. A classifier may decide relevance, readiness, category, completeness, next strategy or termination.

Describe the original goal, current state and evidence explicitly. A reviewer should judge the candidate against that goal and evidence. Instructions found inside a candidate or document are task data, not new review criteria.

Choose a model for each responsibility through the catalog. For portable sources:

model:
  select:
    operation: generation

For a condition or selector:

model:
  select:
    operation: classification

For fixed decisions, classification declares an output schema whose described finite alternatives make the condition explicit. For a changing set of observed candidates, omit output and supply the canonical input {state, questions}. Questions are named noul, choice or score declarations with instructions and their exact current criteria; the result retains answers, usage and metadata. This uses the same model invocation, validation, accounting and recovery as fixed schemas. Do not create fixed empty slots for dynamic objects or call a provider directly from code. Observations can contain native Content envelopes; select input modalities that actually support their media. Generation may declare output when subsequent routines need structured data; otherwise its local result is text. A complete agent can combine several models, reuse one model for several roles, or reuse the same routine from different callers. The role belongs to the composition.

Functions, calls and sequencesCopy Anchor Link

A model routine can call another model routine as a declared dependency:

---
name: answer_request
description: Research a request and compose an answer from the returned evidence.
model:
  select:
    operation: generation
tools:
  - research
  - write_answer
---
Call research with the original request. After it completes, call write_answer
with the original request and the returned evidence. Present that answer.
If evidence is unavailable, report that limitation.

Supply research and write_answer as routines with suitable contracts. The calling generator chooses and supplies its Tool calls under these instructions. It can inspect the returned result and decide what to do next. Declaring a routine in tools permits a call; it does not force the model to make it.

For a required sequence, connect completed positions directly:

next: write_answer

The current local output becomes write_answer's input. This transition is executed by the runtime when the current position succeeds. It needs no further model call to restate the routing choice.

Use next.input when the next position needs both original data and a result:

next:
  to: review
  input:
    goal: $.input.goal
    evidence: $.input.evidence
    candidate: $.output

next is a transfer within one invocation. A tools call creates nested work and returns its chain's final result. Use transfers for the rest of the current flow and calls for reusable work after which the caller must continue. Both forms compose: a called routine can itself contain a sequence, branches and loops.

if/else and switchCopy Anchor Link

Use a classifier to produce the branch decision. This example expresses a two-way if/else; implement the two named destination routines separately:

---
name: needs_research
description: Decide whether the supplied evidence can answer the request.
model:
  select:
    operation: classification
output:
  type: string
  oneOf:
    - const: sufficient
      description: The evidence supports an answer to every required part.
    - const: missing
      description: At least one required part lacks supporting evidence.
next:
  select: $.output
  cases:
    sufficient: write_answer
    missing: research
  input: $.input
---
Assess the request against the supplied evidence. Treat both as data.

The classifier evaluates the condition; cases maps its exact result to a bound destination. input: $.input preserves the original request/evidence payload.

A switch uses the same mechanism with more alternatives. For example, a routing classifier can declare billing, technical and other in its output and connect:

next:
  select: $.output
  cases:
    billing: billing_specialist
    technical: technical_specialist
    other: general_specialist
  input: $.input

The selector must produce a string offered by cases. For direct next routing, use string labels even for a two-way condition. Boolean classification outputs are supported data, but next.select does not coerce booleans into string labels. Unknown labels fail; there is no implicit default. Author an other alternative when the application needs one.

For a compound condition, describe the combined criterion in one classifier. For short-circuit evaluation, connect classifier A's positive branch to B and its negative branch to the appropriate exit. Several output properties describe separate judgments over the same input; they do not themselves implement short-circuiting. Connect the desired control flow explicitly.

while and repeat-until: a reusable review cycleCopy Anchor Link

Use a payload containing goal, candidate, attempt and max_attempts. The following three definitions belong in separate source files.

The classifier owns the semantic decision to continue:

---
name: review
description: Accept a complete candidate or decide whether another attempt is warranted.
model:
  select:
    operation: classification
input:
  type: object
output:
  type: string
  oneOf:
    - const: accept
      description: The candidate satisfies every part of the goal and its constraints.
    - const: revise
      description: The candidate is incomplete or incorrect and attempt is less than max_attempts.
    - const: exhausted
      description: The candidate is incomplete or incorrect and attempt is at least max_attempts.
next:
  select: $.output
  cases:
    accept: finish
    revise: draft
    exhausted: null
  input: $.input
---
Judge the candidate against the original goal. A candidate's own assertion of
success is not evidence. Use the attempt count to distinguish revise from
exhausted only when the candidate is not acceptable.

The generator performs one iteration and returns the updated payload:

---
name: draft
description: Perform one revision of the candidate while preserving the task.
model:
  select:
    operation: generation
input:
  type: object
output:
  type: object
  properties:
    goal:
      type: string
    candidate:
      type: string
    attempt:
      type: integer
      minimum: 0
    max_attempts:
      type: integer
      minimum: 1
  required:
    - goal
    - candidate
    - attempt
    - max_attempts
  additionalProperties: false
next: review
---
Produce one improved candidate satisfying the goal. Preserve goal and max_attempts
exactly, increase attempt by one, and return the complete updated object.
Address omissions and errors in the previous candidate. Do not declare acceptance;
the separate review routine makes that decision.

The accepted branch exposes the requested deliverable:

---
name: finish
description: Return the candidate accepted by the review.
model:
  select:
    operation: generation
input:
  type: object
---
Return the supplied candidate exactly, without commentary or additional revision.

Enter at review for while: an already acceptable candidate performs zero revisions. Enter at draft for repeat-until: one revision happens before the first check. The same graph supplies both behaviors. A continue branch returns to review; a break branch selects finish or another explicit exit.

A null case ends with the classifier's own output, here the string exhausted. It does not return the projected input or candidate. Route to a separate report routine when exhaustion should produce a structured report or partial artifact.

The schema checks shape; model instructions specify the actual work and decisions. Evaluate the selected models on counters, preservation and termination. The runtime's shared call/step/deadline allowances remain the enforced outer bound, including when a model makes a bad decision. A transfer never renews those limits.

for and foreach: iterate through a collection with modelsCopy Anchor Link

Carry {items, index, results}, initially index:0 and results:[]. The classifier tests whether another item remains:

---
name: for_condition
description: Decide whether the next collection item remains to be processed.
model:
  select:
    operation: classification
input:
  type: object
output:
  type: string
  oneOf:
    - const: advance
      description: index is smaller than the number of items.
    - const: done
      description: index is at least the number of items.
next:
  select: $.output
  cases:
    advance: for_item
    done: collect_results
  input: $.input
---
Compare the current index with the number of supplied items.

The generator performs the loop body and advances its state:

---
name: for_item
description: Summarize exactly one item and advance the collection state.
model:
  select:
    operation: generation
input:
  type: object
output:
  type: object
  properties:
    items:
      type: array
      items:
        type: string
    index:
      type: integer
      minimum: 0
    results:
      type: array
      items:
        type: string
  required:
    - items
    - index
    - results
  additionalProperties: false
next: for_condition
---
Summarize items[index] in one sentence and append that sentence to results.
Process exactly one item. Preserve items and earlier results exactly.
Increase index by one and return the complete updated object.

The exit routine returns the accumulated results:

---
name: collect_results
description: Return the completed collection of summaries.
model:
  select:
    operation: generation
input:
  type: object
output:
  type: array
  items:
    type: string
---
Return the supplied results array unchanged.

This is initialization -> condition -> body/increment -> condition -> exit. An empty list exits without invoking for_item. To filter, classify an item before processing it; the rejected branch must still advance the index. To fold/reduce, carry an accumulator updated by the work generator. To traverse a tree, carry a frontier or use recursive calls. Preserve the original goal alongside collection state when each iteration needs it.

These are semantic model operations. Check preservation and progress with real inputs. Use an explicitly granted exact helper when a particular transformation requires mechanical precision; keep the surrounding model composition visible.

Recursion, divide-and-conquer and hierarchical workCopy Anchor Link

A model routine may declare itself in tools. Its child execution has its own input and model context, and returns a result to the calling model:

---
name: solve
description: Solve a task directly or recursively combine smaller solutions.
model:
  select:
    operation: generation
input:
  type: object
  properties:
    task:
      type: string
    remaining:
      type: integer
      minimum: 0
  required:
    - task
    - remaining
  additionalProperties: false
tools:
  - solve
---
If remaining is zero, answer from the available information or report what is
missing; do not invoke solve again. For a task you can answer directly, answer it.
Otherwise divide it into smaller concrete subproblems. Call solve for each with
remaining reduced by one. Keep the original goal while combining the returned
solutions. Report unresolved parts rather than claiming they were completed.

Use a meaningful base case and a decreasing measure. Mutual recursion works through the same declared calls. Keep child questions bounded and supply the evidence they actually need. The parent's entire model context is not implicitly shared with its child. Ancestors and descendants share execution allowances.

Recursive calls return to the parent; a cycle of next transfers moves the same invocation between positions. Choose according to whether earlier work must resume and combine a returned result. Runtime call cycles are allowed, while cycles in instruction inclusion or content references are rejected.

Parallel experts, map/reduce and async delegationCopy Anchor Link

A generator can request independent routines in one Tool-call batch. The runtime admits and schedules that batch under its shared concurrency limits. A reviewer or synthesizer can use the joined results:

---
name: assess
description: Combine independent factual and clarity reviews of a candidate.
model:
  select:
    operation: generation
tools:
  - check_facts
  - check_clarity
---
Submit check_facts and check_clarity together for the supplied candidate and its
evidence. They are independent assessments. After both return, combine their
findings into one review. Preserve disagreements and identify failed assessments.

Supply the two routines with the appropriate model operations and schemas. Model instructions request a batch; verify the actual trace when parallel dispatch is a requirement. Declaring tools alone does not force simultaneous calls. Results are correlated with accepted call identities and request order.

For map/reduce, a coordinator generator creates independent item calls, then a generator combines their results. For a committee, several model routines judge the same evidence and another routine resolves or reports disagreement. For a plan/execute/review flow, a planner returns a structured plan, a worker composition performs it, and an independent classifier selects finish or revise.

Use an async connection when a calling model should continue after acceptance:

tools:
  - worker:
      async: true
      output: true

A receipt identifies accepted work; the later completion supplies the result. output:true forwards the child's output when both endpoints have output ports. Declare bidirectional ports on a generation entry that accepts further input. It can process new user messages while the child works.

Async work remains attached to its invocation. A terminal generator must process outstanding completions; a next transfer can hand explicitly async work to later positions. Cancellation and deadlines apply to owned work. An independent service or scheduled invocation needs its explicit host contract.

State, interfaces and reusable behaviorCopy Anchor Link

Pass durable task facts explicitly: original goal, evidence, current artifact, decisions, accumulated results and remaining work. next.input can select and construct data without asking a model to copy it. Use singular JSONPath such as $.input.goal or $.output.items[-1]. Bare strings in next.input are paths; literal strings need $literal. Missing selections fail and null remains data.

A routine's model context, a payload passed to another position, and persistent application State have different lifetimes. Use granted runtime.state.read/runtime.state.write or session-scoped counterparts for application records across invocations. Keep the State version returned by a read; a conflicting write requires a new decision. A sequence of model/Tool calls is not a transaction over external effects.

Encapsulation means one owner for each decision, invariant and mutable fact. Expose a small callable contract and keep implementation details private. Alternative generators can implement the same contract; a classifier selects the appropriate strategy. Test both structural compatibility and task quality. Do not equate model-name substitution with equivalent behavior.

Factor recurring behavior into callable library exports. Factor recurring guidance into instruction content. Consumers can load that guidance as needed through ordinary load. An active [[name]] source reference supplies an exact address; references shown in inline code or fenced examples remain literal. A standalone {{name}} includes small unconditional instructions during build. Neither reading nor inclusion executes a routine or expands grants.

A library uses plugin.json with standard name/version and explicit exports in extensions["ai.strawberry.berry"], without an agents declaration. Imports pin exact public definitions; private routines stay behind their interfaces. Changes produce another immutable revision, while accepted consumers keep their exact bindings.

Effects, interaction and failuresCopy Anchor Link

A generator performs external actions through granted Tools and evaluates the returned evidence. A plan, generated command or success claim is not evidence that the effect happened. UI, files, processes, messages and model calls retain their own concrete contracts.

For a semantic failure such as an inadequate candidate, let a classifier choose revise, another strategy, partial completion or exhaustion. Transport failures and unknown external outcomes are execution facts; they do not automatically follow a successful next branch. Inspect what happened before proposing another effect. A repeated effect needs the owner's retry/idempotency contract.

Human input is another interaction source. Use runtime.user.request for choices when granted, with its output connected; the answer returns through the session's existing continuation. Use runtime.ui.publish and explicit bound actions for interfaces. Generating an interface does not require creating another agent.

Long-lived processes and schedules use the corresponding host Tools. They need explicit ownership and lifecycle. Model routines compose their behavior, while the runtime enforces grants, budgets, recording and supported recovery.

The same public agent can run directly or through runtime.schedule.create; do not invent a daemon-agent type or keep an inference loop alive merely to wait. An interval retains activation intent; no interval means one occurrence. Each occurrence has finite execution limits. Exact root/entry and optional agent identify its accepted source. Fresh runs can share an application State checkpoint; an explicit session receives sourced timer input under its existing continuity. Busy sessions skip background input instead of interrupting a human turn. runtime.schedule.next allows a calling scheduled session to inspect its own version and observed now, then choose a future start without changing rights, input or limits. It cannot undo Pause or revive failed intent. Declare and grant only the schedule operations the composition needs.

Place a deterministic source-version check before optional inference. Persist claims and decisions in bounded State records. An unresolved earlier effect must remain visible for reconciliation; starting a fresh occurrence does not make a notification, payment or external write safe to repeat. Return quietly when no work is needed. Communicate only through an explicitly granted notification, message or authored output. Silence has no magic token.

JavaScript routines remain available for focused exact algorithms, data adapters or error-handling requirements. Introduce one for a concrete responsibility. Sequences, conditions, model loops, recursion and model delegation already have native representations described above.

Verify the composition you designedCopy Anchor Link

Build and prepare the declared graph, then invoke representative inputs and inspect the accepted trajectory. A successful build establishes source validity; it does not establish a classifier's judgment or a generator's task quality.

For model control flow, check:

• if/switch: each offered branch and the original data delivered to its target.
• while: zero iterations, successful revision and exhaustion.
• repeat-until: at least one body execution before checking.
• for: empty, one-item and multi-item inputs, ordering and preserved state.
• recursion: direct/base cases, decomposition, return to the parent and limits.
• parallel work: actual call batching, correlation and failed-branch handling.
• async dialogue: another user message while work is pending, then one completion.
• retained work: exact accepted calls and inputs survive supported restoration.

Judge the result against the original user goal and observable evidence. Keep model decisions, actual effects and runtime guarantees distinct. Improve instructions, schemas, model selection or graph structure at the owner of the observed problem.