> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jeanmemory.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate
> Generate recommendations by autoregressively decoding semantic IDs.
The value moment. Give the model a user's history and it emits semantic ID tokens one level at a time, exactly the way a language model emits text.
Beam search is constrained to prefixes that exist in the codebook, so the model cannot hallucinate an item that does not exist. Every returned sequence resolves.
```bash curl theme={"dark"}
curl https://api.jeantechnologies.com/v1/generate \
-H "Authorization: Bearer $JEAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tokenizer_id": "tok_9k2m",
"history": ["sku_310", "sku_884", "sku_771"],
"limit": 10,
"beam_width": 40,
"filters": { "in_stock": true }
}'
```
```python Python theme={"dark"}
recs = requests.post(
"https://api.jeantechnologies.com/v1/generate",
headers={"Authorization": f"Bearer {os.environ['JEAN_API_KEY']}"},
json={
"tokenizer_id": "tok_9k2m",
"history": ["sku_310", "sku_884", "sku_771"],
"limit": 10,
"filters": {"in_stock": True},
},
).json()
```
```ts TypeScript theme={"dark"}
const res = await fetch("https://api.jeantechnologies.com/v1/generate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.JEAN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
tokenizer_id: "tok_9k2m",
history: ["sku_310", "sku_884", "sku_771"],
limit: 10,
filters: { in_stock: true },
}),
});
const { recommendations } = await res.json();
```
## Response
```json theme={"dark"}
{
"recommendations": [
{
"item_id": "sku_402",
"codes": [1487, 302, 91, 12],
"tokens": "",
"score": 0.31
}
],
"beams_explored": 40,
"beams_pruned_invalid": 0
}
```
`score` is length-normalized sequence likelihood. It is comparable between candidates in one response and **not** comparable across requests, so use it to rank, not to threshold.
`beams_pruned_invalid` should be `0`. A nonzero value means beam search reached prefixes the codebook no longer resolves, which almost always means the serving codebook is stale relative to the catalog. Refit or re-sync before trusting the results.
## History matters
`history` is ordered, oldest first, and the order is signal. A user who viewed A then B is a different state from one who viewed B then A, and the model is trained to care.
Send the real sequence. Deduplicating it, sorting it, or collapsing it into a set throws away most of what makes a sequence model better than a co-occurrence table.
Long histories are truncated from the front, keeping the most recent interactions. If you have a strong reason to keep older context, say so during onboarding and we can weight the window differently for your tenant.
## Tuning beam width
| `beam_width` | Effect |
| ------------ | -------------------------------------------------------------- |
| = `limit` | Fastest. Greedy in practice, and recall suffers on tail items. |
| 4x `limit` | Default territory. Good recall for most catalogs. |
| 10x `limit` | Diminishing returns on quality, meaningful latency cost. |
Filters are applied during decoding rather than after, so a restrictive `filters` object needs a wider beam to fill `limit`. If you are getting back fewer results than you asked for, widen the beam before you loosen the filter.
## Feeding outcomes back
Generation is not the end of the loop. Send what actually happened to [`POST /feedback`](/api-reference/feedback/submit-feedback) so the model adapts to your objective rather than to a proxy. See [Foundation models](/products/foundation-models) for how the adaptation stages fit together.
## OpenAPI
````yaml POST /generate
openapi: 3.1.0
info:
title: Jean Technologies API
version: 1.0.0
description: >-
Foundation models of human behavior. Fit a semantic ID tokenizer on your
catalog, generate recommendations over it, and send outcomes back.
servers:
- url: https://api.jeantechnologies.com/v1
description: Production
security:
- bearerAuth: []
paths:
/generate:
post:
tags:
- Semantic IDs
summary: Generate
description: >-
Generate recommendations for a user history. The model autoregressively
emits semantic ID tokens, and beam search is constrained to prefixes
that exist in the codebook, so every returned sequence resolves to a
real item.
operationId: generate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateRequest'
responses:
'200':
description: Recommendations
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateResponse'
'400':
$ref: '#/components/responses/BadRequest'
components:
schemas:
GenerateRequest:
type: object
required:
- tokenizer_id
- history
properties:
tokenizer_id:
type: string
example: tok_9k2m
history:
type: array
items:
type: string
description: >-
The user's item interactions, oldest first. Order carries
preference, so send it in true sequence.
example:
- sku_310
- sku_884
- sku_771
limit:
type: integer
default: 10
minimum: 1
maximum: 100
beam_width:
type: integer
default: 40
description: Wider beams raise recall and latency. Must be at least `limit`.
exclude_history:
type: boolean
default: true
filters:
type: object
additionalProperties: true
description: Hard constraints applied to candidate items during decoding.
example:
in_stock: true
GenerateResponse:
type: object
properties:
recommendations:
type: array
items:
$ref: '#/components/schemas/Recommendation'
beams_explored:
type: integer
example: 40
beams_pruned_invalid:
type: integer
description: >-
Beams dropped for not resolving to a real item. Should be 0 under
prefix-constrained decoding; a nonzero value means the codebook is
stale relative to the catalog.
example: 0
Recommendation:
type: object
properties:
item_id:
type: string
example: sku_402
codes:
type: array
items:
type: integer
example:
- 1487
- 302
- 91
- 12
tokens:
type: string
example:
score:
type: number
description: Sequence likelihood, length-normalized.
example: 0.31
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: invalid_request
message:
type: string
example: Field 'domain' is required.
details:
type: object
additionalProperties: true
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key issued by Jean Technologies. Contact the team for access.
````