Class TurSemanticNavToolService

java.lang.Object
com.viglet.turing.genai.tool.TurSemanticNavToolService
@Service public class TurSemanticNavToolService extends Object

  • Constructor Details

  • Method Details

    • listSites

      @Tool(name="list_sites", description="Lists available Semantic Navigation sites.\nONLY use this if you do not know the siteName or need to verify available locales.\nArgs:\n filterName (str): Optional. Filter sites by name. Use empty string for all.") public String listSites(String filterName)

    • getSiteFields

      @Tool(name="get_site_fields", description="Retrieves valid facet fields for filtering a specific site.\nONLY call this if the user asks for specific filters (e.g., 'by author', 'only news')\nand you need to know the exact field name to use in search_site.\nArgs:\n siteName (str): Name of the site.") public String getSiteFields(String siteName)

    • getValidFilterValues

      @Tool(name="get_valid_filter_values", description="Returns the exact, valid string values that can be used for a specific filter (facet) in search_site.\nUse this tool BEFORE applying a filter in search_site if you are not 100% sure of the exact value name\nin the database. This prevents hallucinating filter values.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n fieldName (str): Required. The facet field name (e.g., 'temas', 'author', 'type').") public String getValidFilterValues(String siteName, String locale, String fieldName)

    • searchSite

      @Tool(name="search_site", description="Searches for content on a site. Returns compact results (ID, title, URL, snippet).\nUse get_document_details to read the full content of a specific result.\n\nMANDATORY WORKFLOW \u2014 follow these steps IN ORDER:\n1. FIRST call 'discover_facet_values' (phrase) or 'lookup_facet_value' (single word)\n to check which words match existing facet values.\n2. THEN call 'search_site' using the results:\n - Words that MATCHED a facet \u2192 put ONLY in 'filterQueries' (with exact value from facet)\n - Words that DID NOT match any facet \u2192 put in 'query'\n - If ALL words matched facets \u2192 use query='*'\n3. NEVER put the same word in BOTH 'query' and 'filterQueries'. This causes redundant\n filtering and returns poor results.\n4. NEVER invent filter values. ONLY use exact values returned by the facet lookup tools.\n\nExample: User says \"gradua\u00e7\u00e3o tecnologia\"\n \u2192 discover_facet_values finds: gradua\u00e7\u00e3o\u2192programas:Gradua\u00e7\u00e3o, tecnologia\u2192area-de-conhecimento:Tecnologia\n \u2192 search_site(query='*', filterQueries='programas:Gradua\u00e7\u00e3o|area-de-conhecimento:Tecnologia')\n\nArgs:\n siteName (str): Required. Use 'educaction-stage-publish' as default if unknown.\n locale (str): Required. Use 'pt_BR' or 'en'.\n query (str): Required. Use '*' when all user terms are covered by filterQueries.\n rows (int): Optional. Number of results. Defaults to 10.\n page (int): Optional. Defaults to 1.\n filterQueries (str): Optional. Format: field_name:VALUE. Separate with pipe (|).\n") public String searchSite(String siteName, String locale, String query, Integer rows, Integer page, String filterQueries)

    • getDocumentDetails

      @Tool(name="get_document_details", description="Retrieves the full text and complete metadata of a single document using its ID.\nCall this tool when the user asks for specific details about a document found in a\nprevious search, or if you need to read the full content to answer a complex question.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n documentId (str): Required. The document ID from a previous search result.") public String getDocumentDetails(String siteName, String locale, String documentId)

    • getSearchSuggestions

      @Tool(name="get_search_suggestions", description="Provides autocomplete suggestions and spelling corrections for a search query.\nUse this tool ONLY if search_site returns 0 results, to check if the user misspelled a word.\nAlso useful to help the user refine their search terms.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n term (str): Required. The search term to get suggestions for.") public String getSearchSuggestions(String siteName, String locale, String term)

    • findSimilarDocuments

      @Tool(name="find_similar_documents", description="Finds documents that are semantically similar to a specific document (More Like This).\nUse this when the user asks for recommendations, related articles, or 'more like this'.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n documentId (str): Required. The document ID to find similar documents for.") public String findSimilarDocuments(String siteName, String locale, String documentId)

    • getAggregatedStats

      @Tool(name="get_aggregated_stats", description="Calculates totals and distributions for a specific category using facet aggregation.\nCall this when the user asks 'how many', 'what is the distribution', 'count by category',\nor wants statistical data about content WITHOUT needing to read the actual documents.\nMuch more efficient than reading all results and counting manually.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n query (str): Required. The search query to scope the aggregation (e.g., 'Pos-Graduacao', '*' for all).\n facetField (str): Required. The field to aggregate by (e.g., 'area_conhecimento', 'type', 'author').\n filterQueries (str): Optional. Additional filters. Format: field_name:VALUE. Separate with pipe (|).") public String getAggregatedStats(String siteName, String locale, String query, String facetField, String filterQueries)

    • getDocumentHighlights

      @Tool(name="get_document_highlights", description="Extracts specific sentences or paragraphs from a document where the search terms appear.\nUse this for precise questions about long documents (rules, regulations, chapters) to save context.\nInstead of reading the full document, this returns only the relevant highlighted passages.\nRequires highlighting to be enabled on the site.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n documentId (str): Required. The document ID to search within.\n termsToHighlight (str): Required. The search terms to find within the document.") public String getDocumentHighlights(String siteName, String locale, String documentId, String termsToHighlight)

    • compareItems

      @Tool(name="compare_items", description="Compares specific fields of two or more documents side-by-side in a structured table format.\nCall this when the user asks for differences, similarities, or a comparison between courses,\narticles, events, or any other content items.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n documentIds (str): Required. Comma-separated document IDs (2 to 5 IDs).\n fieldsToCompare (str): Required. Comma-separated field names to compare\n (e.g., 'title,description,author,date,url').") public String compareItems(String siteName, String locale, String documentIds, String fieldsToCompare)

    • searchRecentUpdates

      @Tool(name="search_recent_updates", description="Retrieves the newest or most recently updated content about a topic.\nUse this IMMEDIATELY when the user asks for 'latest', 'newest', 'recent news',\n'updates', or 'what happened recently'. This tool handles date sorting automatically,\nso the LLM does NOT need to build date filter queries.\nArgs:\n siteName (str): Required. Name of the site.\n locale (str): Required. Use 'pt_BR' or 'en'.\n query (str): Required. The topic to search for. Use '*' for all recent content.\n rows (int): Optional. Number of recent results. Defaults to 5.\n filterQueries (str): Optional. Additional filters. Format: field_name:VALUE. Separate with pipe (|).") public String searchRecentUpdates(String siteName, String locale, String query, Integer rows, String filterQueries)

    • getFacetSummary

      @Tool(name="get_facet_summary", description="Provides a statistical summary of ALL categories and attributes available for a given search query.\nCall this tool when the user asks 'What types of X do you have?', 'How is the content organized?',\n'What categories exist?', or wants a panoramic overview of available content without reading documents.\nUnlike get_valid_filter_values (which returns values for ONE field), this returns ALL facet fields at once.\nArgs:\n siteName (str): Required. Site name.\n locale (str): Required. Search locale (e.g., 'pt_BR' or 'en').\n query (str): Optional. The search term to scope the summary. Use '*' for the entire site.") public String getFacetSummary(String siteName, String locale, String query)

    • searchByDateRange

      @Tool(name="search_by_date_range", description="Searches for documents within a specific date range.\nUse this INSTEAD of search_site when the user asks for content from a specific period\n(e.g., 'news from last year', 'events in October 2023', 'publications between March and June').\nThis tool handles date syntax automatically - the LLM only needs to provide simple YYYY-MM-DD dates.\nArgs:\n siteName (str): Required. Site name.\n locale (str): Required. Search locale (e.g., 'pt_BR' or 'en').\n query (str): Required. The search term (or '*' for all content in the date range).\n dateFieldName (str): Required. The name of the date field to filter on\n (must be discovered via get_site_fields, e.g., 'date', 'publication_date', 'modification_date').\n startDate (str): Required. Start date in format YYYY-MM-DD.\n endDate (str): Required. End date in format YYYY-MM-DD. Use the same date as startDate for a single day.\n rows (int): Optional. Number of results. Defaults to 10.") public String searchByDateRange(String siteName, String locale, String query, String dateFieldName, String startDate, String endDate, Integer rows)

    • lookupFacetValue

      @Tool(name="lookup_facet_value", description="Looks up a SINGLE term across all available facets to find exact filter values in the database.\nUses word-stem matching so inflected forms (plurals, conjugations) also match.\nCRITICAL: Call this BEFORE using 'filterQueries' in 'search_site' when you know a single keyword\nbut not the exact database value (e.g., 'docente', 'inovacao', 'silva').\nIMPORTANT RULE: If the term matches a facet value, use it in 'filterQueries' and DO NOT repeat\nthe same term in the 'query' parameter of 'search_site'. Only use 'query' for words that did\nnot match any facet. This avoids redundant filtering and improves search precision.\nFor multi-word user phrases, prefer 'discover_facet_values' instead.\nArgs:\n siteName (str): Required. The site name.\n locale (str): Required. The locale (e.g., 'pt_BR' or 'en').\n term (str): Required. A single word or short term to look for inside facet values.") public String lookupFacetValue(String siteName, String locale, String term)

    • discoverFacetValues

      @Tool(name="discover_facet_values", description="Splits a user phrase into individual words and searches ALL facets for values matching each word.\nUses word-stem matching for better recall (e.g., 'docentes' matches 'Docente').\nCRITICAL USE CASE: When the user asks to filter by a phrase like 'cursos de engenharia' or\n'professores de matem\u00e1tica', call this tool to discover which facet fields and values exist\nfor EACH word in the phrase. This prevents hallucinating filter values.\nIMPORTANT RULE: Words that match a facet value MUST be used in 'filterQueries' and MUST NOT\nbe repeated in the 'query' parameter of 'search_site'. Only words that did NOT match any facet\nshould remain in the 'query'. This avoids redundant filtering and improves search precision.\nFor a single keyword, you may use 'lookup_facet_value' instead.\nArgs:\n siteName (str): Required. The site name.\n locale (str): Required. The locale (e.g., 'pt_BR' or 'en').\n text (str): Required. A phrase or sentence whose words will be searched individually\n (e.g., 'cursos engenharia computa\u00e7\u00e3o', 'professores matem\u00e1tica').") public String discoverFacetValues(String siteName, String locale, String text)