hyperforge-nucliadb 1.0.0.post22__tar.gz

hyperforge_nucliadb-1.0.0.post22/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: hyperforge_nucliadb
+Version: 1.0.0.post22
+Summary: NucliaDB Hyperforge agent
+Author-email: Nuclia <nucliadb@nuclia.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://progress.com
+Project-URL: Repository, https://github.com/nuclia/forge
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: hyperforge
+Requires-Dist: lingua-language-detector
+Requires-Dist: nucliadb_sdk
+
+# NucliaDB Hyperforge agents
+
+Basic ASK - Basic initial agent
+Advanced ASK (deprecated)
+ASK (experimental)
+Sync (Sync Service oauth linked)

hyperforge_nucliadb-1.0.0.post22/README.md

@@ -0,0 +1,6 @@
+# NucliaDB Hyperforge agents
+
+Basic ASK - Basic initial agent
+Advanced ASK (deprecated)
+ASK (experimental)
+Sync (Sync Service oauth linked)

hyperforge_nucliadb-1.0.0.post22/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyperforge_nucliadb"
+version = "1.0.0.post22"
+license = "Apache-2.0"
+description = "NucliaDB Hyperforge agent"
+authors = [{ name = "Nuclia", email = "nucliadb@nuclia.com" }]
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10, <4"
+dependencies = ["hyperforge", "lingua-language-detector", "nucliadb_sdk"]
+
+[dependency-groups]
+# these dependencies are actually in the src/ folder (under
+# src/nucliadb_utils/tests/), but only used when the module is imported
+dev = [
+    "pytest",
+    "pytest-benchmark",
+    "pytest-docker-fixtures>=1.4.2",
+    "pytest-lazy-fixtures",
+    "hyperforge_rephrase",
+]
+
+[project.urls]
+Homepage = "https://progress.com"
+Repository = "https://github.com/nuclia/forge"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

hyperforge_nucliadb-1.0.0.post22/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hyperforge_nucliadb-1.0.0.post22/src/hyperforge_nucliadb/__init__.py

@@ -0,0 +1,13 @@
+from .advanced_ask_agent import AdvancedAskAgent
+from .ask.ask import AskAgent
+from .basic_ask_agent import BasicAskAgent
+from .driver import NucliaDBDriver
+from .sync.agent import SyncAskAgent
+
+__all__ = [
+    "NucliaDBDriver",
+    "AskAgent",
+    "AdvancedAskAgent",
+    "BasicAskAgent",
+    "SyncAskAgent",
+]

hyperforge_nucliadb-1.0.0.post22/src/hyperforge_nucliadb/advanced_ask_agent.py

@@ -0,0 +1,267 @@
+import asyncio
+from time import time
+from typing import Any, Dict, List, Optional, cast
+
+from hyperforge.agent import Agent
+from hyperforge.configure import agent
+from hyperforge.context.agent import ContextAgent
+from hyperforge.manager import Manager
+from hyperforge.memory import Chunk, Context, QuestionMemory, Source
+from nucliadb_models import filters as ndb_filters
+from nucliadb_models.search import AskRequest
+
+from hyperforge import logger
+from hyperforge_nucliadb.advanced_ask_config import (
+    AdvancedAskAgentConfig,
+)
+from hyperforge_nucliadb.ask.multi import choose_source
+from hyperforge_nucliadb.ask_utils import (
+    combine_filter_expressions,
+    get_chunk_text,
+    to_field_filter_expression,
+)
+from hyperforge_nucliadb.driver import (
+    NucliaDBConnection,
+    NucliaDBDriver,
+)
+
+
+@agent(
+    id="advanced_ask",
+    agent_type="context",
+    title="Knowledge Box Advanced Ask",
+    description="Ask a question to the knowledge box and retrieve relevant information",
+    config_schema=AdvancedAskAgentConfig,
+)
+class AdvancedAskAgent(ContextAgent, Agent[AdvancedAskAgentConfig]):
+    agent_description: str = "Agent that queries a NucliaDB Knowledge Box to get context to answer questions. It is a retrieval agent, so questions should be in a format that makes sense for retrieval."
+
+    async def _get_question_context(
+        self,
+        memory: QuestionMemory,
+        manager: Manager,
+        question_uuid: str,
+        question: str,
+        flow_id: str,
+        extra_context: Optional[Dict[str, Any]] = None,
+    ) -> List[tuple[str, str]]:
+        sources = self.config.sources
+        # Choose sources based on the question/s and the in
+        chosen_sources = await choose_source(
+            memory,
+            manager,
+            sources,
+            question,
+            ident=self.config.id if self.config.id else "default",
+            step_title=self.step_title("Choose sources"),
+        )
+
+        missing: list[tuple[str, str] | None] = await asyncio.gather(
+            *[
+                self.rag(
+                    memory, manager, source, question_uuid, question, flow_id=flow_id
+                )
+                for source in chosen_sources
+            ]
+        )
+        # We only want to fallback if all sources failed
+        if any(m is None for m in missing):
+            return []
+        else:
+            # XXX: We might be duplicating some results here if multiple sources return the same missing question
+            return [r for r in missing if r is not None]
+
+    async def rag(
+        self,
+        memory: QuestionMemory,
+        manager: Manager,
+        source_obj: Source,
+        question_uuid: str,
+        question: str,
+        flow_id: str,
+    ) -> tuple[str, str] | None:
+        source = source_obj.id
+
+        nucliadb_driver = get_ndb_driver(manager, source)
+
+        context = Context(
+            agent_id=self.config.id,
+            original_question_uuid=memory.original_question_uuid,
+            actual_question_uuid=question_uuid,
+            question=question,
+            source=source,
+            agent="advanced_ask",
+            title=self.config.title
+            if self.config.title
+            else f"Retrieval on {source} Knowledge Box",
+        )
+        t0 = time()
+        ask_request = build_ask_request(self.config, nucliadb_driver.config, question)
+        paragraphs = await nucliadb_driver.ask(ask_request)
+        answer = None
+        if paragraphs is not None:
+            input_tokens = (
+                paragraphs.metadata.tokens.input_nuclia
+                if paragraphs.metadata and paragraphs.metadata.tokens
+                else 0
+            )
+            output_tokens = (
+                paragraphs.metadata.tokens.output_nuclia
+                if paragraphs.metadata and paragraphs.metadata.tokens
+                else 0
+            )
+            context.chunks = []
+            answer = (
+                paragraphs.answer
+                if paragraphs.answer
+                and "not enough data to answer this" not in paragraphs.answer
+                else ""
+            )
+            if paragraphs.citations != {}:
+                result_chunks = list(paragraphs.citations.keys())
+            else:
+                result_chunks = paragraphs.retrieval_results.best_matches
+            for chunk_id in result_chunks:
+                resource_id = chunk_id.split("/")[0]
+                resource = paragraphs.retrieval_results.resources[resource_id]
+                text = get_chunk_text(paragraphs, chunk_id)
+                context.chunks.append(
+                    Chunk(
+                        chunk_id=chunk_id,
+                        title=resource.title,
+                        text=text,
+                        source=source,
+                        origin_agent=self.config.module,
+                    )
+                )
+                # TODO: Save citations properly
+
+        # XXX: This answer will be overriden by any call to save_ctx_and_return_missing below
+        if answer:
+            context.summary = answer
+        if self.fallback is None:
+            if answer is not None and answer != "":
+                missing = await self.save_ctx_and_return_missing(
+                    context=context,
+                    question=question,
+                    memory=memory,
+                    manager=manager,
+                    flow_id=flow_id,
+                )
+            else:
+                missing = (question_uuid, question)
+                logger.info(
+                    f"No context found for question {question} in source {source}, skipping"
+                )
+            ident = self.config.id if self.config.id else "default"
+            await memory.add_step(
+                step_module=self.config.module,
+                step_title=self.step_title("RAG retrieval"),
+                step_reason="Got answer" if answer else "No answer",
+                step_value=answer if answer else "No answer",
+                timeit=time() - t0,
+                input_nuclia_tokens=input_tokens if input_tokens else 0,
+                output_nuclia_tokens=output_tokens if output_tokens else 0,
+                step_agent_path=f"/context/{ident}",
+            )
+            return missing
+        missing = await self.save_ctx_and_return_missing(
+            context=context,
+            question=question,
+            memory=memory,
+            manager=manager,
+            flow_id=flow_id,
+        )
+        return missing
+
+
+def get_ndb_driver(manager: Manager, source: str) -> NucliaDBDriver:
+    driver = manager.drivers.get(source)
+    if driver is None:
+        raise Exception("No NDB available")
+    return cast(NucliaDBDriver, driver)
+
+
+def build_ask_request(
+    agent: AdvancedAskAgentConfig,
+    driver: NucliaDBConnection,
+    question: str,
+) -> AskRequest:
+    filter_expression = parse_filter_expression(agent, driver)
+    ask_request = AskRequest(
+        query=question,
+        generative_model=agent.generative_model,
+        citations=True,
+        filters=driver.filters,
+    )
+    if filter_expression is not None:
+        # filters and filter_expression are mutually exclusive
+        ask_request.filter_expression = filter_expression
+        ask_request.filters = []
+
+    # Fields to copy from agent to ask_request
+    COPYABLE_FIELDS = [
+        "answer_json_schema",
+        "citation_threshold",
+        "citations",
+        "extra_context_images",
+        "extra_context",
+        "features",
+        "generate_answer",
+        "max_tokens",
+        "min_score",
+        "prompt",
+        "query_image",
+        "rag_images_strategies",
+        "rag_strategies",
+        "rank_fusion",
+        "rephrase",
+        "reranker",
+        "resource_filters",
+        "security",
+        "show_hidden",
+        "top_k",
+        "vectorset",
+        "search_configuration",
+    ]
+    for field in COPYABLE_FIELDS:
+        value = getattr(agent, field, None)
+        if value is not None:
+            setattr(ask_request, field, value)
+    return ask_request
+
+
+def parse_filter_expression(
+    agent: AdvancedAskAgentConfig,
+    driver: NucliaDBConnection,
+) -> Optional[ndb_filters.FilterExpression]:
+    """
+    Make sure to merge agent and driver filter expressions properly if both are present.
+    """
+    driver_filter_expression: Optional[ndb_filters.FilterExpression] = None
+    if len(driver.filters) > 0:
+        operands: list[ndb_filters.FieldFilterExpression] = []
+        for filter in driver.filters:
+            field_filter = to_field_filter_expression(filter)
+            if field_filter is not None:
+                operands.append(field_filter)
+        if len(operands) == 0:
+            driver_filter_expression = None
+        elif len(operands) == 1:
+            driver_filter_expression = operands[0]  # type: ignore
+        else:
+            driver_filter_expression = ndb_filters.FilterExpression(
+                field=ndb_filters.And(operands=operands)
+            )
+    elif driver.filter_expression is not None:
+        driver_filter_expression = driver.filter_expression
+
+    if agent.filter_expression is None:
+        return driver_filter_expression
+    else:
+        if driver_filter_expression is None:
+            return agent.filter_expression
+        else:
+            return combine_filter_expressions(
+                [agent.filter_expression, driver_filter_expression], operator="and"
+            )

hyperforge_nucliadb-1.0.0.post22/src/hyperforge_nucliadb/advanced_ask_config.py

@@ -0,0 +1,241 @@
+from typing import Any, List, Literal, Optional, Union
+
+from hyperforge.context.config import ContextAgentConfig
+from hyperforge.utils import WidgetType
+from nucliadb_models.filters import FilterExpression
+from nucliadb_models.search import (
+    ChatOptions,
+    CitationsType,
+    CustomPrompt,
+    Image,
+    MaxTokens,
+    MinScore,
+    RagImagesStrategies,
+    RagStrategies,
+    RankFusion,
+    RankFusionName,
+    RerankerName,
+)
+from nucliadb_models.security import RequestSecurity
+from pydantic import Field
+from pydantic.config import ConfigDict
+
+
+class AdvancedAskAgentConfig(ContextAgentConfig):
+    model_config = ConfigDict(title="Knowledge Box advanced Ask")
+    module: Literal["advanced_ask"] = "advanced_ask"
+    sources: List[str] = Field(
+        default_factory=list,
+        json_schema_extra={
+            "show_in_node": True,
+        },
+    )
+    generative_model: str = Field(
+        default="chatgpt-azure-4o-mini",
+        title="Generative model",
+        description="Model used to generate answers",
+        json_schema_extra={"widget": WidgetType.MODEL_SELECT},
+    )
+    features: Optional[list[ChatOptions]] = Field(
+        default=None,
+        title="Chat features",
+        description="Features enabled for the chat endpoint. Semantic search is done if `semantic` is included. If `keyword` is included, the results will include matching paragraphs from the bm25 index. If `relations` is included, a graph of entities related to the answer is returned. `paragraphs` and `vectors` are deprecated, please use `keyword` and `semantic` instead",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    top_k: Optional[int] = Field(
+        default=None,
+        title="Top k",
+        ge=1,
+        le=200,
+        description="The top most relevant results to fetch at the retrieval step. The maximum number of results allowed is 200.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    filter_expression: Optional[FilterExpression] = Field(
+        default=None,
+        title="Filter documents by an expression",
+        description=(
+            "Returns only documents that match this filter expression."
+            "Filtering examples can be found here: https://docs.nuclia.dev/docs/rag/advanced/search-filters"
+        ),
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    rephrase: Optional[bool] = Field(
+        default=None,
+        description=(
+            "Rephrase the query for a more efficient retrieval. This will consume LLM tokens and make the request slower."
+        ),
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    reranker: Optional[RerankerName] = Field(
+        default=None,
+        title="Reranker",
+        description="Reranker to use for the search.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    security: Optional[RequestSecurity] = Field(
+        default=None,
+        title="Security",
+        description="Security metadata for the request. If not provided, the search request is done without the security lookup phase.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    prompt: Optional[CustomPrompt] = Field(
+        default=None,
+        title="Prompts",
+        description="Use to customize the prompts given to the generative model. Both system and user prompts can be customized.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    max_tokens: Optional[MaxTokens] = Field(
+        default=None,
+        title="Maximum LLM tokens to use for the request",
+        description="Use to limit the amount of tokens used in the LLM context and/or for generating the answer. If not provided, the default maximum tokens of the generative model will be used. If an integer is provided, it is interpreted as the maximum tokens for the answer.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    show_hidden: Optional[bool] = Field(
+        default=None,
+        title="Show hidden resources",
+        description="If set to false (default), excludes hidden resources from search",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    rag_strategies: Optional[List[RagStrategies]] = Field(
+        default=None,
+        title="RAG context building strategies",
+        description=(
+            """Options for tweaking how the context for the LLM model is crafted:
+- `full_resource` will add the full text of the matching resources to the context. This strategy cannot be combined with `hierarchy`, `neighbouring_paragraphs`, or `field_extension`.
+- `field_extension` will add the text of the matching resource's specified fields to the context.
+- `hierarchy` will add the title and summary text of the parent resource to the context for each matching paragraph.
+- `neighbouring_paragraphs` will add the sorrounding paragraphs to the context for each matching paragraph.
+- `metadata_extension` will add the metadata of the matching paragraphs or its resources to the context.
+- `prequeries` allows to run multiple retrieval queries before the main query and add the results to the context. The results of specific queries can be boosted by the specifying weights.
+
+If empty, the default strategy is used, which simply adds the text of the matching paragraphs to the context.
+"""
+        ),
+        examples=[
+            [{"name": "full_resource", "count": 2}],
+            [
+                {"name": "field_extension", "fields": ["t/amend", "a/title"]},
+            ],
+            [{"name": "hierarchy", "count": 2}],
+            [{"name": "neighbouring_paragraphs", "before": 2, "after": 2}],
+            [
+                {
+                    "name": "metadata_extension",
+                    "types": ["origin", "classification_labels"],
+                }
+            ],
+            [
+                {
+                    "name": "prequeries",
+                    "queries": [
+                        {
+                            "request": {
+                                "query": "What is the capital of France?",
+                                "features": ["keyword"],
+                            },
+                            "weight": 0.5,
+                        },
+                        {
+                            "request": {
+                                "query": "What is the capital of Germany?",
+                            },
+                            "weight": 0.5,
+                        },
+                    ],
+                }
+            ],
+        ],
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    citations: Optional[Union[bool, CitationsType]] = Field(
+        default=None,
+        description="Whether to include citations in the response. "
+        "If set to None or False, no citations will be computed. "
+        "If set to True or 'default', citations will be computed after answer generation and send as a separate `CitationsGenerativeResponse` chunk. "
+        "If set to 'llm_footnotes', citations will be included in the LLM's response as markdown-styled footnotes. A `FootnoteCitationsGenerativeResponse` chunk will also be sent to map footnote ids to context keys in the `query_context`.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    citation_threshold: Optional[float] = Field(
+        default=None,
+        description="If citations is set to True or 'default', this will be the similarity threshold. Value between 0 and 1, lower values will produce more citations. If not set, it will be set to the optimized threshold found by Nuclia.",
+        ge=0.0,
+        le=1.0,
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    answer_json_schema: Optional[dict[str, Any]] = Field(
+        default=None,
+        title="Answer JSON schema",
+        description="""Desired JSON schema for the LLM answer.
+This schema is passed to the LLM so that it answers in a scructured format following the schema. If not provided, textual response is returned.
+Note that when using this parameter, the answer in the generative response will not be returned in chunks, the whole response text will be returned instead.
+Using this feature also disables the `citations` parameter. For maximal accuracy, please include a `description` for each field of the schema.
+""",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    generate_answer: Optional[bool] = Field(
+        default=None,
+        description="Whether to generate an answer using the generative model. If set to false, the response will only contain the retrieval results.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    min_score: Optional[Union[float, MinScore]] = Field(
+        default=None,
+        title="Minimum score",
+        description="Minimum score to filter search results. Results with a lower score will be ignored. Accepts either a float or a dictionary with the minimum scores for the bm25 and vector indexes. If a float is provided, it is interpreted as the minimum score for vector index search.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    extra_context: Optional[list[str]] = Field(
+        default=None,
+        title="Extra query context",
+        description="""Additional context that is added to the retrieval context sent to the LLM.
+        It allows extending the chat feature with content that may not be in the Knowledge Box.""",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    extra_context_images: Optional[list[Image]] = Field(
+        default=None,
+        title="Extra query context images",
+        description="""Additional images added to the retrieval context sent to the LLM."
+        It allows extending the chat feature with content that may not be in the Knowledge Box.""",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    query_image: Optional[Image] = Field(
+        default=None,
+        title="Query image",
+        description="Image that will be used together with the query text for retrieval and then sent to the LLM as part of the context. "
+        "If a query image is provided, the `extra_context_images` and `rag_images_strategies` will be disabled.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    rank_fusion: Optional[Union[RankFusionName, RankFusion]] = Field(
+        default=None,
+        title="Rank fusion",
+        description="Rank fusion algorithm to use to merge results from multiple retrievers (keyword, semantic)",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    rag_images_strategies: Optional[list[RagImagesStrategies]] = Field(
+        default=None,
+        title="RAG image context building strategies",
+        description=(
+            "Options for tweaking how the image based context for the LLM model is crafted:\n"
+            "- `page_image` will add the full page image of the matching resources to the context.\n"
+            "- `tables` will send the table images for the paragraphs that contain tables and matched the retrieval query.\n"
+            "- `paragraph_image` will add the images of the paragraphs that contain images (images for tables are not included).\n"
+            "No image strategy is used by default. Note that this is only available for LLM models that support visual inputs. If the model does not support visual inputs, the image strategies will be ignored."
+        ),
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    resource_filters: Optional[list[str]] = Field(
+        default=None,
+        title="Resources filter",
+        description="List of resource ids to filter search results for. Only paragraphs from the specified resources will be returned.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    vectorset: Optional[str] = Field(
+        default=None,
+        title="Vectorset",
+        description="Vectors index to perform the search in. If not provided, NucliaDB will use the default one",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )
+    search_configuration: Optional[str] = Field(
+        default=None,
+        description="Load ask parameters from this configuration. Parameters in the request override parameters from the configuration.",
+        json_schema_extra={"widget": WidgetType.NOT_SHOWN},
+    )

hyperforge_nucliadb-1.0.0.post22/src/hyperforge_nucliadb/ask/__init__.py

@@ -0,0 +1,3 @@
+from .ask import AskAgent
+
+__all__ = ["AskAgent"]