nvidia-nat-ragaai 1.2.0rc5__py3-none-any.whl

aiq/meta/pypi.md

@@ -0,0 +1,23 @@
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+![NVIDIA NeMo Agent Toolkit](https://media.githubusercontent.com/media/NVIDIA/NeMo-Agent-Toolkit/refs/heads/main/docs/source/_static/aiqtoolkit_banner.png "NeMo Agent toolkit banner image"
+
+# NVIDIA NeMo Agent Toolkit Subpackage
+This is a subpackage for RagaAI Catalyst integration for observability.
+
+For more information about the NVIDIA NeMo Agent toolkit, please visit the [NeMo Agent toolkit GitHub Repo](https://github.com/NVIDIA/NeMo-Agent-Toolkit).

aiq/plugins/ragaai/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

aiq/plugins/ragaai/mixin/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

aiq/plugins/ragaai/mixin/ragaai_catalyst_mixin.py

@@ -0,0 +1,244 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import json
+import logging
+import os
+from dataclasses import asdict
+
+import ragaai_catalyst
+from ragaai_catalyst.tracers.agentic_tracing.utils.trace_utils import format_interactions
+from ragaai_catalyst.tracers.agentic_tracing.utils.zip_list_of_unique_files import zip_list_of_unique_files
+from ragaai_catalyst.tracers.exporters import DynamicTraceExporter
+from ragaai_catalyst.tracers.exporters.ragaai_trace_exporter import RAGATraceExporter
+from ragaai_catalyst.tracers.exporters.ragaai_trace_exporter import TracerJSONEncoder
+from ragaai_catalyst.tracers.utils.trace_json_converter import convert_json_format
+
+from aiq.plugins.opentelemetry.otel_span import OtelSpan
+
+logger = logging.getLogger(__name__)
+
+
+class RAGATraceExporterOptWrite(RAGATraceExporter):
+    """Custom RAGATraceExporter that provides optional local file writing.
+
+    This subclass of RAGATraceExporter allows control over whether the
+    rag_agent_traces.json file is written to the current directory.
+
+    Args:
+        debug_mode: When False (default), creates local rag_agent_traces.json file.
+                   When True, skips local file creation for cleaner operation.
+    """
+
+    def __init__(self, *args, debug_mode: bool = False, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.debug_mode = debug_mode
+
+    def prepare_trace(self, spans, trace_id):
+        try:
+            try:
+                ragaai_trace = convert_json_format(spans,
+                                                   self.custom_model_cost,
+                                                   self.user_context,
+                                                   self.user_gt,
+                                                   self.external_id)
+            except Exception as e:
+                print(f"Error in convert_json_format function: {trace_id}: {e}")
+                return None
+
+            try:
+                interactions = format_interactions(ragaai_trace)
+                if interactions and 'workflow' in interactions:
+                    ragaai_trace["workflow"] = interactions['workflow']
+            except Exception as e:
+                print(f"Error in format_interactions function: {trace_id}: {e}")
+                return None
+
+            try:
+                # Add source code hash
+                files_to_zip = self.files_to_zip or []
+                hash_id, zip_path = zip_list_of_unique_files(files_to_zip, output_dir=self.tmp_dir)
+            except Exception as e:
+                print(f"Error in zip_list_of_unique_files function: {trace_id}: {e}")
+                return None
+
+            try:
+                ragaai_trace["metadata"]["system_info"] = asdict(self.system_monitor.get_system_info())
+                ragaai_trace["metadata"]["resources"] = asdict(self.system_monitor.get_resources())
+            except Exception as e:
+                print(f"Error in get_system_info or get_resources function: {trace_id}: {e}")
+                return None
+
+            try:
+                ragaai_trace["metadata"]["system_info"]["source_code"] = hash_id
+            except Exception as e:
+                print(f"Error in adding source code hash: {trace_id}: {e}")
+                return None
+
+            try:
+                if "data" in ragaai_trace and ragaai_trace["data"] and len(ragaai_trace["data"]) > 0:
+                    if "start_time" in ragaai_trace:
+                        ragaai_trace["data"][0]["start_time"] = ragaai_trace["start_time"]
+                    if "end_time" in ragaai_trace:
+                        ragaai_trace["data"][0]["end_time"] = ragaai_trace["end_time"]
+            except Exception as e:
+                print(f"Error in adding start_time or end_time: {trace_id}: {e}")
+                return None
+
+            try:
+                if hasattr(self, 'project_name'):
+                    ragaai_trace["project_name"] = self.project_name
+            except Exception as e:
+                print(f"Error in adding project name: {trace_id}: {e}")
+                return None
+
+            try:
+                # Add tracer type to the trace
+                if hasattr(self, 'tracer_type'):
+                    ragaai_trace["tracer_type"] = self.tracer_type
+            except Exception as e:
+                print(f"Error in adding tracer type: {trace_id}: {e}")
+                return None
+
+            # Add user passed metadata to the trace
+            try:
+                logger.debug("Started adding user passed metadata")
+
+                metadata = (self.user_details.get("trace_user_detail", {}).get("metadata", {})
+                            if self.user_details else {})
+
+                if isinstance(metadata, dict):
+                    for key, value in metadata.items():
+                        if key not in {"log_source", "recorded_on"}:
+                            ragaai_trace.setdefault("metadata", {})[key] = value
+
+                logger.debug("Completed adding user passed metadata")
+            except Exception as e:
+                print(f"Error in adding metadata: {trace_id}: {e}")
+                return None
+
+            try:
+                # Save the trace_json
+                trace_file_path = os.path.join(self.tmp_dir, f"{trace_id}.json")
+                with open(trace_file_path, "w", encoding="utf-8") as file:
+                    json.dump(ragaai_trace, file, cls=TracerJSONEncoder, indent=2)
+
+                if self.debug_mode:
+                    with open(os.path.join(os.getcwd(), 'rag_agent_traces.json'), 'w', encoding="utf-8") as f:
+                        json.dump(ragaai_trace, f, cls=TracerJSONEncoder, indent=2)
+            except Exception as e:
+                print(f"Error in saving trace json: {trace_id}: {e}")
+                return None
+
+            return {'trace_file_path': trace_file_path, 'code_zip_path': zip_path, 'hash_id': hash_id}
+        except Exception as e:
+            print(f"Error converting trace {trace_id}: {str(e)}")
+            return None
+
+
+class DynamicTraceExporterOptWrite(DynamicTraceExporter):
+    """Custom DynamicTraceExporter that uses RAGATraceExporterOptWrite internally.
+
+    This subclass of DynamicTraceExporter creates a RAGATraceExporterOptWrite
+    instance instead of the default RAGATraceExporter, providing control over
+    local file creation.
+
+    Args:
+        debug_mode: When False (default), creates local rag_agent_traces.json file.
+                   When True, skips local file creation for cleaner operation.
+    """
+
+    def __init__(self, *args, debug_mode: bool = False, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._exporter = RAGATraceExporterOptWrite(*args, debug_mode=debug_mode, **kwargs)
+
+
+class RagaAICatalystMixin:
+    """Mixin for RagaAI Catalyst exporters.
+
+    This mixin provides RagaAI Catalyst-specific functionality for OpenTelemetry span exporters.
+    It handles RagaAI Catalyst project and dataset configuration and uses custom subclassed
+    exporters to control local file creation behavior.
+
+    Key Features:
+    - RagaAI Catalyst authentication with access key and secret key
+    - Project and dataset scoping for trace organization
+    - Integration with custom DynamicTraceExporter for telemetry transmission
+    - Automatic initialization of RagaAI Catalyst client
+    - Configurable local file creation via debug_mode parameter
+
+    This mixin uses subclassed exporters (RAGATraceExporterOptWrite and DynamicTraceExporterOptWrite)
+    to provide clean control over whether the rag_agent_traces.json file is created locally.
+
+    This mixin is designed to be used with OtelSpanExporter as a base class:
+
+    Example:
+        class MyCatalystExporter(OtelSpanExporter, RagaAICatalystMixin):
+            def __init__(self, base_url, access_key, secret_key, project, dataset, **kwargs):
+                super().__init__(base_url=base_url, access_key=access_key,
+                                 secret_key=secret_key, project=project, dataset=dataset, **kwargs)
+    """
+
+    def __init__(self,
+                 *args,
+                 base_url: str,
+                 access_key: str,
+                 secret_key: str,
+                 project: str,
+                 dataset: str,
+                 tracer_type: str,
+                 debug_mode: bool = False,
+                 **kwargs):
+        """Initialize the RagaAI Catalyst exporter.
+
+        Args:
+            base_url: RagaAI Catalyst base URL.
+            access_key: RagaAI Catalyst access key.
+            secret_key: RagaAI Catalyst secret key.
+            project: RagaAI Catalyst project name.
+            dataset: RagaAI Catalyst dataset name.
+            tracer_type: RagaAI Catalyst tracer type.
+            debug_mode: When False (default), creates local rag_agent_traces.json file.
+                       When True, skips local file creation for cleaner operation.
+            **kwargs: Additional keyword arguments passed to parent classes.
+        """
+        logger.info("RagaAICatalystMixin initialized with debug_mode=%s", debug_mode)
+
+        ragaai_catalyst.RagaAICatalyst(access_key=access_key, secret_key=secret_key, base_url=base_url)
+
+        # Create the DynamicTraceExporter (this will trigger our hook)
+        self._exporter = DynamicTraceExporterOptWrite(project, dataset, base_url, tracer_type, debug_mode=debug_mode)
+
+        super().__init__(*args, **kwargs)
+
+    async def export_otel_spans(self, spans: list[OtelSpan]) -> None:
+        """Export a list of OtelSpans using the custom RagaAI Catalyst exporter.
+
+        This method uses the DynamicTraceExporterOptWrite instance to export spans,
+        with local file creation controlled by the debug_mode setting.
+
+        Args:
+            spans (list[OtelSpan]): The list of spans to export.
+
+        Raises:
+            Exception: If there's an error during span export (logged but not re-raised).
+        """
+        try:
+            # Run the blocking export operation in a thread pool to make it non-blocking
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, lambda: self._exporter.export(spans))  # type: ignore[arg-type]
+        except Exception as e:
+            logger.error("Error exporting spans: %s", e, exc_info=True)

aiq/plugins/ragaai/ragaai_catalyst_exporter.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+from aiq.builder.context import AIQContextState
+from aiq.plugins.opentelemetry.otel_span_exporter import OtelSpanExporter
+from aiq.plugins.ragaai.mixin.ragaai_catalyst_mixin import RagaAICatalystMixin
+
+logger = logging.getLogger(__name__)
+
+
+class RagaAICatalystExporter(RagaAICatalystMixin, OtelSpanExporter):  # pylint: disable=R0901
+    """RagaAI Catalyst exporter for AI workflow observability.
+
+    Exports OpenTelemetry-compatible traces to RagaAI Catalyst for visualization
+    and analysis of AI agent behavior and performance.
+
+    Features:
+    - Automatic span conversion from AIQ events
+    - RagaAI Catalyst-specific authentication
+    - Project and dataset-based trace organization
+    - Integration with custom DynamicTraceExporter for optimal local file control
+
+    Args:
+        context_state: Execution context for isolation
+        base_url: RagaAI Catalyst base URL
+        access_key: RagaAI Catalyst access key
+        secret_key: RagaAI Catalyst secret key
+        project: Project name for trace grouping
+        dataset: Dataset name for trace organization
+        tracer_type: RagaAI Catalyst tracer type.
+        debug_mode: When False (default), creates local rag_agent_traces.json file.
+                   When True, skips local file creation for cleaner operation.
+        batch_size: Batch size for exporting
+        flush_interval: Flush interval for exporting
+        max_queue_size: Maximum queue size for exporting
+        drop_on_overflow: Drop on overflow for exporting
+        shutdown_timeout: Shutdown timeout for exporting
+    """
+
+    def __init__(self,
+                 context_state: AIQContextState | None = None,
+                 batch_size: int = 100,
+                 flush_interval: float = 5.0,
+                 max_queue_size: int = 1000,
+                 drop_on_overflow: bool = False,
+                 shutdown_timeout: float = 10.0,
+                 **catalyst_kwargs):
+        super().__init__(context_state=context_state,
+                         batch_size=batch_size,
+                         flush_interval=flush_interval,
+                         max_queue_size=max_queue_size,
+                         drop_on_overflow=drop_on_overflow,
+                         shutdown_timeout=shutdown_timeout,
+                         **catalyst_kwargs)

aiq/plugins/ragaai/register.py

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+
+from pydantic import Field
+
+from aiq.builder.builder import Builder
+from aiq.cli.register_workflow import register_telemetry_exporter
+from aiq.data_models.telemetry_exporter import TelemetryExporterBaseConfig
+from aiq.observability.mixin.batch_config_mixin import BatchConfigMixin
+from aiq.observability.mixin.collector_config_mixin import CollectorConfigMixin
+
+logger = logging.getLogger(__name__)
+
+
+class CatalystTelemetryExporter(BatchConfigMixin, CollectorConfigMixin, TelemetryExporterBaseConfig, name="catalyst"):
+    """A telemetry exporter to transmit traces to RagaAI catalyst."""
+    endpoint: str = Field(description="The RagaAI Catalyst endpoint", default="https://catalyst.raga.ai/api")
+    access_key: str = Field(description="The RagaAI Catalyst API access key", default="")
+    secret_key: str = Field(description="The RagaAI Catalyst API secret key", default="")
+    dataset: str | None = Field(description="The RagaAI Catalyst dataset name", default=None)
+    tracer_type: str = Field(description="The RagaAI Catalyst tracer type", default="agentic/nemo-framework")
+
+    # Debug mode control options
+    debug_mode: bool = Field(description="When False (default), creates local rag_agent_traces.json file. "
+                             "When True, skips local file creation for cleaner operation.",
+                             default=False)
+
+
+@register_telemetry_exporter(config_type=CatalystTelemetryExporter)
+async def catalyst_telemetry_exporter(config: CatalystTelemetryExporter, builder: Builder):  # pylint: disable=W0613
+    """Create a Catalyst telemetry exporter."""
+
+    try:
+        import os
+
+        from aiq.plugins.ragaai.ragaai_catalyst_exporter import RagaAICatalystExporter
+
+        access_key = config.access_key or os.environ.get("CATALYST_ACCESS_KEY")
+        secret_key = config.secret_key or os.environ.get("CATALYST_SECRET_KEY")
+        endpoint = config.endpoint or os.environ.get("CATALYST_ENDPOINT")
+
+        assert endpoint is not None, "catalyst endpoint is not set"
+        assert access_key is not None, "catalyst access key is not set"
+        assert secret_key is not None, "catalyst secret key is not set"
+
+        yield RagaAICatalystExporter(base_url=endpoint,
+                                     access_key=access_key,
+                                     secret_key=secret_key,
+                                     project=config.project,
+                                     dataset=config.dataset,
+                                     tracer_type=config.tracer_type,
+                                     debug_mode=config.debug_mode,
+                                     batch_size=config.batch_size,
+                                     flush_interval=config.flush_interval,
+                                     max_queue_size=config.max_queue_size,
+                                     drop_on_overflow=config.drop_on_overflow,
+                                     shutdown_timeout=config.shutdown_timeout)
+    except Exception as e:
+        logger.warning("Error creating catalyst telemetry exporter: %s", e, exc_info=True)

nvidia_nat_ragaai-1.2.0rc5.dist-info/METADATA

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: nvidia-nat-ragaai
+Version: 1.2.0rc5
+Summary: Subpackage for RagaAI Catalyst integration in AIQtoolkit
+Keywords: ai,observability,ragaai catalyst
+Classifier: Programming Language :: Python
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: nvidia-nat[opentelemetry]~=1.2
+Requires-Dist: ragaai-catalyst<2.3,>=2.2.0
+
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+![NVIDIA NeMo Agent Toolkit](https://media.githubusercontent.com/media/NVIDIA/NeMo-Agent-Toolkit/refs/heads/main/docs/source/_static/aiqtoolkit_banner.png "NeMo Agent toolkit banner image"
+
+# NVIDIA NeMo Agent Toolkit Subpackage
+This is a subpackage for RagaAI Catalyst integration for observability.
+
+For more information about the NVIDIA NeMo Agent toolkit, please visit the [NeMo Agent toolkit GitHub Repo](https://github.com/NVIDIA/NeMo-Agent-Toolkit).

nvidia_nat_ragaai-1.2.0rc5.dist-info/RECORD

@@ -0,0 +1,11 @@
+aiq/meta/pypi.md,sha256=iXOgvEl_QMB_qjj7fzcisG85J-UC1qUtAXln5dDg6u4,1122
+aiq/plugins/ragaai/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
+aiq/plugins/ragaai/ragaai_catalyst_exporter.py,sha256=1mblHLAv3bO-6Nlsw-ZmMUp7zq7FMFlfVojSgAvvr7Y,3000
+aiq/plugins/ragaai/register.py,sha256=R4EWLsyub_1uq_6cc7RStO6qQbZKcDenOoemclSLTCY,3786
+aiq/plugins/ragaai/mixin/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
+aiq/plugins/ragaai/mixin/ragaai_catalyst_mixin.py,sha256=vjIjKItalJD5LPrkbBUPayZwpsjYCyQGKJ1n2QGtJ8I,10920
+nvidia_nat_ragaai-1.2.0rc5.dist-info/METADATA,sha256=1D0-no_QtILVJ3uuxVLwsKJl4eTtqaH8U4i5Vlu8bgA,1498
+nvidia_nat_ragaai-1.2.0rc5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nvidia_nat_ragaai-1.2.0rc5.dist-info/entry_points.txt,sha256=YwaRUww8SsUuP4SPi5DRcBP3z5fpZ_r_PGddumHNYWs,58
+nvidia_nat_ragaai-1.2.0rc5.dist-info/top_level.txt,sha256=fo7AzYcNhZ_tRWrhGumtxwnxMew4xrT1iwouDy_f0Kc,4
+nvidia_nat_ragaai-1.2.0rc5.dist-info/RECORD,,

nvidia_nat_ragaai-1.2.0rc5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nvidia_nat_ragaai-1.2.0rc5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[aiq.components]
+aiq_ragaai = aiq.plugins.ragaai.register

nvidia_nat_ragaai-1.2.0rc5.dist-info/top_level.txt

@@ -0,0 +1 @@
+aiq