Citations

When you use Knowledge Bases in a chat completions request, Tensoras returns citations alongside the model’s response. Citations identify the source documents and specific text passages that informed the answer, letting your users verify claims and explore the original material.

How Citations Work

You send a chat completions request with the knowledge_bases parameter.
Tensoras retrieves the most relevant chunks from your Knowledge Base using hybrid search.
The retrieved chunks are injected into the model’s context as reference material.
The model generates an answer grounded in those chunks.
The response includes a citations array mapping parts of the answer back to the source chunks.

Citation Format

Each citation in the response contains:

Field	Type	Description
`source`	`string`	The source document identifier (file name, URL, or connector-specific ID)
`text`	`string`	The text of the chunk that was used as context
`score`	`number`	Relevance score between 0 and 1 (higher is more relevant)

Python Example

from tensoras import Tensoras
 
client = Tensoras(api_key="tns_your_key_here")
 
response = client.chat.completions.create(
    model="llama-3.3-70b",
    messages=[
        {"role": "user", "content": "What is the return policy for electronics?"},
    ],
    knowledge_bases=["kb_abc123"],
)
 
# Print the answer
print("Answer:")
print(response.choices[0].message.content)
print()
 
# Print citations
print("Citations:")
for i, citation in enumerate(response.citations, 1):
    print(f"\n[{i}] Source: {citation.source}")
    print(f"    Score:  {citation.score:.4f}")
    print(f"    Text:   {citation.text[:200]}...")

Output

Answer:
Electronics can be returned within 30 days of purchase for a full refund,
provided they are in their original packaging and include all accessories.
Items that have been opened may be subject to a 15% restocking fee.

Citations:

[1] Source: return-policy.pdf
    Score:  0.9234
    Text:   Electronics purchased from our store may be returned within 30 days
            of the original purchase date. Items must be in their original packaging
            with all included accessories...

[2] Source: faq.pdf
    Score:  0.8712
    Text:   Opened electronics are subject to a 15% restocking fee. Defective
            items are exempt from the restocking fee and may be returned at
            any time within the warranty period...

Node.js Example

import Tensoras from "tensoras";
 
const client = new Tensoras({ apiKey: "tns_your_key_here" });
 
const response = await client.chat.completions.create({
  model: "llama-3.3-70b",
  messages: [
    { role: "user", content: "What is the return policy for electronics?" },
  ],
  knowledgeBases: ["kb_abc123"],
});
 
console.log("Answer:");
console.log(response.choices[0].message.content);
console.log();
 
console.log("Citations:");
response.citations.forEach((citation, i) => {
  console.log(`\n[${i + 1}] Source: ${citation.source}`);
  console.log(`    Score:  ${citation.score.toFixed(4)}`);
  console.log(`    Text:   ${citation.text.slice(0, 200)}...`);
});

Using Citations in Your Application

Citations enable several useful patterns in your application:

Display Source References

Show users where the information came from by rendering citations as footnotes, expandable panels, or links to the original documents.

Confidence Filtering

Use the score field to filter out low-relevance citations. If no citation exceeds a confidence threshold, you can flag the response as potentially unreliable or prompt the user to rephrase.

HIGH_CONFIDENCE_THRESHOLD = 0.8
 
high_confidence_citations = [
    c for c in response.citations if c.score >= HIGH_CONFIDENCE_THRESHOLD
]
 
if not high_confidence_citations:
    print("Warning: No high-confidence sources found for this answer.")

Audit Trail

Store citations alongside responses for compliance or auditing. Each citation traces the model’s answer back to a specific passage in a specific document.

Citations with Streaming

Citations are also returned when using stream=True. The citations data is included after the content stream completes, typically in the final event of the stream.

RAG Overview — end-to-end RAG pipeline
Hybrid Search — how relevant chunks are retrieved
Chunking Strategies — how documents are split into citable chunks
Knowledge Bases API — create and manage Knowledge Bases
Chat Completions API — full endpoint reference

Hybrid Search Connectors