> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moonbounce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Moonbounce works

> The whole loop on one page, from a decision in your code to a better version you merge.

Moonbounce takes a judgment your app makes about content, such as "should we grant this refund?", and turns it into a **decision** you describe in code. Moonbounce runs the decision on each item you send, records every answer, asks you about the cases it is least sure of, and proposes better versions from what you tell it. You accept a better version the way you accept any change: by merging it.

This page gives you the whole picture with one running example. The guides that follow take each piece in turn: building a decision, running it, and improving it.

## The running example

An online store refunds unused items returned within 30 days, and its support bot handles those. Everything else, such as a late request or a used item, is an exception that needs judgment: grant the refund, send it to a person, or deny it.

The store's support app asks Moonbounce to make that call. The decision is called `refund-exception`, and a ticket like this one goes in:

> Order \$129, delivered 42 days ago, no refunds in the last year. The zipper on my sleeping bag ripped out the first night.

and an outcome comes out: `grant`. The app then does whatever `grant` means in its code.

## From content to an outcome

A decision doesn't ask a model "should we grant this?" in one go. It breaks the judgment into small yes/no questions, and combines the answers with a recipe you can read:

```mermaid theme={null}
flowchart LR
  T[Ticket text] --> Q1[outside_window?]
  T --> Q2[item_used?]
  T --> Q3[defective?]
  T --> Q4[repeat_refunder?]
  T --> Q5[high_value?]
  Q1 & Q2 & Q3 & Q4 & Q5 --> C[weighted_mean: grant_score]
  C --> S((value 0.766))
  S --> O{bands: handling}
  O --> G[grant]
```

1. **Questions** are asked about the content, such as "Does the customer describe a defect, damage on arrival, or the item failing under normal use?". An **engine**, a language model Moonbounce runs, answers each one with the probability that the answer is true. For the sleeping bag, `defective` comes back as 0.96. Each question can read only part of the content: `defective` reads the customer's message, `high_value` reads the order.
2. **Aggregations** combine answers. A `weighted_mean` turns the five answers into one value between 0 and 1. Your structure says which way each answer pushes: a defect argues for a grant, a late request against it.
3. **An outcome aggregation** turns the value into an outcome. The decision's `bands` are: below 0.38 is `deny`, from 0.38 is `escalate`, from 0.72 is `grant`. The sleeping bag's value is 0.766, so it lands on `grant`.

The questions, aggregations and cut points together are the decision's **structure**, a small JSON document that lives in your repository and travels with each call. If you already use System One, the structure is a System One request's `questions` plus the aggregations and a `result`.

Because every step is explicit, you can always see why an item got its outcome: which questions were answered how, and what every aggregation computed from them. You can also change one question without touching the others.

## Who owns what

Your code is the source of truth for what the decision is. Moonbounce runs it and learns from it, but never changes your production behavior on its own.

| Your code owns | Moonbounce owns |
| - | - |
| The questions and how they combine (the structure) | Asking the questions on an engine |
| Every weight, threshold and cut point, and the outcome names | Storing every evaluation, answer and piece of feedback |
| What your app does with each outcome | Picking which cases to ask you about |
| Merging a change | Proposing better versions, with evidence |

Nothing reaches your production traffic except through a merge in your repository. A suggestion from Moonbounce is a code diff your coding agent applies and you review, like any other pull request.

## The loop

The decision gets better through a loop of five steps:

```mermaid theme={null}
flowchart LR
  D[1. Describe] --> E[2. Evaluate]
  E --> F[3. Feedback]
  F --> I[4. Improve]
  I --> A[5. Accept]
  A --> E
```

**1. Describe the decision**

You, or your coding agent, write the structure: the questions, how they combine, and the outcomes. You seed it with about a dozen labeled examples so Moonbounce has cases to test changes against. [Describe a decision](https://docs.moonbounce.ai/learn/decisions.md).

**2. Evaluate items**

Your app calls `POST /v1/evaluate` with the content and the structure, and acts on the outcome. Every evaluation is stored with all of its answers. [Evaluate content](https://docs.moonbounce.ai/learn/evaluations.md).

**3. Give feedback**

When you learn the right answer, you tell Moonbounce: from your app, or by reviewing a short daily queue on your phone. The queue holds the cases whose answer would teach the most, plus random spot checks that measure how often the decision agrees with you. [Feedback](https://docs.moonbounce.ai/learn/feedback.md) and [Review](https://docs.moonbounce.ai/learn/review.md).

**4. Improve**

From your feedback, Moonbounce proposes one change, such as rewording a question or adding a missing one, and previews it: it replays the new version on your past cases and shows what it fixes, what it breaks, and how strong that evidence is. [Suggestions and previews](https://docs.moonbounce.ai/learn/improving.md).

**5. Accept through your merge**

Your agent applies the change to the structure in your repository and opens a pull request. You merge it, your app deploys it, and the new version starts serving. Moonbounce counts the suggestion as accepted when the new version first serves production traffic.

## One turn of the loop

The refund structure has no question about shipping. That's a gap: the refund policy says a late or lost delivery is the store's own failure and a reason to grant. Here is how the loop closes it.

1. A ticket comes in: "The tent showed up two weeks late (stuck at the regional hub), I used it once on the trip it was for." It's 39 days after delivery. No question captures the late delivery, so the value is 0.540, between the cuts, and the outcome is `escalate`. A person has to look at it.
2. The person who handles the escalation grants the refund, and the decision's owner tells Moonbounce it should have been `grant`, with the reason "The carrier delay ate their return window; that's our failure." They also confirm that two answers were right: the request is past the window, and nothing is broken. So the problem isn't a wrong answer but a missing question.
3. After a few cases like it, some sent as feedback and some answered in the owner's review queue, the developer's coding agent asks for a suggestion. Moonbounce finds that no existing question explains these misses, and drafts a new one: did the carrier deliver the order late, or lose it? Added to the plain average, it breaks more than it fixes (the ripped-zipper ticket would lose its `grant`), so Moonbounce proposes nothing and says why.
4. The question is right; the way it joins the average is not. The developer groups it with `defective` as one "our fault" reason in `moonbounce/refund-exception.json` and previews the change on the decision's past reviewed cases: the carrier-delay tickets now land on `grant`, and the ripped zipper keeps its `grant`. The coding agent opens a pull request, and the developer reads the diff and the preview, and merges.
5. The support app deploys, and its next refund request runs on the new version.

## Three ideas to hold on to

* **Your code is the source of truth.** The structure, with every weight, threshold and cut point, lives in your repository and changes in one pull request. What merges is exactly what was previewed.
* **A version is a hash.** The **structure hash** identifies the questions, how they combine and where the cuts are. There are no drafts and no version numbers: any structure you send is a version the moment it arrives, and two structures that differ only in formatting or key order get the same hash. [Versions and hashes](https://docs.moonbounce.ai/learn/versions.md).
* **Nothing is learned behind your back.** Every aggregation does exactly what its definition says. A better version arrives as a change to your structure, which you review and merge. [Aggregations](https://docs.moonbounce.ai/learn/aggregations.md).

## What Moonbounce doesn't do

* You write questions in plain words, and the engine sees each one as you wrote it, over the part of the content it reads.
* It doesn't take actions. It returns an outcome name, and your code decides what that means.
* It runs one decision per call. If your app chains decisions, chain them in your code.
* It reads text and JSON today. Images, audio, video and documents are refused with a clear error until an engine supports them.

## Next

Start with the structure itself: [Describe a decision](https://docs.moonbounce.ai/learn/decisions.md) builds the refund decision one piece at a time. If you'd rather run something first, the [Quickstart](https://docs.moonbounce.ai/quickstart.md) takes about ten minutes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.