pygeai 0.6.0b3__py3-none-any.whl → 0.6.0b6__py3-none-any.whl

pygeai/_docs/source/content/ai_lab.rst

@@ -0,0 +1,102 @@
+The Lab
+=======
+
+The Globant Enterprise AI Lab is a comprehensive framework designed to create, manage, and orchestrate autonomous AI agents capable of addressing complex tasks with minimal human intervention. It provides a structured environment for defining agents, their associated tools, reasoning strategies, and workflows, all integrated within a cohesive ecosystem. The PyGEAI SDK serves as the primary interface for developers to interact with the Lab, offering a Python-native experience through the `lab` module, which enables seamless management of the Lab’s resources and operations.
+
+Overview
+--------
+
+The Globant Enterprise AI Lab enables the creation of intelligent AI agents, from collaborative co-pilots to fully
+autonomous systems, capable of executing intricate tasks. Its modular design ensures flexibility, allowing developers
+to define agent behaviors, orchestrate collaborative workflows, and manage knowledge artifacts. The PyGEAI SDK
+streamlines these processes by providing an intuitive, Python-centric interface that abstracts the Lab’s underlying
+APIs, making it accessible to developers familiar with Python conventions.
+
+The Lab’s core modules are:
+
+- **Agents & Tools Repository**: A centralized hub for defining and managing agents and their resources, such as skills, tools, and external API integrations.
+- **Agentic Flows**: A system for creating workflows that combine tasks, agents, and knowledge artifacts to achieve broader objectives.
+- **Knowledge Base**: A repository for storing and organizing artifacts (e.g., documents, data outputs) that agents consume or produce during workflows.
+- **Agent Runtime**: The execution environment where agents perform tasks, interact with artifacts, and respond to events within defined workflows.
+
+
+Interacting with the Lab via PyGEAI SDK
+--------------------------------------
+
+The PyGEAI SDK’s `lab` module provides a streamlined interface for developers to engage with the Globant Enterprise AI Lab. Designed to align with Python conventions, it offers a command-line tool that facilitates interaction with the Lab’s resources, including agents, tools, reasoning strategies, processes, tasks, and runtime instances. The `lab` module supports a range of operations, ensuring developers can efficiently manage the Lab’s ecosystem.
+
+### Managing Agents
+
+The `lab` module enables developers to define and manage AI agents within the Lab. Agents are entities configured with specific prompts, language models, and operational parameters to perform designated tasks. Through the `lab` module, developers can create agents with custom attributes, update their configurations, retrieve details, list available agents, publish revisions, share agents via links, or remove them as needed. This functionality allows for precise control over agent lifecycle and behavior within the Lab’s environment.
+
+### Configuring Tools
+
+Tools extend agent capabilities by providing access to external APIs, built-in functions, or custom logic. The `lab` module supports the creation and management of tools, allowing developers to define tools with specific scopes (e.g., API-based or external), configure their parameters, and control their accessibility. Developers can list tools, retrieve tool details, update configurations, publish revisions, set parameters, or delete tools, ensuring tools are seamlessly integrated into the Lab’s workflows.
+
+### Defining Reasoning Strategies
+
+Reasoning strategies guide how agents process information and make decisions. The `lab` module allows developers to create and manage these strategies, specifying system prompts and access scopes to tailor agent reasoning. Developers can list available strategies, retrieve details, update configurations, and ensure strategies align with project requirements, enhancing agent performance within the Lab.
+
+### Orchestrating Processes
+
+Processes in the Lab define workflows that combine agents, tasks, and knowledge artifacts to achieve complex objectives. The `lab` module facilitates process management by enabling developers to create processes, define their structure (including activities, signals, and sequence flows), and update configurations. Developers can list processes, retrieve details, publish revisions, or delete processes, providing full control over workflow orchestration within the Lab.
+
+### Managing Tasks
+
+Tasks are individual units of work within processes, assigned to agents for execution. The `lab` module supports task creation, allowing developers to specify task prompts, artifact types, and descriptions. Developers can list tasks, retrieve task details, update configurations, publish revisions, or delete tasks, ensuring tasks are effectively integrated into the Lab’s workflows.
+
+### Controlling Runtime Instances
+
+The Lab’s runtime environment executes processes, where agents perform tasks and interact with artifacts. The `lab` module provides commands to manage runtime instances, enabling developers to start process instances, monitor their progress, retrieve instance details, access execution history, send signals to influence workflow, or abort instances as needed. This ensures dynamic control over the Lab’s operational execution.
+
+### Running Agents with the Runner
+
+The `Runner` class in the `lab` module provides a direct interface for executing agent tasks asynchronously within the Lab’s runtime environment. It allows developers to run agents with flexible input formats—strings, `ChatMessage`, or `ChatMessageList`—and customizable LLM settings, enabling tailored interactions for testing or production use. The `Runner` simplifies agent execution by handling message processing and LLM configuration, returning a `ProviderResponse` object containing the agent’s response and metadata.
+
+SDK Tools and Utilities
+-----------------------
+
+The PyGEAI SDK provides robust programmatic interfaces for interacting with the Globant Enterprise AI Lab, enabling developers to manage agents, tools, reasoning strategies, processes, tasks, and runtime instances directly within Python applications. Beyond the command-line interface, the SDK offers a high-level manager and low-level client classes, designed to integrate seamlessly into development workflows with structured, object-oriented access or flexible JSON-based interactions.
+
+High-Level Interface: AILabManager
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The AILabManager class serves as the primary high-level interface, offering a Pythonic, object-oriented approach to managing the Lab’s resources. It abstracts the underlying API complexity, mapping responses to structured Python objects such as Agent, Tool, ReasoningStrategy, AgenticProcess, Task, and ProcessInstance. This allows developers to work with strongly typed models, ensuring clarity and reducing errors when creating, updating, retrieving, or deleting Lab entities.
+
+- Agent Management: Create, update, retrieve, list, publish, share, or delete agents using methods like create_agent, update_agent, get_agent, and delete_agent. Agents are represented as Agent objects, encapsulating properties like name, prompts, and LLM configurations.
+- Tool Management: Define and manage tools with methods such as create_tool, update_tool, get_tool, list_tools, publish_tool_revision, and delete_tool. Tools are modeled as Tool objects, supporting API-based or custom configurations with parameters (ToolParameter).
+- Reasoning Strategies: Configure agent reasoning with create_reasoning_strategy, update_reasoning_strategy, get_reasoning_strategy, and list_reasoning_strategies. Strategies are represented as ReasoningStrategy objects, defining system prompts and access scopes.
+- Process Orchestration: Manage workflows through create_process, update_process, get_process, list_processes, publish_process_revision, and delete_process. Processes are encapsulated as AgenticProcess objects, detailing activities, signals, and sequence flows.
+- Task Management: Create and manage tasks with create_task, update_task, get_task, list_tasks, publish_task_revision, and delete_task. Tasks are modeled as Task objects, specifying prompts and artifact types.
+- Runtime Control: Start, monitor, and control process instances using start_instance, get_instance, list_process_instances, get_instance_history, send_user_signal, and abort_instance. Instances are represented as ProcessInstance objects, with execution details and thread information accessible via get_thread_information.
+
+The AILabManager is initialized with an API key, base URL, and optional alias, providing a unified entry point for all Lab operations. Its methods handle error mapping (ErrorListResponse) and response validation, making it ideal for rapid development and integration into larger applications.
+
+Low-Level Interface: Client Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For developers requiring fine-grained control or preferring to work directly with JSON responses, the SDK includes low-level client classes: AgentClient, ToolClient, ReasoningStrategyClient, and AgenticProcessClient. These clients interact with the Lab’s APIs without mapping responses to Python objects, returning raw JSON or text for maximum flexibility.
+
+- AgentClient: Supports operations like create_agent, update_agent, get_agent, list_agents, publish_agent_revision, create_sharing_link, and delete_agent. It handles agent-specific API endpoints, passing parameters like project ID, agent name, prompts, and LLM configurations as dictionaries.
+- ToolClient: Provides methods such as create_tool, update_tool, get_tool, list_tools, publish_tool_revision, get_parameter, set_parameter, and delete_tool. It manages tool configurations, including OpenAPI specifications and parameter lists, with validation for scopes and access levels.
+- ReasoningStrategyClient: Includes create_reasoning_strategy, update_reasoning_strategy, get_reasoning_strategy, and list_reasoning_strategies, allowing direct manipulation of strategy definitions like system prompts and localized descriptions.
+- AgenticProcessClient: Offers comprehensive process and task management with methods like create_process, update_process, get_process, list_processes, publish_process_revision, delete_process, create_task, update_task, get_task, list_tasks, publish_task_revision, delete_task, start_instance, get_instance, list_process_instances, get_instance_history, get_thread_information, send_user_signal, and abort_instance. It handles complex process structures and runtime operations in JSON format.
+
+Each client is initialized with an API key and base URL, using a BaseClient for HTTP requests. They provide direct access to the Lab’s endpoints, enabling custom parsing or integration with external systems where object mapping is unnecessary.
+
+Integration and Flexibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Both the AILabManager and client classes are installable via pip install pygeai and support cross-platform development. The high-level AILabManager is suited for structured applications requiring type safety and ease of use, while the low-level clients cater to scenarios demanding raw API responses or custom workflows. Developers can combine these interfaces within the same project, leveraging AILabManager for rapid prototyping and clients for specialized tasks.
+
+
+PyGEAI SDK - Lab components
+---------------------------
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    ai_lab/models
+    ai_lab/runner
+    ai_lab/usage
+    ai_lab/cli
+    ai_lab/spec
+

pygeai/_docs/source/content/api_reference/chat.rst

@@ -0,0 +1,328 @@
+Chat
+====
+
+Chat Completion
+~~~~~~~~~~~~~~~
+
+The GEAI SDK provides functionality to interact with the Globant Enterprise AI chat system, allowing users to generate chat completions using specified models and parameters. This can be achieved through the command line interface, the low-level service layer (ChatClient), or the high-level service layer (ChatManager). The `stream` parameter, which enables streaming responses, is supported in the command line and low-level service layer but not in the high-level service layer.
+
+Command Line
+^^^^^^^^^^^^
+
+The `geai chat completion` command generates a chat completion based on the provided model and messages. Various flags allow customization of the response, such as streaming, temperature, and maximum tokens.
+
+.. code-block:: shell
+
+    geai chat completion \
+      --model "saia:assistant:Welcome data Assistant 3" \
+      --messages '[{"role": "user", "content": "Hi, welcome to Globant Enterprise AI!!"}]' \
+      --temperature 0.7 \
+      --max-tokens 1000 \
+      --stream 1
+
+To use a different API key alias for authentication:
+
+.. code-block:: shell
+
+    geai --alias admin chat completion \
+      --model "saia:assistant:Welcome data Assistant 3" \
+      --messages '[{"role": "user", "content": "What is Globant Enterprise AI?"}]' \
+      --temperature 0.5 \
+      --max-tokens 500
+
+For a non-streaming response with additional parameters like frequency and presence penalties:
+
+.. code-block:: shell
+
+    geai chat completion \
+      --model "saia:assistant:Welcome data Assistant 3" \
+      --messages '[{"role": "user", "content": "Can you explain AI solutions offered by Globant?"}]' \
+      --temperature 0.6 \
+      --max-tokens 800 \
+      --frequency-penalty 0.1 \
+      --presence-penalty 0.2 \
+      --stream 0
+
+Using tools and tool choice to fetch weather data:
+
+.. code-block:: shell
+
+    geai chat completion \
+      --model "saia:assistant:Welcome data Assistant 3" \
+      --messages '[{"role": "user", "content": "Please get the current weather for San Francisco."}]' \
+      --temperature 0.6 \
+      --max-tokens 800 \
+      --tools '[{"name": "get_weather", "description": "Fetches the current weather for a given location", "parameters": {"type": "object", "properties": {"location": {"type": "string", "description": "City name"}}, "required": ["location"]}, "strict": true}]' \
+      --tool-choice '{"type": "function", "function": {"name": "get_weather"}}' \
+      --stream 1
+
+Low Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The `ChatClient` class provides a low-level interface to generate chat completions. It supports both streaming and non-streaming responses and allows fine-grained control over parameters.
+
+.. code-block:: python
+
+    from pygeai.chat.clients import ChatClient
+
+    client = ChatClient()
+
+    response = client.chat_completion(
+        model="saia:assistant:Welcome data Assistant 3",
+        messages=[{"role": "user", "content": "What is Globant Enterprise AI?"}],
+        temperature=0.5,
+        max_tokens=500,
+        stream=False
+    )
+    print(response)
+
+Streaming response with tools:
+
+.. code-block:: python
+
+    from pygeai.chat.clients import ChatClient
+
+    client = ChatClient()
+
+    llm_settings = {
+        "temperature": 0.6,
+        "max_tokens": 800,
+        "frequency_penalty": 0.1,
+        "presence_penalty": 0.2
+    }
+
+    messages = [{"role": "user", "content": "Please get the current weather for San Francisco."}]
+
+    tools = [
+        {
+            "name": "get_weather",
+            "description": "Fetches the current weather for a given location",
+            "parameters": {
+                "type": "object",
+                "properties": {"location": {"type": "string", "description": "City name"}},
+                "required": ["location"]
+            },
+            "strict": True
+        }
+    ]
+
+    tool_choice = {"type": "function", "function": {"name": "get_weather"}}
+
+    response = client.chat_completion(
+        model="saia:assistant:Welcome data Assistant 3",
+        messages=messages,
+        stream=True,
+        tools=tools,
+        tool_choice=tool_choice,
+        **llm_settings
+    )
+
+    for chunk in response:
+        print(chunk, end="")
+
+Using variables and thread ID:
+
+.. code-block:: python
+
+    from pygeai.chat.clients import ChatClient
+
+    client = ChatClient()
+
+    response = client.chat_completion(
+        model="saia:assistant:Welcome data Assistant 3",
+        messages=[
+            {"role": "system", "content": "You are a helpful assistant for Globant Enterprise AI."},
+            {"role": "user", "content": "What AI solutions does Globant offer?"}
+        ],
+        temperature=0.8,
+        max_tokens=2000,
+        presence_penalty=0.1,
+        thread_id="thread_123e4567-e89b-12d3-a456-426614174000",
+        variables=[{"key": "user_region", "value": "North America"}, {"key": "industry", "value": "Technology"}],
+        stream=False
+    )
+    print(response)
+
+High Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The `ChatManager` class provides a high-level interface for generating chat completions. It does not support streaming responses but simplifies the process by using structured models like `ChatMessageList` and `LlmSettings`.
+
+.. code-block:: python
+
+    from pygeai.chat.managers import ChatManager
+    from pygeai.core.models import LlmSettings, ChatMessageList, ChatMessage
+
+    manager = ChatManager()
+
+    llm_settings = LlmSettings(
+        temperature=0.5,
+        max_tokens=500,
+        frequency_penalty=0.2
+    )
+
+    messages = ChatMessageList(
+        messages=[ChatMessage(role="user", content="Can you explain what Globant Enterprise AI does?")]
+    )
+
+    response = manager.chat_completion(
+        model="saia:assistant:Welcome data Assistant 3",
+        messages=messages,
+        llm_settings=llm_settings
+    )
+    print(response)
+
+Using tools to check weather and send an email:
+
+.. code-block:: python
+
+    from pygeai.chat.managers import ChatManager
+    from pygeai.core.models import LlmSettings, ChatMessageList, ChatMessage, ChatTool, ChatToolList
+
+    manager = ChatManager()
+
+    llm_settings = LlmSettings(
+        temperature=0.7,
+        max_tokens=1000,
+        frequency_penalty=0.3,
+        presence_penalty=0.2
+    )
+
+    messages = ChatMessageList(
+        messages=[ChatMessage(role="user", content="Can you check the weather for New York and send an email summary?")]
+    )
+
+    tools = ChatToolList(
+        variables=[
+            ChatTool(
+                name="get_weather",
+                description="Fetches the current weather for a given location",
+                parameters={
+                    "type": "object",
+                    "properties": {"location": {"type": "string", "description": "City name"}},
+                    "required": ["location"]
+                },
+                strict=True
+            ),
+            ChatTool(
+                name="send_email",
+                description="Sends an email to a recipient with a subject and body",
+                parameters={
+                    "type": "object",
+                    "properties": {
+                        "recipient": {"type": "string", "description": "Email address"},
+                        "subject": {"type": "string", "description": "Email subject"},
+                        "body": {"type": "string", "description": "Email content"}
+                    },
+                    "required": ["recipient", "subject", "body"]
+                },
+                strict=False
+            )
+        ]
+    )
+
+    response = manager.chat_completion(
+        model="saia:assistant:Welcome data Assistant 3",
+        messages=messages,
+        llm_settings=llm_settings,
+        tools=tools
+    )
+    print(response)
+
+With variables and thread ID:
+
+.. code-block:: python
+
+    from pygeai.chat.managers import ChatManager
+    from pygeai.core.models import LlmSettings, ChatMessageList, ChatMessage, ChatVariable, ChatVariableList
+
+    manager = ChatManager()
+
+    llm_settings = LlmSettings(
+        temperature=0.8,
+        max_tokens=2000,
+        presence_penalty=0.1
+    )
+
+    messages = ChatMessageList(
+        messages=[
+            ChatMessage(role="system", content="You are a helpful assistant for Globant Enterprise AI."),
+            ChatMessage(role="user", content="What AI solutions does Globant offer?")
+        ]
+    )
+
+    variables = ChatVariableList(
+        variables=[
+            ChatVariable(key="user_region", value="North America"),
+            ChatVariable(key="industry", value="Technology")
+        ]
+    )
+
+    response = manager.chat_completion(
+        model="saia:assistant:Welcome data Assistant 3",
+        messages=messages,
+        llm_settings=llm_settings,
+        thread_id="thread_123e4567-e89b-12d3-a456-426614174000",
+        variables=variables
+    )
+    print(response)
+
+With tool choice:
+
+.. code-block:: python
+
+    from pygeai.chat.managers import ChatManager
+    from pygeai.core.models import LlmSettings, ChatMessageList, ChatMessage, ChatTool, ChatToolList, ToolChoice, ToolChoiceObject, ToolChoiceFunction
+
+    manager = ChatManager()
+
+    llm_settings = LlmSettings(
+        temperature=0.6,
+        max_tokens=800,
+        frequency_penalty=0.1,
+        presence_penalty=0.2
+    )
+
+    messages = ChatMessageList(
+        messages=[ChatMessage(role="user", content="Please get the current weather for San Francisco.")]
+    )
+
+    tools = ChatToolList(
+        variables=[
+            ChatTool(
+                name="get_weather",
+                description="Fetches the current weather for a given location",
+                parameters={
+                    "type": "object",
+                    "properties": {"location": {"type": "string", "description": "City name"}},
+                    "required": ["location"]
+                },
+                strict=True
+            ),
+            ChatTool(
+                name="send_notification",
+                description="Sends a notification with a message",
+                parameters={
+                    "type": "object",
+                    "properties": {"message": {"type": "string", "description": "Notification content"}},
+                    "required": ["message"]
+                },
+                strict=False
+            )
+        ]
+    )
+
+    tool_choice = ToolChoice(
+        value=ToolChoiceObject(
+            function=ToolChoiceFunction(name="get_weather")
+        )
+    )
+
+    response = manager.chat_completion(
+        model="saia:assistant:Welcome data Assistant 3",
+        messages=messages,
+        llm_settings=llm_settings,
+        tool_choice=tool_choice,
+        tools=tools
+    )
+    print(response)

pygeai/_docs/source/content/api_reference/embeddings.rst

@@ -0,0 +1,124 @@
+Embeddings
+==========
+
+The API Reference enables you to generate embeddings from various input types, including text and images. You can leverage different LLM providers and their respective models for this purpose.
+
+* Generate embeddings: Generates embeddings for a given list of inputs using a specified LLM model.
+
+
+Generate embeddings
+~~~~~~~~~~~~~~
+
+Generates embeddings from different input types using `PyGEA </pygeai>`_. It can interact with several LLM providers and their respective models for embedding generation.
+
+To achieve this, you have three options:
+
+* `Command Line </docs/source/content/api_reference.rst#command-line>`_
+* `Low-Level Service Layer </docs/source/content/api_reference.rst#low-level-service-layer>`_
+* `High-Level Service Layer </docs/source/content/api_reference.rst#high-level-service-layer>`_
+
+
+Command line
+^^^^^^^^^^^^
+
+Use the following command to generate embeddings:
+
+.. code-block:: shell
+
+    geai emb generate \
+     -i "<your_text_input>" \
+     -i "<your_image_input>" \
+     -m "<provider>/<model_name>"
+
+Replace the placeholders with your desired values:
+
+* `<your_text_input>`: The text you want to generate an embedding for. For example: `"Help me with Globant Enterprise AI."`
+* `<your_image_input>`: The image data, encoded appropriately (e.g., base64). For example: `"image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAEElEQVR4nGK6HcwNCAAA//8DTgE8HuxwEQAAAABJRU5ErkJggg=="`
+* `<provider>/<model_name>`: The provider and model to use for embedding generation. For example: `"awsbedrock/amazon.titan-embed-text-v1"`
+
+
+Low level service layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to generate embeddings using the low-level service layer:
+
+
+.. code-block:: python
+
+    from pygeai.core.embeddings.clients import EmbeddingsClient
+    from pygeai.core.services.llm.model import Model
+    from pygeai.core.services.llm.providers import Provider
+
+    client = EmbeddingsClient()
+
+    inputs = [
+        "<your_text_input>",
+        "<your_image_input>"
+    ]
+
+    embeddings = client.generate_embeddings(
+        input_list=inputs,
+        model=f"{Provider.<provider>}/{Model.<provider>.<model_name>}",
+        encoding_format=None,
+        dimensions=None,
+        user=None,
+        input_type=None,
+        timeout=600,
+        cache=False
+    )
+
+    print(embeddings)
+
+
+Replace the placeholders with your desired values:
+
+* `<your_text_input>`: Text you want to generate an embedding for. For example: `"Help me with Globant Enterprise AI"`
+* `<your_image_input>`: Image data, encoded appropriately (e.g., base64). For example: `"image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAEElEQVR4nGK6HcwNCAAA//8DTgE8HuxwEQAAAABJRU5ErkJggg=="`
+* `<provider>`: LLM provider. For example: `AWS_BEDROCK`
+* `<model_name>`: Specific model from the provider. For example: `AMAZON_TITAN_EMBED_TEXT_V1`
+
+
+High level service layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to generate embeddings using the high-level service layer:
+
+
+.. code-block:: python
+
+    from pygeai.core.embeddings.managers import EmbeddingsManager
+    from pygeai.core.embeddings.models import EmbeddingConfiguration
+    from pygeai.core.services.llm.model import Model
+    from pygeai.core.services.llm.providers import Provider
+
+    manager = EmbeddingsManager()
+
+    inputs = [
+        "<your_text_input>",
+        "<your_image_input>"
+    ]
+
+
+    configuration = EmbeddingConfiguration(
+        inputs=inputs,
+        model=f"{Provider.<provider>}/{Model.<provider>.<model_name>}",
+        encoding_format=None,
+        dimensions=None,
+        user=None,
+        input_type=None,
+        timeout=600,
+        cache=False
+    )
+
+    embeddings = manager.generate_embeddings(configuration)
+    print(embeddings)
+
+
+Replace the placeholders with your desired values:
+
+* `<your_text_input>`: Text you want to generate an embedding for. For example: `"Help me with Globant Enterprise AI"`
+* `<your_image_input>`: Image data, encoded appropriately (e.g., base64). For example: `"image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAEElEQVR4nGK6HcwNCAAA//8DTgE8HuxwEQAAAABJRU5ErkJggg=="`
+* `<provider>`: LLM provider. For example: `AWS_BEDROCK`
+* `<model_name>`: Specific model from the provider. For example: `AMAZON_TITAN_EMBED_TEXT_V1`
+
+