ONIX RAG integration

Status: Architecture contract for later integration. No ONIX adapter has been implemented or deployed.

ONIX should not need to reproduce LibreChat internals to use the Bauer retrieval system. The long- term boundary is one client-independent RAG service with thin host adapters.

This page explains how the existing versions could be reached from ONIX and why V4 is being designed as the preferred integration target.

Integration principle

flowchart LR
    U["ONIX user"] --> Agent["ONIX Agent/UI"]
    Agent --> Adapter["ONIX RAG adapter"]
    Adapter --> Auth["ONIX identity to signed RAG scope"]
    Adapter --> API["Versioned RAG API"]
    API --> Release["Server-pinned knowledge release"]
    Release --> Evidence["Authorized evidence"]
    Evidence --> Response["Answer + citations + coverage"]
    Response --> Agent

ONIX owns:

• user experience;
• conversation and session state;
• organization/project selection;
• display of answers and citations;
• ONIX identity and access policy.

The RAG service owns:

• knowledge releases;
• source authorization enforcement;
• parsing and canonical evidence;
• retrieval and reranking;
• grounded answering;
• citation identity;
• answer validation;
• retrieval observability.

Neither system should reach into the other's database.

Version compatibility

Version	ONIX integration possibility	Limitation
V1	Wrap the existing /query_multiple route	Generic chunk retrieval and LibreChat-shaped file permissions
V2	Wrap /query_v2 with authorized file IDs	Better quality, but service and answer flow remain coupled to the current RAG API
V3	Adapt signed scope and /v3/answer	Strong controls, but the current final boundary and query contract are LibreChat-specific
V4	Use the host-neutral V4 API	Designed for full-question transport, typed coverage, stable citations, and multiple clients

V1–V3 can be exposed to ONIX for demonstrations or comparison through adapters. New ONIX product work should target the V4 contract rather than copying a LibreChat integration.

V4 request boundary

An ONIX request will conceptually contain:

{
  "request_id": "opaque-id",
  "question": "complete original ONIX user question",
  "search_hint": "optional",
  "conversation_context": [],
  "locale": "de-DE",
  "client": {
    "type": "onix",
    "instance": "company-environment"
  },
  "authorization": {
    "signed_scope": "short-lived in-memory assertion"
  }
}

The ONIX adapter may also pass typed filters selected in the UI, such as project, product, document, revision, language, or lifecycle state. Those filters are additive constraints. They do not replace the user's full question.

The ONIX client may not:

• select an arbitrary release;
• submit unrestricted source IDs;
• bypass tenant or knowledge-base scope;
• send database credentials;
• treat a search phrase as the complete user task.

V4 response boundary

The response will distinguish a complete answer from supported partial information:

{
  "status": "partial",
  "answer": "Supported answer text",
  "coverage": [
    {
      "field": "motor_power",
      "status": "supported",
      "citation_ids": ["E-..."]
    },
    {
      "field": "ambient_temperature_limit",
      "status": "not_found",
      "citation_ids": []
    }
  ],
  "not_found": ["ambient_temperature_limit"],
  "citations": [],
  "release": {
    "public_id": "opaque-id"
  },
  "trace_id": "opaque-id"
}

ONIX can render:

• the main answer;
• source cards;
• document/page/table locations;
• supported versus missing fields;
• ambiguity or contradiction warnings;
• a trace identifier for support.

The client should not infer that an absent field is zero, false, or approved.

Authorization mapping

The exact ONIX identity model is still to be defined. The adapter must eventually map:

ONIX concept	RAG scope
user/service principal	principal
company/organization	tenant
selected project or knowledge collection	knowledge base
document permissions	authorized external source IDs
ONIX environment	signed audience/client instance

The assertion should be short-lived, audience-bound, nonce-protected, and generated server-side. The RAG service intersects it with the pinned release membership and PostgreSQL RLS.

ONIX should never reuse a LibreChat administrator token or LibreChat MongoDB authorization record.

Agent behavior

An ONIX Agent using V4 should:

1. pass the complete original question;
2. preserve explicit units, identifiers, requested fields, and exclusions;
3. pass UI filters as typed constraints;
4. allow V4 to decompose multi-part questions internally;
5. display partial and not_found states honestly;
6. render citations using stable evidence IDs;
7. avoid a second unconstrained synthesis step that can alter V4's validated answer.

If ONIX needs to combine RAG evidence with ERP, PLM, CAD, or calculation tools, its Agent may orchestrate those tools. V4 remains responsible only for the evidence task it was given. Tool results should remain distinguishable by authority and source type.

Portable implementation artifacts

V4 must provide:

• OpenAPI specification;
• JSON Schema request and response definitions;
• a generated or minimal TypeScript client;
• a Python reference client;
• authorization assertion examples without secrets;
• adapter contract tests;
• citation and coverage rendering fixtures;
• timeout, retry, idempotency, and error semantics;
• version-compatibility policy.

LibreChat will be the first consumer of the same contract. Passing LibreChat adapter tests therefore validates the service contract but not ONIX-specific identity or UI behavior.

Later ONIX integration sequence

When ONIX implementation begins:

1. document the ONIX identity, organization, project, and document-permission model;
2. select the RAG tenant/KB mapping;
3. implement signed-scope issuance in the ONIX backend;
4. generate or implement the V4 API client;
5. render answers, citations, coverage, and missing fields;
6. run the shared adapter contract suite;
7. add ONIX authorization-negative and usability tests;
8. compare equivalent LibreChat and ONIX requests against the same fixed release;
9. deploy privately before exposing company users.

No RAG compiler, retrieval, or validation code should be forked into ONIX.

Open Questions

• What is the canonical ONIX user and organization identity?
• Does ONIX select a company knowledge base, a project knowledge base, or both?
• Which ONIX roles may view document text, metadata, or only derived answers?
• Will ONIX combine V4 evidence with live ERP/PLM tool calls in one Agent response?
• What conversation and audit retention policy will apply inside ONIX?

Sources

• Bauer RAG versions and V4 direction
• RapidDraft integration strategy
• D:\02_Code\LibreChat_Setup\docs\bauer-rag-v4-architecture-and-delivery-plan.md
• D:\02_Code\15_ERP\docs\RapidDraft_Data_Contract_v1.md