pygeai 0.6.0b10__py3-none-any.whl → 0.6.0b12__py3-none-any.whl

pygeai/_docs/source/content/ai_lab/cli.rst

@@ -1,5 +1,5 @@
 Working with the GEAI Lab using the CLI
-======================================
+=======================================
 
 The `geai ai-lab` command-line interface (CLI) allows users to interact with the Globant Enterprise AI (GEAI) Lab to manage agents, tools, reasoning strategies, processes, tasks, and process instances. This guide provides step-by-step instructions for performing common operations using CLI commands.
 
@@ -309,7 +309,7 @@ Remove a tool from the project.
      --tool-id "88888888-8888-8888-8888-888888888888"
 
 Managing Reasoning Strategies
-----------------------------
+-----------------------------
 
 Reasoning strategies define how agents process information.
 
@@ -591,7 +591,7 @@ Remove a task from the project.
      --task-id "eeeeffff-0000-1111-2222-333333333333"
 
 Managing Process Instances
--------------------------
+--------------------------
 
 Process instances represent running workflows.
 
@@ -690,7 +690,7 @@ Stop a running process instance.
      --instance-id "<instance-id>"
 
 Complete Example Workflow
-------------------------
+-------------------------
 
 This example demonstrates creating an agent, a task, a process, and starting an instance.
 

pygeai/_docs/source/content/ai_lab/models.rst

@@ -42,7 +42,7 @@ Usage Examples
    # Output: Dictionary with filter settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Most fields are optional for flexible queries.
 - Pagination requires non-negative integers.
@@ -86,7 +86,7 @@ Usage Examples
    # Output: {"temperature": 0.8, "topK": 40, "topP": 0.95}
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - All fields are required.
 - Temperature should range from 0.1 to 2.0.
@@ -135,7 +135,7 @@ Usage Examples
    # Output: Dictionary with LLM settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Core fields are mandatory.
 - Token limits depend on LLM capacity.
@@ -188,7 +188,7 @@ Usage Examples
    # Output: Dictionary with model settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name is required; must be Lab-supported.
 - Optional LLM config can be a dictionary.
@@ -231,7 +231,7 @@ Usage Examples
    # Output: Dictionary with example data
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Both fields are required; output must be JSON.
 - Keep examples concise and relevant.
@@ -274,7 +274,7 @@ Usage Examples
    # Output: {"key": "summary", "description": "Text summary."}
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Key and description are required.
 - Keys must be unique per prompt.
@@ -321,7 +321,7 @@ Usage Examples
    # Output: Dictionary with prompt settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Instructions, inputs, and outputs are required.
 - Outputs need at least one entry.
@@ -367,7 +367,7 @@ Usage Examples
    # Output: List of model dictionaries
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Models collection is required; can be empty.
 - Accepts models as dictionaries.
@@ -375,6 +375,92 @@ Restrictions and Considerations
 - Ensure unique model names.
 - Simplifies bulk model setup.
 
+
+Permission
+----------
+
+Purpose
+~~~~~~~
+
+Represents permission settings for an agent, defining access levels for chat sharing and external execution.
+
+Usage Examples
+~~~~~~~~~~~~~~
+
+**Via Attributes**:
+
+.. code-block:: python
+
+   from pygeai.lab.models import Permission
+
+   permission = Permission(chat_sharing="organization", external_execution="project")
+   print(permission.to_dict())
+   # Output: {"chatSharing": "organization", "externalExecution": "project"}
+
+**Via Dictionary**:
+
+.. code-block:: python
+
+   from pygeai.lab.models import Permission
+
+   permission = Permission(**{
+       "chatSharing": "organization",
+       "externalExecution": "none"
+   })
+   print(permission.to_dict())
+   # Output: {"chatSharing": "organization", "externalExecution": "none"}
+
+Restrictions and Considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Valid values for both fields: "none", "organization", "project"
+- Both fields are optional
+- Used to control agent sharing and execution permissions
+- Can be used as `permissions` or `effective_permissions` in Agent model
+
+Property
+--------
+
+Purpose
+~~~~~~~
+
+Represents a custom property for an agent, allowing key-value storage with type information.
+
+Usage Examples
+~~~~~~~~~~~~~~
+
+**Via Attributes**:
+
+.. code-block:: python
+
+   from pygeai.lab.models import Property
+
+   property = Property(data_type="string", key="environment", value="production")
+   print(property.to_dict())
+   # Output: {"dataType": "string", "key": "environment", "value": "production"}
+
+**Via Dictionary**:
+
+.. code-block:: python
+
+   from pygeai.lab.models import Property
+
+   property = Property(**{
+       "dataType": "number",
+       "key": "max_retries",
+       "value": "3"
+   })
+   print(property.to_dict())
+   # Output: {"dataType": "number", "key": "max_retries", "value": "3"}
+
+Restrictions and Considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- All three fields (data_type, key, value) are required
+- Supported data types: "string", "number", "boolean", "object", "array"
+- Value is always stored as string, regardless of data_type
+- Used in AgentData to store custom configuration
+- Useful for environment-specific settings
 AgentData
 ---------
 
@@ -422,8 +508,28 @@ Usage Examples
    print(agent_data.to_dict())
    # Output: Dictionary with agent data
 
+**With Properties**:
+
+.. code-block:: python
+
+   from pygeai.lab.models import AgentData, Property
+
+   agent_data = AgentData(**{
+       "prompt": {"instructions": "Process data"},
+       "models": [{"name": "gpt-4"}],
+       "properties": [
+           {"dataType": "string", "key": "environment", "value": "production"},
+           {"dataType": "number", "key": "timeout", "value": "30"},
+           {"dataType": "boolean", "key": "cache_enabled", "value": "true"}
+       ],
+       "strategyName": "Dynamic Prompting"
+   })
+   print(agent_data.properties[0].key)  # Output: "environment"
+   print(agent_data.strategy_name)  # Output: "Dynamic Prompting"
+
+
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Core components are required.
 - Accepts prompt, LLM config, and models as dictionaries.
@@ -482,8 +588,36 @@ Usage Examples
    print(agent.to_dict())
    # Output: Dictionary with agent settings
 
+**With New Fields (permissions, sharing_scope)**:
+
+.. code-block:: python
+
+   from pygeai.lab.models import Agent, Permission
+
+   agent = Agent(**{
+       "name": "SecureAgent",
+       "accessScope": "private",
+       "sharingScope": "organization",
+       "permissions": {
+           "chatSharing": "organization",
+           "externalExecution": "none"
+       },
+       "agentData": {
+           "prompt": {"instructions": "Secure assistant"},
+           "models": [{"name": "gpt-4"}],
+           "properties": [
+               {"dataType": "string", "key": "env", "value": "production"},
+               {"dataType": "boolean", "key": "logging", "value": "true"}
+           ]
+       }
+   })
+   print(agent.sharing_scope)  # Output: "organization"
+   print(agent.permissions.chat_sharing)  # Output: "organization"
+   print(agent.agent_data.properties[0].key)  # Output: "env"
+
+
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name is required; avoid special characters.
 - Accepts `agent_data` as a dictionary.
@@ -529,7 +663,7 @@ Usage Examples
    # Output: List of agent dictionaries
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Agents collection is required; can be empty.
 - Accepts agents as dictionaries.
@@ -572,7 +706,7 @@ Usage Examples
    # Output: Dictionary with link details
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - All fields are required, set by API.
 - Links must be valid URLs.
@@ -616,7 +750,7 @@ Usage Examples
    # Output: Dictionary with parameter details
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Core fields are mandatory.
 - Data types must match API expectations.
@@ -658,7 +792,7 @@ Usage Examples
    # Output: {"description": "Invalid key.", "type": "error"}
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Both fields are required.
 - Types are typically "warning" or "error."
@@ -705,7 +839,7 @@ Usage Examples
    # Output: Dictionary with tool settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name and description are required.
 - Accepts parameters as dictionaries.
@@ -750,7 +884,7 @@ Usage Examples
    # Output: Dictionary with tool list
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Tools collection is required; can be empty.
 - Accepts tools as dictionaries.
@@ -792,7 +926,7 @@ Usage Examples
    # Output: {"language": "english", "description": "Creative strategy."}
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Both fields are required.
 - Use standard language names.
@@ -839,7 +973,7 @@ Usage Examples
    # Output: Dictionary with strategy settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name, scope, and type are required.
 - Accepts descriptions as dictionaries.
@@ -883,7 +1017,7 @@ Usage Examples
    # Output: List of strategy dictionaries
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Strategies collection is required; can be empty.
 - Accepts strategies as dictionaries.
@@ -924,7 +1058,7 @@ Usage Examples
    # Output: Dictionary with knowledge base settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name and artifact types are required.
 - Dictionaries simplify setup.
@@ -969,7 +1103,7 @@ Usage Examples
    # Output: Dictionary with activity settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Core fields are required.
 - Keys must be unique.
@@ -1013,7 +1147,7 @@ Usage Examples
    # Output: Dictionary with signal settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - All fields are required.
 - Keys must be unique.
@@ -1055,7 +1189,7 @@ Usage Examples
    # Output: {"key": "user1", "name": "UserInput"}
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Both fields are required.
 - Keys must be unique.
@@ -1097,7 +1231,7 @@ Usage Examples
    # Output: {"key": "start1", "name": "ProcessStart"}
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Both fields are required.
 - Keys must be unique.
@@ -1140,7 +1274,7 @@ Usage Examples
    # Output: Dictionary with flow settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - All fields are required.
 - Keys must be unique.
@@ -1182,7 +1316,7 @@ Usage Examples
    # Output: {"key": "input_text", "value": "Sample text"}
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Both fields are required.
 - Keys should be unique.
@@ -1226,7 +1360,7 @@ Usage Examples
    # Output: List of variable dictionaries
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Variables collection is optional; defaults to empty.
 - Accepts variables as dictionaries.
@@ -1282,7 +1416,7 @@ Usage Examples
    # Output: Dictionary with process settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name is required; avoid special characters.
 - Accepts activities, events, and flows as dictionaries.
@@ -1325,7 +1459,7 @@ Usage Examples
    # Output: Dictionary with artifact settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name and usage type are required.
 - Usage type is "input" or "output."
@@ -1369,7 +1503,7 @@ Usage Examples
    # Output: List of artifact dictionaries
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Artifact types collection is optional; defaults to empty.
 - Accepts artifact types as dictionaries.
@@ -1419,7 +1553,7 @@ Usage Examples
    # Output: Dictionary with task settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Name is required; avoid special characters.
 - Accepts prompt and artifact types as dictionaries.
@@ -1463,7 +1597,7 @@ Usage Examples
    # Output: Dictionary with process list
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Processes collection is required; can be empty.
 - Accepts processes as dictionaries.
@@ -1506,7 +1640,7 @@ Usage Examples
    # Output: List of task dictionaries
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Tasks collection is required; can be empty.
 - Accepts tasks as dictionaries.
@@ -1548,7 +1682,7 @@ Usage Examples
    # Output: Dictionary with instance settings
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Process and subject are required.
 - Accepts process as a dictionary.
@@ -1593,7 +1727,7 @@ Usage Examples
    # Output: List of instance dictionaries
 
 Restrictions and Considerations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Instances collection is required; can be empty.
 - Accepts instances as dictionaries.

pygeai/_docs/source/content/ai_lab/runner.rst

@@ -4,7 +4,7 @@ Runner
 The `Runner` class in the PyGEAI SDK's `lab` module provides a straightforward, asynchronous interface for executing AI agent tasks within the Globant Enterprise AI Lab's runtime environment. It enables developers to run agents with flexible input formats and customizable language model (LLM) settings, facilitating both testing and production use cases. The `Runner` class abstracts the complexity of chat completion requests, handling message processing and LLM configuration to deliver a `ProviderResponse` object containing the agent’s response and metadata.
 
 Overview
--------
+--------
 
 The `Runner` class is designed to execute agent tasks by invoking the Lab’s chat completion API. It supports multiple input types—strings, `ChatMessage`, or `ChatMessageList`—allowing developers to interact with agents in various contexts, from simple text inputs to structured conversation histories. The class also accepts optional LLM settings to fine-tune the agent's behavior, such as temperature, token limits, and penalties, ensuring precise control over task execution.
 
@@ -236,7 +236,7 @@ Error Handling
 The `Runner` class validates input types and raises a `WrongArgumentError` if the `user_input` is not a string, `ChatMessage`, or `ChatMessageList`. Developers should handle exceptions to ensure robust execution, as shown in the example’s try-except blocks.
 
 Integration with AILabManager
-----------------------------
+-----------------------------
 
 The `Runner` integrates seamlessly with the `AILabManager` class, which is used to create, manage, and retrieve agents. In the example, the `AILabManager` creates and publishes the agent, which is then passed to the `Runner` for execution. This workflow ensures agents are properly configured before runtime execution.
 

pygeai/_docs/source/content/ai_lab/spec.rst

@@ -27,7 +27,7 @@ The ``geai spec`` command is a utility within the Globant Enterprise AI (GEAI) C
 Each subcommand accepts specific options to configure the loading process, such as project ID (specified as a UUID), file path, and publication settings.
 
 Subcommands and Options
-----------------------
+-----------------------
 
 The following subcommands are available under ``geai spec``:
 
@@ -57,7 +57,7 @@ load-agent
   +-------------------------+---------------------------+-------------------------------------------------------------+----------+
   | file                    | --file, -f                | Path to the JSON file containing the agent definition        | Yes      |
   +-------------------------+---------------------------+-------------------------------------------------------------+----------+
-  | automatic_publish       | --automatic-publish, --ap | Define if the agent is published (1) or created as draft (0) | Yes      |
+  | automatic_publish       | --automatic-publish, --ap | Define if agent is published (1) or created as draft (0)     | Yes      |
   +-------------------------+---------------------------+-------------------------------------------------------------+----------+
 
 - **Usage**:
@@ -78,9 +78,9 @@ load-tool
   +=========================+===========================+===========================================================+==========+
   | project_id              | --project-id, --pid       | UUID of the project where the tool will be loaded         | Yes      |
   +-------------------------+---------------------------+-----------------------------------------------------------+----------+
-  | file                    | --file, -f                | Path to the JSON file containing the tool definition       | Yes      |
+  | file                    | --file, -f                | Path to the JSON file containing the tool definition      | Yes      |
   +-------------------------+---------------------------+-----------------------------------------------------------+----------+
-  | automatic_publish       | --automatic-publish, --ap | Define if the tool is published (1) or created as draft (0)| Yes      |
+  | automatic_publish       | --automatic-publish, --ap | Define if tool is published (1) or created as draft (0)   | Yes      |
   +-------------------------+---------------------------+-----------------------------------------------------------+----------+
 
 - **Usage**:
@@ -101,9 +101,9 @@ load-task
   +=========================+===========================+===========================================================+==========+
   | project_id              | --project-id, --pid       | UUID of the project where the task will be loaded         | Yes      |
   +-------------------------+---------------------------+-----------------------------------------------------------+----------+
-  | file                    | --file, -f                | Path to the JSON file containing the task definition       | Yes      |
+  | file                    | --file, -f                | Path to the JSON file containing the task definition      | Yes      |
   +-------------------------+---------------------------+-----------------------------------------------------------+----------+
-  | automatic_publish       | --automatic-publish, --ap | Define if the task is published (1) or created as draft (0)| Yes      |
+  | automatic_publish       | --automatic-publish, --ap | Define if task is published (1) or created as draft (0)   | Yes      |
   +-------------------------+---------------------------+-----------------------------------------------------------+----------+
 
 - **Usage**:
@@ -124,9 +124,9 @@ load-agentic-process
   +=========================+===========================+=====================================================================+==========+
   | project_id              | --project-id, --pid       | UUID of the project where the agentic process will be loaded        | Yes      |
   +-------------------------+---------------------------+---------------------------------------------------------------------+----------+
-  | file                    | --file, -f                | Path to the JSON file containing the agentic process definition      | Yes      |
+  | file                    | --file, -f                | Path to JSON file containing agentic process definition             | Yes      |
   +-------------------------+---------------------------+---------------------------------------------------------------------+----------+
-  | automatic_publish       | --automatic-publish, --ap | Define if the agentic process is published (1) or created as draft (0)| Yes      |
+  | automatic_publish       | --automatic-publish, --ap | Define if process is published (1) or created as draft (0)          | Yes      |
   +-------------------------+---------------------------+---------------------------------------------------------------------+----------+
 
 - **Usage**:
@@ -237,7 +237,7 @@ Attempt to load a task without specifying the file path.
    Error: Cannot load task definition without specifying path to JSON file.
 
 JSON Specification Formats
--------------------------
+--------------------------
 
 The ``load-agent``, ``load-tool``, ``load-task``, and ``load-agentic-process`` subcommands expect JSON files containing agent, tool, task, or agentic process specifications, respectively. The JSON file can contain a single specification (object) or multiple specifications (array).