pygeai 0.1.6__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/vendor/a2a/utils/telemetry.py

@@ -0,0 +1,299 @@
+"""OpenTelemetry Tracing Utilities for A2A Python SDK.
+
+This module provides decorators to simplify the integration of OpenTelemetry
+tracing into Python applications. It offers `trace_function` for instrumenting
+individual functions (both synchronous and asynchronous) and `trace_class`
+for instrumenting multiple methods within a class.
+
+The tracer is initialized with the module name and version defined by
+`INSTRUMENTING_MODULE_NAME` ('a2a-python-sdk') and
+`INSTRUMENTING_MODULE_VERSION` ('1.0.0').
+
+Features:
+- Automatic span creation for decorated functions/methods.
+- Support for both synchronous and asynchronous functions.
+- Default span naming based on module and function/class/method name.
+- Customizable span names, kinds, and static attributes.
+- Dynamic attribute setting via an `attribute_extractor` callback.
+- Automatic recording of exceptions and setting of span status.
+- Selective method tracing in classes using include/exclude lists.
+
+Usage:
+    For a single function:
+    ```python
+    from your_module import trace_function
+
+
+    @trace_function
+    def my_function():
+        # ...
+        pass
+
+
+    @trace_function(span_name='custom.op', kind=SpanKind.CLIENT)
+    async def my_async_function():
+        # ...
+        pass
+    ```
+
+    For a class:
+    ```python
+    from your_module import trace_class
+
+
+    @trace_class(exclude_list=['internal_method'])
+    class MyService:
+        def public_api(self, user_id):
+            # This method will be traced
+            pass
+
+        def internal_method(self):
+            # This method will not be traced
+            pass
+    ```
+"""
+
+import functools
+import inspect
+import logging
+
+from collections.abc import Callable
+from typing import Any, TypeAlias
+
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind as _SpanKind
+from opentelemetry.trace import StatusCode
+
+
+SpanKind: TypeAlias = _SpanKind
+__all__ = ['SpanKind']
+INSTRUMENTING_MODULE_NAME = 'a2a-python-sdk'
+INSTRUMENTING_MODULE_VERSION = '1.0.0'
+
+logger = logging.getLogger(__name__)
+
+
+def trace_function(  # noqa: PLR0915
+    func: Callable | None = None,
+    *,
+    span_name: str | None = None,
+    kind: SpanKind = SpanKind.INTERNAL,
+    attributes: dict[str, Any] | None = None,
+    attribute_extractor: Callable | None = None,
+) -> Callable:
+    """A decorator to automatically trace a function call with OpenTelemetry.
+
+    This decorator can be used to wrap both sync and async functions.
+    When applied, it creates a new span for each call to the decorated function.
+    The span will record the execution time, status (OK or ERROR), and any
+    exceptions that occur.
+
+    It can be used in two ways:
+
+    1. As a direct decorator: `@trace_function`
+    2. As a decorator factory to provide arguments: `@trace_function(span_name="custom.name")`
+
+    Args:
+        func (callable, optional): The function to be decorated. If None,
+            the decorator returns a partial function, allowing it to be called
+            with arguments. Defaults to None.
+        span_name (str, optional): Custom name for the span. If None,
+            it defaults to ``f'{func.__module__}.{func.__name__}'``.
+            Defaults to None.
+        kind (SpanKind, optional): The ``opentelemetry.trace.SpanKind`` for the
+            created span. Defaults to ``SpanKind.INTERNAL``.
+        attributes (dict, optional): A dictionary of static attributes to be
+            set on the span. Keys are attribute names (str) and values are
+            the corresponding attribute values. Defaults to None.
+        attribute_extractor (callable, optional): A function that can be used
+            to dynamically extract and set attributes on the span.
+            It is called within a ``finally`` block, ensuring it runs even if
+            the decorated function raises an exception.
+            The function signature should be:
+            ``attribute_extractor(span, args, kwargs, result, exception)``
+            where:
+                - ``span`` : the OpenTelemetry ``Span`` object.
+                - ``args`` : a tuple of positional arguments passed
+                - ``kwargs`` : a dictionary of keyword arguments passed
+                - ``result`` : return value (None if an exception occurred)
+                - ``exception`` : exception object if raised (None otherwise).
+            Any exception raised by the ``attribute_extractor`` itself will be
+            caught and logged. Defaults to None.
+
+    Returns:
+        callable: The wrapped function that includes tracing, or a partial
+            decorator if ``func`` is None.
+    """
+    if func is None:
+        return functools.partial(
+            trace_function,
+            span_name=span_name,
+            kind=kind,
+            attributes=attributes,
+            attribute_extractor=attribute_extractor,
+        )
+
+    actual_span_name = span_name or f'{func.__module__}.{func.__name__}'
+
+    is_async_func = inspect.iscoroutinefunction(func)
+
+    logger.debug(
+        f'Start tracing for {actual_span_name}, is_async_func {is_async_func}'
+    )
+
+    @functools.wraps(func)
+    async def async_wrapper(*args, **kwargs) -> Any:
+        """Async Wrapper for the decorator."""
+        logger.debug('Start async tracer')
+        tracer = trace.get_tracer(
+            INSTRUMENTING_MODULE_NAME, INSTRUMENTING_MODULE_VERSION
+        )
+        with tracer.start_as_current_span(actual_span_name, kind=kind) as span:
+            if attributes:
+                for k, v in attributes.items():
+                    span.set_attribute(k, v)
+
+            result = None
+            exception = None
+
+            try:
+                # Async wrapper, await for the function call to complete.
+                result = await func(*args, **kwargs)
+                span.set_status(StatusCode.OK)
+                return result
+
+            except Exception as e:
+                exception = e
+                span.record_exception(e)
+                span.set_status(StatusCode.ERROR, description=str(e))
+                raise
+            finally:
+                if attribute_extractor:
+                    try:
+                        attribute_extractor(
+                            span, args, kwargs, result, exception
+                        )
+                    except Exception as attr_e:
+                        logger.error(
+                            f'attribute_extractor error in span {actual_span_name}: {attr_e}'
+                        )
+
+    @functools.wraps(func)
+    def sync_wrapper(*args, **kwargs) -> Any:
+        """Sync Wrapper for the decorator."""
+        tracer = trace.get_tracer(INSTRUMENTING_MODULE_NAME)
+        with tracer.start_as_current_span(actual_span_name, kind=kind) as span:
+            if attributes:
+                for k, v in attributes.items():
+                    span.set_attribute(k, v)
+
+            result = None
+            exception = None
+
+            try:
+                # Sync wrapper, execute the function call.
+                result = func(*args, **kwargs)
+                span.set_status(StatusCode.OK)
+                return result
+
+            except Exception as e:
+                exception = e
+                span.record_exception(e)
+                span.set_status(StatusCode.ERROR, description=str(e))
+                raise
+            finally:
+                if attribute_extractor:
+                    try:
+                        attribute_extractor(
+                            span, args, kwargs, result, exception
+                        )
+                    except Exception as attr_e:
+                        logger.error(
+                            f'attribute_extractor error in span {actual_span_name}: {attr_e}'
+                        )
+
+    return async_wrapper if is_async_func else sync_wrapper
+
+
+def trace_class(
+    include_list: list[str] | None = None,
+    exclude_list: list[str] | None = None,
+    kind: SpanKind = SpanKind.INTERNAL,
+) -> Callable:
+    """A class decorator to automatically trace specified methods of a class.
+
+    This decorator iterates over the methods of a class and applies the
+    `trace_function` decorator to them, based on the `include_list` and
+    `exclude_list` criteria. Methods starting or ending with double underscores
+    (dunder methods, e.g., `__init__`, `__call__`) are always excluded by default.
+
+    Args:
+        include_list (list[str], optional): A list of method names to
+            explicitly include for tracing. If provided, only methods in this
+            list (that are not dunder methods) will be traced.
+            Defaults to None (trace all non-dunder methods).
+        exclude_list (list[str], optional): A list of method names to exclude
+            from tracing. This is only considered if `include_list` is not
+            provided. Dunder methods are implicitly excluded.
+            Defaults to an empty list.
+        kind (SpanKind, optional): The `opentelemetry.trace.SpanKind` for the
+            created spans on the methods. Defaults to `SpanKind.INTERNAL`.
+
+    Returns:
+        callable: A decorator function that, when applied to a class,
+                  modifies the class to wrap its specified methods with tracing.
+
+    Example:
+        To trace all methods except 'internal_method':
+        ```python
+        @trace_class(exclude_list=['internal_method'])
+        class MyService:
+            def public_api(self):
+                pass
+
+            def internal_method(self):
+                pass
+        ```
+
+        To trace only 'method_one' and 'method_two':
+        ```python
+        @trace_class(include_list=['method_one', 'method_two'])
+        class AnotherService:
+            def method_one(self):
+                pass
+
+            def method_two(self):
+                pass
+
+            def not_traced_method(self):
+                pass
+        ```
+    """
+    logger.debug(f'Trace all class {include_list}, {exclude_list}')
+    exclude_list = exclude_list or []
+
+    def decorator(cls: Any) -> Any:
+        all_methods = {}
+        for name, method in inspect.getmembers(cls, inspect.isfunction):
+            # Skip Dunders
+            if name.startswith('__') and name.endswith('__'):
+                continue
+
+            # Skip if include list is defined but the method not included.
+            if include_list and name not in include_list:
+                continue
+            # Skip if include list is not defined but the method is in excludes.
+            if not include_list and name in exclude_list:
+                continue
+
+            all_methods[name] = method
+            span_name = f'{cls.__module__}.{cls.__name__}.{name}'
+            # Set the decorator on the method.
+            setattr(
+                cls,
+                name,
+                trace_function(span_name=span_name, kind=kind)(method),
+            )
+        return cls
+
+    return decorator

pygeai-0.6.0b15.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: pygeai
+Version: 0.6.0b15
+Summary: Software Development Kit to interact with Globant Enterprise AI.
+Author-email: Globant <geai-sdk@globant.com>
+License-Expression: MIT
+Keywords: geai,pygeai
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: packaging
+Requires-Dist: mcp
+Requires-Dist: pyyaml
+Requires-Dist: prompt_toolkit
+Requires-Dist: toml
+Requires-Dist: httpx==0.28.1
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: opentelemetry-api>=1.33.0
+Requires-Dist: opentelemetry-sdk>=1.33.0
+Requires-Dist: sse-starlette>=2.3.3
+Requires-Dist: starlette>=0.46.2
+Requires-Dist: typing-extensions>=4.13.2
+Requires-Dist: streamlit
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx-markdown-builder; extra == "docs"
+Provides-Extra: tests
+Requires-Dist: coverage; extra == "tests"
+Dynamic: license-file
+
+# PyGEAI - SDK for Globant Enterprise AI
+
+PyGEAI is a Software Development Kit (SDK) for interacting with [Globant Enterprise AI](https://wiki.genexus.com/enterprise-ai/wiki?8,Table+of+contents%3AEnterprise+AI). It comprises libraries, tools, code samples, and documentation to simplify your experience with the platform.
+
+## Terms and conditions
+
+By using the Python SDK to interact with Globant Enterprise AI, you agree with the following Terms and Conditions:
+
+[Terms and Conditions](https://www.globant.com/enterprise-ai/terms-of-use)
+
+## Compatibility
+This package is compatible with the Globant Enterprise AI release from November 2025.
+
+## Configuration
+
+Before using the SDK, you need to define `GEAI_API_KEY` (`$SAIA_APITOKEN`) and `GEAI_API_BASE_URL` (`$BASE_URL`). You can achieve this in three ways:
+
+* **Environment variables:** Set `GEAI_API_KEY` and `GEAI_API_BASE_URL` as environment variables in your operating system.
+* **Credentials file:** Create a file named credentials in the `.geai` directory within your user home directory (`$USER_HOME/.geai/credentials`) and define `GEAI_API_KEY` and `GEAI_API_BASE_URL` within this file.
+* **Client instantiation:** Specify the `api_key` and `base_url` parameters directly when creating an instance of a client class.
+
+**Note:** If you plan to use the [Evaluation Module](https://wiki.genexus.com/enterprise-ai/wiki?896,Evaluation), you must also define `GEAI_API_EVAL_URL`
+
+### Credentials file
+The credentials file is organized via profiles, so one can interact with different instances of Globant Enterprise AI by just
+referencing which profile one wishes to use. This also applies to different levels of permissions.
+
+The structure of the credentials file is as follows:
+
+```
+[default]
+geai_api_key = <API_TOKEN>
+geai_api_base_url = <GEAI_BASE_URL>
+geai_api_evaul_url = <GEAI_EVALUATION_MODULE_URL>
+
+[<another alias>]
+geai_api_key = <API_TOKEN>
+geai_api_base_url = <GEAI_BASE_URL>
+geai_api_evaul_url = <GEAI_EVALUATION_MODULE_URL>
+
+```
+
+After setting the profiles, one can use them with the --alias option, for example:
+
+```bash 
+geai --alias test llm list-providers
+```
+
+## Modules
+
+The SDK consists of several modules, all accessible through a single package `pygeai`:
+
+- **`pygeai`**: The package encapsulates all components of the SDK.
+- **`admin`**: Allows the user to interact with some of the administration endpoints of Globant Enterprise AI.
+- **`assistant`**: This module handles interactions with various Assistants, including [Data Analyst Assistants](https://wiki.genexus.com/enterprise-ai/wiki?886,Data+Analyst+Assistant+2.0), [RAG Assistants](https://wiki.genexus.com/enterprise-ai/wiki?44,RAG+Assistants+Introduction), [Chat with Data Assistants](https://wiki.genexus.com/enterprise-ai/wiki?159,Chat+with+Data+Assistant), [Chat with API Assistants](https://wiki.genexus.com/enterprise-ai/wiki?110,API+Assistant), and [Chat Assistants](https://wiki.genexus.com/enterprise-ai/wiki?708,Chat+Assistant [soon to be deprecated]).
+- **`chat`**: This module offers facilities to chat with assistants/agents created in Globant Enterprise AI.
+- **`core`**: This module handles interactions with the fundamental components of Globant Enterprise.
+- **`cli`**: This module provides a command-line tool for interacting with the SDK.
+- **`dbg`**: This module includes a debugger to troubleshoot potential SDK issues and gain detailed insights into its operations.
+- **`evaluation`**: This module provides functionality for the evaluation module.
+- **`flows`**: This module enables interactions with [Flows](https://wiki.genexus.com/enterprise-ai/wiki?321,Flows+in+Globant+Enterprise+AI) [in development]. 
+- **`gam`**: This module allows interaction with [GAM] (https://wiki.genexus.com/commwiki/wiki?24746,Table+of+contents%3AGeneXus+Access+Manager+%28GAM%29,).
+- **`health`**: Provides an easy way to check the status of the Globant Enterprise AI instance one is using.
+- **`lab`**: This module facilitates interactions with [The Lab] (https://docs.globant.ai/en/wiki?1671,The+Lab).
+- **`organization`**: This module facilitates interactions with Organizations and [Projects](https://wiki.genexus.com/enterprise-ai/wiki?565,Projects) in Globant Enterprise AI.
+- **`migration`**: This module provides functionality to migrate Agents, Tools and Projects between instances and organizations.
+- **`proxy`**: This module handles [integrations with MCP and A2A] (https://docs.globant.ai/en/wiki?1179,Importing+Tools+using+MCP+and+A2A+Servers).
+
+## Usage
+
+### Install PyGEAI
+Use pip to install the package from PyPI:
+
+```
+(venv) ~$ pip install pygeai
+```
+
+To install pre-release versions, you can run:
+```
+(venv) ~$ pip install --pre pygeai
+```
+
+### Verify installation
+To check the installed PyGEAI version, run:
+
+```
+(venv) ~$ geai v
+```
+
+### View help
+
+To access the general help menu:
+
+```
+(venv) ~$ geai h
+```
+To view help for a specific command:
+
+```
+(venv) ~$ geai <command> h
+```
+
+### Debugger
+
+The `pygeai-dbg` package provides a command-line debugger (`geai-dbg`) for troubleshooting and inspecting the `geai` CLI. 
+It pauses execution at breakpoints, allowing you to inspect variables, execute Python code, and control program flow interactively.
+
+To debug a `geai` command, replace `geai` with `geai-dbg`. For example:
+
+```bash
+(venv) ~$ geai-dbg ail lrs
+```
+
+This pauses at the `main` function in `pygeai.cli.geai`, displaying an interactive prompt `(geai-dbg)`. 
+You can then use commands like `continue` (resume), `run` (run without pauses), `quit` (exit), or `help` (list commands).
+
+
+### Man Pages Documentation
+
+The package includes Unix manual pages (man pages) for detailed command-line documentation. 
+
+To install man pages locally:
+
+```bash
+geai-install-man
+```
+
+To install man pages system-wide:
+
+```bash
+sudo geai-install-man --system
+```
+
+To access the man pages:
+
+```bash
+man geai
+```
+
+#### Setting up Man Pages Access
+
+If you're using a virtual environment, you'll need to configure your system to find the man pages. Add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.):
+
+```bash
+# For macOS
+if [ -n "$VIRTUAL_ENV" ]; then
+    export MANPATH="$VIRTUAL_ENV/share/man:$MANPATH"
+fi
+
+# For Linux
+if [ -n "$VIRTUAL_ENV" ]; then
+    export MANPATH="$VIRTUAL_ENV/man:$MANPATH"
+fi
+```
+
+After adding this configuration:
+1. Reload your shell configuration: `source ~/.bashrc` or `source ~/.zshrc`
+2. The man pages will be available when your virtual environment is active
+
+## Bugs and suggestions
+To report any bug, request features or make any suggestions, the following email is available:
+
+<geai-sdk@globant.com>
+
+## Authors
+Copyright 2025, Globant. All rights reserved