Nexus queries

A query is a single turn: a question in, a grounded answer out. A multi-turn conversation is a session. Rather than stuffing raw chunks into a prompt, Pinecone Nexus runs an agent loop in which the model writes Python against a retrieval SDK to gather just the evidence it needs, then composes a grounded answer with citations.

The usual ways to answer over a corpus both struggle. Agentic RAG issues many retrieval calls and burns tokens stitching them together, and a coding agent greps and parses raw files, which is powerful but slow, expensive, and unreliable.

A query turn does the hard retrieval work in one place. The model writes Python that reads artifacts, runs search, walks the graph, and queries structured tables, then answers from only the evidence it surfaced. Raw tool output never enters the model's context.

A query is run by the Nexus runtime, a single generic Python image the orchestrator launches fresh for each turn. There is no per-context code. Every context runs the same entrypoint, parameterized by its manifest.

1. A fresh container per turn: Each query spawns one isolated container that runs exactly that turn, then exits. It pulls the scoped contexts' curated knowledge: artifacts on disk plus their vector index.
2. Orientation: The runtime reads the manifests and an artifact outline up front, so the model starts knowing what knowledge exists and where.
3. The agent loop: The model writes Python into a persistent REPL to call the retrieval SDK, reading artifacts, running search, walking the graph, querying structured tables.
4. Step events: Each step is posted back as it happens, powering the live answer stream you see in the console. You can replay the full sequence for any query with query tracing.
5. Synthesis: Once enough evidence is gathered, the runtime composes a grounded answer with inline citations, then finalizes the turn.

The model's primary tool is run_python, a persistent REPL. Variables survive across calls, so the model chains operations together: find an artifact, read it, filter its sources, drill for a verbatim quote, all in one block. It processes results in code and prints only what it needs.

If the first pass misses, the model refines its code and searches again, so hard questions get more work, not a worse answer. The loop stops as soon as the model can answer.

# One turn: find an artifact, read it, drill its sources.
art = await search_knowledge("acquisition terms", kind="summary")
srcs = read_artifact(art[0].name).sources
for h in await search_in_sources(srcs, "purchase price"):
    print(h.fields["source_path"], "::", h.fields["chunk_text"][:160])

Independent searches run concurrently, and lookups already held in a variable are never repeated. The loop is capped, so the model is pushed to extract everything it needs and answer in a few steps.

The Composable Retriever pre-binds these primitives into the REPL. Read artifacts cheaply off disk, fall back to search over the index, and reach for SQL when the question is a count or enumeration.

Synthesis from surfaced evidence. The answer is composed from just the evidence the code surfaced, never the raw corpus, so the model reasons over a small, relevant context instead of the whole document set.

Citations that trace to a source. Inline citation markers map back to real source spans: the file, page, and verbatim text behind every claim.

Optional structured output. When a shape is supplied, the answer is routed through structured synthesis to produce a schema-conforming document instead of prose.