Package dyntabs.ai.annotation

Annotation Interface EasyRAG

@Target(TYPE) @Retention(RUNTIME) public @interface EasyRAG
Enables RAG (Retrieval-Augmented Generation) for an AI assistant.

RAG lets the AI answer questions based on your documents (PDF, DOCX, TXT, etc.) instead of relying only on its general knowledge. The documents are loaded, split into segments, and embedded at build time. When the user asks a question, EasyAI automatically finds the most relevant segments and includes them in the AI prompt.

Two Ways to Provide Documents

EasyAI supports two approaches for loading documents into RAG:

  1. This annotation (@EasyRAG) - for documents with known, fixed paths (classpath resources or static files). Simple, declarative, zero code.
  2. Programmatic via withRAG(DocumentSource...) - for documents loaded at runtime as byte[] from a DMS, database BLOB, REST API, user upload, or any other dynamic source.

Approach 1: @EasyRAG Annotation (Static Paths)

Use Case 1: Company Policy Bot


 @EasyRAG(source = "classpath:company-policy.pdf")
 @EasyAIAssistant(systemMessage = "Answer questions based on the company policy document")
 public interface PolicyBot {
     String ask(String question);
 }

 PolicyBot bot = EasyAI.assistant(PolicyBot.class).build();
 String answer = bot.ask("How many vacation days do I get?");
 // AI reads the PDF and gives an answer based on the actual policy

Use Case 2: Multiple Static Documents


 @EasyRAG(source = {
     "classpath:docs/installation-guide.pdf",
     "classpath:docs/user-manual.pdf",
     "classpath:docs/faq.txt"
 })
 @EasyAIAssistant(systemMessage = "Help users with product questions using the documentation")
 public interface HelpDeskBot {
     String ask(String question);
 }

Use Case 3: Loading From File System


 @EasyRAG(source = "file:C:/data/legal-terms.pdf", maxResults = 5, minScore = 0.7)
 @EasyAIAssistant
 public interface LegalBot {
     String ask(String question);
 }

Approach 2: Programmatic withRAG(DocumentSource...) (Dynamic Content)

When documents are not static files but come from external systems at runtime, skip this annotation and use AssistantBuilder.withRAG(DocumentSource...) instead. This is typical in enterprise/web applications where documents live in a DMS, database, or are uploaded by users.

Use Case 4: Document from a DMS (byte[])


 byte[] pdfBytes = dmsClient.downloadDocument("DOC-12345");

 @EasyAIAssistant(systemMessage = "Answer based on the policy document")
 public interface PolicyBot {
     String ask(String question);
 }

 PolicyBot bot = EasyAI.assistant(PolicyBot.class)
     .withRAG(DocumentSource.of("policy.pdf", pdfBytes))
     .build();

Use Case 5: Document from a Database BLOB


 byte[] content = resultSet.getBytes("document_content");
 String fileName = resultSet.getString("file_name");

 PolicyBot bot = EasyAI.assistant(PolicyBot.class)
     .withRAG(DocumentSource.of(fileName, content))
     .build();

Use Case 6: Plain Text (No File at All)


 String rulesText = configService.loadBusinessRules();

 PolicyBot bot = EasyAI.assistant(PolicyBot.class)
     .withRAG(DocumentSource.ofText("rules", rulesText))
     .build();

Use Case 7: Multiple Documents from Mixed Sources


 PolicyBot bot = EasyAI.assistant(PolicyBot.class)
     .withRAG(
         DocumentSource.of("policy.pdf", dmsClient.download("policy")),
         DocumentSource.of("terms.docx", blobStorage.get("terms")),
         DocumentSource.ofText("extra-rules", additionalRulesText)
     )
     .build();

How Source Paths Work (for @EasyRAG annotation)

  • "classpath:docs/file.pdf" - loads from the classpath (inside your JAR/WAR)
  • "file:C:/data/file.pdf" - loads from the file system (absolute path)
  • "relative/path.txt" - loads from the current working directory

Supported File Formats

PDF, DOCX, DOC, PPTX, TXT, HTML, and more (via Apache Tika, included automatically). This applies to both annotation-based and DocumentSource-based approaches.

Tuning Parameters

  • maxResults() - More results = more context for AI, but higher cost. Default 3 is good for most cases.
  • minScore() - Higher = only very relevant segments are included. Lower = more segments but possibly less relevant. Default 0.5 works well.
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String[]
    source
    Document source paths.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    maxResults
    Maximum number of relevant document segments to include in the AI prompt.
    double
    minScore
    Minimum relevance score for a document segment to be included (0.0 to 1.0).

  • Element Details

    • source

      String[] source
      Document source paths.

      Supports prefixes:

      • classpath: - classpath resource (e.g. "classpath:docs/manual.pdf")
      • file: - absolute file path (e.g. "file:C:/data/terms.pdf")
      • no prefix - relative to working directory
      Returns:
      one or more document paths

    • maxResults

      int maxResults
      Maximum number of relevant document segments to include in the AI prompt.

      When the user asks a question, EasyAI finds the top N most relevant segments from your documents. More segments = more context for the AI, but also higher token cost and potentially slower responses.

      Returns:
      max number of segments (default 3)
      Default:
      3

    • minScore

      double minScore
      Minimum relevance score for a document segment to be included (0.0 to 1.0).

      Segments with a similarity score below this threshold are discarded.

      • 0.0 = include everything (even barely related segments)
      • 0.5 = balanced (default, good for most cases)
      • 0.8 = strict (only very relevant segments)
      Returns:
      minimum score (default 0.5)
      Default:
      0.5