RAG: Teaching Your Agent About Documents

def _register_tools(self):
    @tool
    def deep_search(question: str, max_iterations: int = 3) -> dict:
        """Search with automatic refinement if results are poor.

        Will refine query and search again if confidence is low.
        """
        all_chunks = []
        queries_tried = []

        current_query = question
        for i in range(max_iterations):
            response = self.rag.query(current_query)
            queries_tried.append(current_query)

            if response.chunk_scores and response.chunk_scores[0] > 0.7:
                # Good results found
                all_chunks.extend(response.chunks[:3])
                return {
                    "status": "success",
                    "chunks": all_chunks,
                    "iterations": i + 1,
                    "queries_used": queries_tried
                }

            # Results not great - try to refine
            all_chunks.extend(response.chunks[:1])  # Keep best chunk anyway

            # Generate refined query (in real implementation, use LLM)
            current_query = f"{question} details specifics"

        return {
            "status": "partial",
            "chunks": all_chunks,
            "iterations": max_iterations,
            "note": "Could not find high-confidence results"
        }

@tool
def multi_aspect_search(aspects: list[str]) -> dict:
    """Search for multiple related topics and combine results.

    Args:
        aspects: List of topics to search for separately

    Use when a question has multiple parts that need
    different searches (e.g., "compare X and Y").
    """
    results = {}

    for aspect in aspects:
        response = self.rag.query(aspect)
        results[aspect] = {
            "chunks": response.chunks[:3],
            "confidence": response.chunk_scores[0] if response.chunk_scores else 0,
            "sources": response.source_files
        }

    # Identify which aspects have good coverage
    covered = [a for a, r in results.items() if r["confidence"] > 0.6]
    missing = [a for a, r in results.items() if r["confidence"] < 0.4]

    return {
        "results": results,
        "well_covered": covered,
        "potentially_missing": missing,
        "note": f"Strong info on {len(covered)}/{len(aspects)} aspects"
    }

User: "Compare our pricing strategy with competitor analysis"

Agent thinks: "This needs two aspects - pricing and competitors"
Agent calls: multi_aspect_search(["pricing strategy", "competitor analysis"])

Results: {
  "pricing strategy": {"confidence": 0.89, ...},
  "competitor analysis": {"confidence": 0.34, ...},
  "well_covered": ["pricing strategy"],
  "potentially_missing": ["competitor analysis"]
}

Agent responds: "I found detailed information about our pricing strategy...
However, I couldn't find substantial competitor analysis in the documents.
You may need to provide competitor analysis documents for a full comparison."

@tool
def verified_search(query: str, min_confidence: float = 0.6) -> dict:
    """Search with explicit confidence verification.

    Only returns results above the confidence threshold.
    Clearly indicates when information is not available.
    """
    response = self.rag.query(query)

    if not response.chunk_scores:
        return {
            "found": False,
            "reason": "No matching documents in index"
        }

    top_confidence = response.chunk_scores[0]

    if top_confidence >= min_confidence:
        return {
            "found": True,
            "confidence": top_confidence,
            "answer_basis": response.chunks[:3],
            "sources": response.source_files
        }
    else:
        return {
            "found": False,
            "confidence": top_confidence,
            "reason": f"Best match only {top_confidence:.0%} confident",
            "suggestion": "The documents may not contain this information",
            "closest_match": response.chunks[0] if response.chunks else None
        }

@tool
def triangulated_search(query: str, min_sources: int = 2) -> dict:
    """Search and verify information across multiple sources.

    More reliable for important facts - ensures the information
    isn't just from one potentially outdated document.
    """
    response = self.rag.query(query)

    # Group chunks by source
    sources = {}
    for chunk, score, meta in zip(
        response.chunks,
        response.chunk_scores,
        response.chunk_metadata
    ):
        source = meta.get("source", "unknown")
        if source not in sources:
            sources[source] = []
        sources[source].append({"chunk": chunk, "score": score})

    unique_sources = len(sources)

    if unique_sources >= min_sources:
        return {
            "verified": True,
            "source_count": unique_sources,
            "sources": list(sources.keys()),
            "evidence": {s: chunks[0] for s, chunks in sources.items()},
            "note": f"Information confirmed across {unique_sources} documents"
        }
    else:
        return {
            "verified": False,
            "source_count": unique_sources,
            "sources": list(sources.keys()),
            "warning": f"Only found in {unique_sources} source(s) - verify independently"
        }

config = RAGConfig(
    chunk_size=256,        # Short chunks for precise matching
    chunk_overlap=50,      # Some overlap for context
    max_chunks=3,          # Few chunks, focused answers
    max_indexed_files=200  # Support many FAQ documents
)

rag = RAGSDK(config)
rag.index_documents(["faq.pdf", "troubleshooting.pdf", "quick_start.pdf"])

response = rag.query("How do I reset my password?")

config = RAGConfig(
    chunk_size=1024,       # Large chunks preserve argument flow
    chunk_overlap=200,     # High overlap keeps ideas connected
    max_chunks=4,          # Fewer, richer chunks
    max_file_size_mb=200   # Academic papers can be large
)

rag = RAGSDK(config)
rag.index_documents(["paper1.pdf", "paper2.pdf", "literature_review.pdf"])

response = rag.query("What methodology was used in the study?")

config = RAGConfig(
    chunk_size=512,        # Medium chunks for mixed content
    chunk_overlap=100,     # Preserve code block context
    max_chunks=6,          # More chunks to show examples + explanations
)

rag = RAGSDK(config)
rag.index_documents(["api_reference.pdf", "tutorial.pdf", "examples.pdf"])

response = rag.query("How do I authenticate API requests?")

config = RAGConfig(
    chunk_size=768,        # Clauses can be long
    chunk_overlap=150,     # Don't break clause boundaries
    max_chunks=5,          # Show relevant clauses
    max_file_size_mb=500   # Contracts can be huge
)

rag = RAGSDK(config)
rag.index_document("contract.pdf")

response = rag.query("What are the termination conditions?")

# 1. Check relevance scores before trusting the answer
response = rag.query(question)

if not response.chunk_scores or response.chunk_scores[0] < 0.6:
    # Low relevance - documents probably don't cover this
    print("I don't have information about that topic.")
else:
    print(response.text)

# 2. Use a more specific question
# ❌ "Tell me about the system"
# ✅ "What are the system requirements for installation?"

# 3. Index more relevant documents
rag.index_document("system_requirements.pdf")

# 1. Increase chunk size
config = RAGConfig(
    chunk_size=768,        # Was 256
    chunk_overlap=150,     # Proportionally larger
)

# 2. Retrieve more chunks
config = RAGConfig(
    max_chunks=8,          # Was 3
)

# 3. Both together for comprehensive answers
config = RAGConfig(
    chunk_size=768,
    chunk_overlap=150,
    max_chunks=6,
)

# 1. Use AMD NPU acceleration (if available)
# Lemonade Server (https://lemonade-server.ai) automatically uses NPU for embeddings

# 2. Index documents in batch
# ✅ Efficient - one batch operation
rag.index_documents(["doc1.pdf", "doc2.pdf", "doc3.pdf", ...])

# ❌ Slow - separate operations
for doc in documents:
    rag.index_document(doc)

# 3. Use smaller embedding model
config = RAGConfig(
    embedding_model="all-MiniLM-L6-v2"  # Smaller, faster
)

# 4. Persist index to avoid re-indexing
config = RAGConfig(
    cache_dir="./my_rag_cache"  # Index persisted here
)
# Next run will load existing index instead of re-creating

# 1. Limit indexed files
config = RAGConfig(
    max_indexed_files=50,     # Limit total files
    max_file_size_mb=50,      # Limit individual file size
)

# 2. Use larger chunks (fewer total chunks)
config = RAGConfig(
    chunk_size=1024,          # Fewer chunks per document
)

# 3. Clear index when switching projects
rag.clear_index()

# 4. Remove documents you no longer need
rag.remove_document("old_document.pdf")