LGOS RAG¶

lgos-rag is an agentic retrieval graph over the Markdown corpus packaged with the demo API. It lazily splits and embeds that corpus into a process-local in-memory vector index, retrieves up to four chunks, and grounds answers with Markdown links and OpenAI url_citation annotations for the source URLs stored on those chunks.

LangGraph Topology¶

graph TD;
    __start__ --> generate_query_or_respond;
    generate_query_or_respond -.-> __end__;
    generate_query_or_respond -.  tools  .-> retrieve;
    retrieve -.-> answer_no_results;
    retrieve -.-> generate_answer;
    retrieve -.-> rewrite_question;
    rewrite_question --> generate_query_or_respond;
    answer_no_results --> __end__;
    generate_answer --> __end__;

Request Flow¶

flowchart TD
  start(["UI → LGOS /v1/responses<br/>User message"]) --> decide["Choose direct response or retrieval"]
  decide -->|"greeting, conversation, or unrelated"| direct["Direct response"]
  direct --> response(["LGOS /v1/responses → UI<br/>Assistant text"])

  decide -->|"LGOS factual question"| retrieve["Retrieve documentation"]
  retrieve --> grade{"Context relevant?"}
  grade -->|"yes"| answer["Generate answer with links and URL citations"]
  answer --> response
  grade -->|"no, first miss"| rewrite["Rewrite query once"]
  rewrite --> decide
  grade -->|"no after rewrite"| no_results["Answer that documentation is insufficient"]
  no_results --> response

The retry is deliberately bounded to one rewrite. Routing, grading, and rewriting use non-streaming internal model calls; retrieval uses the in-memory vector index. Direct, grounded, and no-result answers are the user-visible streamed nodes.

For a grounded answer, the graph adds annotations only for Markdown links whose URLs exactly match retrieved document metadata. Citation spans come from the actual generated link text; the model does not generate indices. Other resource links and images remain ordinary Markdown.

The graph also emits request-scoped status events while it understands the question, searches, checks sources, optionally rewrites, and prepares the answer. Streaming Responses exposes those updates as commentary for the maintained UIs; they are not persisted graph state. See status-events for the shared transport behavior.

State And Lifetime¶

The graph has no checkpointer or LangGraph Store. Any conversation history comes from messages supplied by the client. Each API process builds its own vector index lazily on the first retrieval, reuses it for that process lifetime, and rebuilds it after a restart. This is a demo optimization, not durable application data.

Try It¶