Calypso Context · Citas
Una respuesta con fuentes lleva citas en línea ancladas al texto por posición de caracteres, y una lista estructurada de las fuentes que usó: número de fuente, etiqueta, página, modalidad y un enlace firmado para abrir el original. Tu aplicación renderiza referencias sin analizar la respuesta.
El ejemplo
El modo nativo mantiene la respuesta con forma OpenAI: anotaciones sobre el texto, fuentes en file_search_call.results. Nada que analizar, nada propietario que aprender.
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["CALYPSO_API_KEY"],
base_url="https://api.calypso.so/v1")
resp = client.responses.create(
model="calypso-agent",
input="What is our refund policy?",
metadata={"citation_compat": "native", "sources_appendix": "omit"},
)
print(resp.output_text)
for item in resp.output:
if item.type == "file_search_call":
for r in item.results:
a = r.attributes
print(f"[{a['source_index']}] {a['label']}") # refund_policy_2026.pdf (p. 4)Dos superficies
Ambos endpoints llevan citas. Responses expone toda la superficie estructurada; Chat Completions se limita a la forma url_citation que define esa especificación.
Recomendado. En streaming envía un evento annotation.added por cita y los resultados completos en response.completed.
Las fuentes de archivos y medios se mapean a url_citation con una URL firmada cuando existe y el nombre de archivo como título. En streaming, las anotaciones llegan en un último fragmento.
Los atributos
Los mismos atributos aparecen en los resultados de Responses y en los de Search. Construye tu lista de fuentes directamente desde ellos.
| source_index | Número de fuente estable, desde 1, que coincide con el orden [n] del texto. Úsalo para las insignias y la lista. |
|---|---|
| label | Listo para mostrar, por ejemplo refund_policy_2026.pdf (p. 4). Si no hay más, usa el nombre del archivo. |
| page_number · page_label · locator_label | Dónde dentro del documento, cuando se sabe. Los PDFs citan la página; otros documentos citan el archivo. |
| modality · mime_type | text, multimodal o image, y el tipo MIME. Una cita a una imagen apunta a la propia imagen. |
| access_url · media_id | Una URL firmada para abrir el original cuando existe, e identificadores de medios para vistas previas. |
| text · excerpt · preview | La evidencia citada que usó la respuesta, más descriptores estructurados de extracto y vista previa. |
Cómo funciona
Llama a Responses con calypso-agent o con un agente con nombre. La recuperación corre sobre sus buckets y la evidencia vuelve con la respuesta.
Cada anotación lleva start_index y end_index. Coloca tus marcadores [n] desde las posiciones, numerados por source_index.
Renderiza la lista de fuentes desde los atributos y enlaza cada entrada a su access_url para que el lector pueda comprobar la página.
Renderizado
01
Usa start_index y end_index para colocar referencias. No extraigas tokens [n] del texto.
02
Es estable, empieza en 1 y coincide con el orden de las citas. Úsalo para insignias y lista.
03
Aplica las anotaciones en orden descendente de start_index para que las inserciones anteriores no desplacen las posiciones posteriores.
04
Muestra un panel de fuentes solo cuando grounded_sources_state es available. hidden significa que la política oculta las fuentes; missing y none significan que no hay nada que mostrar.
De la documentación
| Modelo | Anotaciones OpenAI: objetos de cita anclados al texto por posición de caracteres; el texto de la respuesta se mantiene plano |
|---|---|
| Responses | output[] → message → output_text.annotations[] · output[] → file_search_call.results[] |
| Chat Completions | choices[0].message.annotations[] (url_citation) + "Sources:" appendix |
| Modos de compatibilidad | metadata.citation_compat: legacy | native · metadata.sources_appendix: include | omit |
| Evento de streaming | response.output_text.annotation.added |
| Citas por página | PDFs, que se leen como imágenes de página; las imágenes citan la imagen; otros documentos citan el archivo |
| Estados de grounding | available · hidden · missing · none |
Preguntas y respuestas
Sigue leyendo
PDFs, imágenes, páginas y datos. Qué lee y cómo entra.
Memoria de fuentes acotada y duradera. Provisiona por slug, vincula a agentes.
Uno por defecto y los agentes con nombre que quieras, cada uno con su alcance y política.
Recuperación sin generación: los pasajes que una respuesta citaría, ordenados.
Tuyo, aislado: sin entrenar con tus datos, exporta o borra cuando quieras, claves con permisos explícitos.
La referencia desde la que está escrita esta página, con cada endpoint y campo.
Empieza hoy
Carga un bucket, pregunta a calypso-agent y renderiza la lista de fuentes desde la primera respuesta.