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

pygeai/_docs/source/content/authentication.rst

@@ -0,0 +1,295 @@
+Authentication
+==============
+
+The PyGEAI SDK supports two authentication methods: **API Key** authentication and **OAuth 2.0** authentication. Both methods provide secure access to Globant Enterprise AI services, with OAuth offering enhanced security through token-based authentication and project-level access control.
+
+API Key Authentication
+----------------------
+
+API Key authentication is the traditional method that uses a project-specific API token. This is the simplest authentication method and is suitable for most use cases.
+
+Configuration
+~~~~~~~~~~~~~
+
+You can configure API Key authentication using the CLI:
+
+.. code-block:: shell
+
+    geai configure
+
+When prompted, enter your API key and base URL:
+
+.. code-block:: shell
+
+    -> Select an alias (Leave empty to use 'default'): default
+    -> Insert your GEAI_API_KEY: your_api_key_here
+    GEAI API KEY for alias 'default' saved successfully!
+    -> Insert your GEAI API BASE URL: https://api.saia.ai
+    GEAI API BASE URL for alias 'default' saved successfully!
+
+Usage in Code
+~~~~~~~~~~~~~
+
+**Using Configured Credentials:**
+
+.. code-block:: python
+
+    from pygeai.lab.clients import AILabClient
+    
+    # Uses credentials from configuration file
+    client = AILabClient()
+
+**Explicit API Key:**
+
+.. code-block:: python
+
+    from pygeai.lab.clients import AILabClient
+    
+    client = AILabClient(
+        api_key="your_api_key_here",
+        base_url="https://api.saia.ai"
+    )
+
+**With Project ID:**
+
+.. code-block:: python
+
+    from pygeai.lab.clients import AILabClient
+    
+    client = AILabClient(
+        api_key="your_api_key_here",
+        base_url="https://api.saia.ai",
+        project_id="your-project-id"
+    )
+
+OAuth 2.0 Authentication
+------------------------
+
+OAuth 2.0 provides enhanced security by using temporary access tokens instead of long-lived API keys. This method requires both an ``access_token`` and a ``project_id``.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before using OAuth authentication, you need to:
+
+1. Obtain OAuth credentials (client ID, username, password)
+2. Get an access token
+3. Know your project ID
+
+Getting an Access Token
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the Auth client to obtain an OAuth 2.0 access token:
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+    
+    auth_client = AuthClient()
+    
+    # Get OAuth 2.0 access token
+    response = auth_client.get_oauth2_access_token(
+        client_id="your-client-id",
+        username="your-username",
+        password="your-password"
+    )
+    
+    access_token = response["access_token"]
+    project_id = "your-project-id"
+
+Usage in Code
+~~~~~~~~~~~~~
+
+**Basic OAuth Authentication:**
+
+.. code-block:: python
+
+    from pygeai.lab.clients import AILabClient
+    
+    client = AILabClient(
+        base_url="https://api.saia.ai",
+        access_token="your_oauth_access_token",
+        project_id="your-project-id"
+    )
+
+**With Other Clients:**
+
+.. code-block:: python
+
+    from pygeai.core.secrets.clients import SecretClient
+    from pygeai.evaluation.clients import EvaluationClient
+    
+    # Secret Client with OAuth
+    secret_client = SecretClient(
+        base_url="https://api.saia.ai",
+        access_token="your_oauth_access_token",
+        project_id="your-project-id"
+    )
+    
+    # Evaluation Client with OAuth
+    eval_client = EvaluationClient(
+        base_url="https://api.saia.ai",
+        eval_url="https://eval.saia.ai",
+        access_token="your_oauth_access_token",
+        project_id="your-project-id"
+    )
+
+Complete OAuth Flow Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+    from pygeai.lab.clients import AILabClient
+    from pygeai.lab.agents.clients import AgentClient
+    
+    # Step 1: Obtain OAuth access token
+    auth_client = AuthClient()
+    token_response = auth_client.get_oauth2_access_token(
+        client_id="your-client-id",
+        username="user@example.com",
+        password="your-password"
+    )
+    
+    access_token = token_response["access_token"]
+    project_id = "your-project-id"
+    
+    # Step 2: Use OAuth token with clients
+    lab_client = AILabClient(
+        base_url="https://api.saia.ai",
+        access_token=access_token,
+        project_id=project_id
+    )
+    
+    # Step 3: Use the client
+    agents = lab_client.list_agents()
+    print(f"Found {len(agents)} agents")
+
+Authentication Comparison
+-------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 35 35
+
+   * - Feature
+     - API Key
+     - OAuth 2.0
+   * - **Security**
+     - Long-lived key
+     - Temporary access token
+   * - **Setup Complexity**
+     - Simple
+     - Moderate
+   * - **Project Isolation**
+     - Optional
+     - Required
+   * - **Token Expiration**
+     - Never (until revoked)
+     - Yes (requires refresh)
+   * - **Header Format**
+     - ``Bearer {api_key}``
+     - ``Bearer {access_token}``
+   * - **Additional Headers**
+     - None (ProjectId optional)
+     - ``ProjectId`` header required
+   * - **Use Case**
+     - Development, testing
+     - Production, multi-project
+
+Implementation Details
+----------------------
+
+Header Injection
+~~~~~~~~~~~~~~~~
+
+The SDK automatically injects authentication headers:
+
+**API Key:**
+
+.. code-block:: python
+
+    Authorization: Bearer your_api_key_here
+
+**OAuth 2.0:**
+
+.. code-block:: python
+
+    Authorization: Bearer your_oauth_access_token
+    ProjectId: your-project-id
+
+Backward Compatibility
+~~~~~~~~~~~~~~~~~~~~~~
+
+OAuth parameters (``access_token`` and ``project_id``) are **keyword-only** parameters to maintain backward compatibility with existing code:
+
+.. code-block:: python
+
+    # Correct - keyword arguments
+    client = AILabClient(
+        base_url="https://api.saia.ai",
+        access_token="token",
+        project_id="project-123"
+    )
+    
+    # Error - cannot pass as positional
+    client = AILabClient("https://api.saia.ai", "token", "project-123")
+
+Validation
+~~~~~~~~~~
+
+The SDK validates authentication parameters:
+
+- **Missing OAuth parameters**: If ``access_token`` is provided without ``project_id``, a ``MissingRequirementException`` is raised.
+- **Complete OAuth**: Both ``access_token`` and ``project_id`` must be provided together.
+
+.. code-block:: python
+
+    # Raises MissingRequirementException
+    client = AILabClient(
+        base_url="https://api.saia.ai",
+        access_token="token_without_project"
+    )
+    
+    # Correct
+    client = AILabClient(
+        base_url="https://api.saia.ai",
+        access_token="token",
+        project_id="project-123"
+    )
+
+Best Practices
+--------------
+
+1. **Use OAuth for Production**: OAuth provides better security through temporary tokens and project isolation.
+
+2. **Store Credentials Securely**: Never hardcode API keys or access tokens in your source code. Use environment variables or secure credential storage.
+
+3. **Token Refresh**: Implement token refresh logic when using OAuth to handle token expiration.
+
+4. **Project Isolation**: Use ``project_id`` to ensure requests are scoped to the correct project, even when using API keys.
+
+5. **Error Handling**: Implement proper error handling for authentication failures:
+
+.. code-block:: python
+
+    from pygeai.core.common.exceptions import MissingRequirementException, APIResponseError
+    
+    try:
+        client = AILabClient(
+            base_url="https://api.saia.ai",
+            access_token=access_token,
+            project_id=project_id
+        )
+        agents = client.list_agents()
+    except MissingRequirementException as e:
+        print(f"Configuration error: {e}")
+    except APIResponseError as e:
+        print(f"Authentication failed: {e}")
+
+Related Resources
+-----------------
+
+- :doc:`quickstart` - Getting started with PyGEAI
+- :doc:`api_reference/auth` - Auth client API reference
+- :doc:`ai_lab` - AI Lab documentation

pygeai/_docs/source/content/cli.rst

@@ -1,8 +1,85 @@
-geai - cli examples
-===================
+geai - CLI Reference
+====================
 
 In this section, you can find examples of commands using the geai utility to perform basic tasks in GEAI.
 
+CLI Architecture
+----------------
+
+The PyGEAI CLI provides a comprehensive command-line interface with the following features:
+
+- **Type-Safe**: Full type hints for better IDE support and error detection
+- **Fuzzy Matching**: Suggests similar commands when typos are detected
+- **Enhanced Validation**: Detailed error messages with examples and suggestions
+- **Multi-Profile Support**: Manage multiple GEAI instances via ``--alias`` flag
+- **Consistent Error Handling**: Standardized exit codes and error formats
+- **Verbose Mode**: Detailed logging for debugging and troubleshooting
+
+Error Handling
+--------------
+
+The CLI provides clear, actionable error messages:
+
+Exit Codes
+^^^^^^^^^^
+
+- ``0``: Success
+- ``1``: User input error (invalid command, option, or argument)
+- ``2``: Missing required parameter
+- ``3``: Service error (API or agent issues)
+- ``130``: Keyboard interrupt (Ctrl+C)
+- ``255``: Unexpected error
+
+Error Message Format
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: text
+
+    ERROR: <error description>
+      → <suggestion for fixing>
+      
+      Example:
+        <example of correct usage>
+    
+    Run 'geai help' for usage information.
+
+Global Options
+--------------
+
+Verbose Mode
+^^^^^^^^^^^^
+
+Enable detailed logging output to debug issues or understand command execution flow:
+
+.. code-block:: shell
+
+    geai --verbose <command> [options]
+    geai -v <command> [options]
+
+Example output with verbose mode:
+
+.. code-block:: text
+
+    2026-01-13 09:45:04 - geai - DEBUG - Verbose mode enabled
+    2026-01-13 09:45:04 - geai - DEBUG - Running geai with: geai help
+    2026-01-13 09:45:04 - geai - DEBUG - Session: default
+    2026-01-13 09:45:04 - geai - DEBUG - Identifying command for argument: help
+    2026-01-13 09:45:04 - geai - DEBUG - Searching for command matching: help
+    2026-01-13 09:45:04 - geai - DEBUG - Command found: help (identifiers: ['help', 'h'])
+    2026-01-13 09:45:04 - geai - DEBUG - Command identified: help
+    2026-01-13 09:45:04 - geai - DEBUG - Processing command: help, arguments: []
+
+**When to use verbose mode:**
+
+- Troubleshooting configuration issues
+- Understanding which session/alias is being used
+- Debugging command parsing or option validation
+- Reporting issues to support with detailed context
+- Tracking API calls and responses
+
+Basic Usage
+-----------
+
 # Display help
 
 .. code-block:: shell

pygeai/_docs/source/content/debugger.rst

@@ -17,7 +17,7 @@ The debugger provides features similar to Python's built-in ``pdb`` debugger, in
 - **Command history**: Uses readline for command history and editing
 
 Installation and Setup
----------------------
+----------------------
 
 ``geai-dbg`` is included in the ``pygeai`` package. Ensure ``pygeai`` is installed in your Python environment:
 

pygeai/_docs/source/content/migration.rst

@@ -20,6 +20,7 @@ The migration feature supports migrating the following resource types:
 - **Usage Limits**: Resource usage constraints and quotas
 - **RAG Assistants**: Retrieval-Augmented Generation assistants
 - **Files**: Project files and attachments
+- **Secrets**: Secure credentials and sensitive configuration values
 
 Key Features
 ------------
@@ -77,6 +78,7 @@ Different migration operations require different API token scopes:
   - **Task Migration**: Migrating tasks
   - **RAG Assistant Migration**: Migrating RAG assistants
   - **File Migration**: Migrating files within projects
+  - **Secret Migration**: Migrating secrets within projects
 
 Migration Scenarios and Required Keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -129,7 +131,7 @@ This command will:
 
 1. Create a new project named "Cloned Project"
 2. Discover all resources in the source project
-3. Migrate all agents, tools, processes, tasks, usage limits, RAG assistants, and files
+3. Migrate all agents, tools, processes, tasks, usage limits, RAG assistants, files, and secrets
 4. Display progress and results
 
 Migrate to Different Instance
@@ -194,6 +196,18 @@ Instead of migrating everything, you can selectively migrate specific resource t
         --admin-email "admin@example.com" \\
         --rag-assistants all
 
+**Migrate all secrets only:**
+
+.. code-block:: shell
+
+    geai migrate clone-project \\
+        --from-api-key "source_api_key_123" \\
+        --from-project-id "source-project-id" \\
+        --from-instance "https://api.example.ai" \\
+        --to-project-name "Secrets Only" \\
+        --admin-email "admin@example.com" \\
+        --secrets all
+
 Migrate Specific Resources by ID
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -339,7 +353,7 @@ Command: ``geai migrate clone-project``
 **Migration Flags:**
 
 ``--all``
-  Migrate all available resource types (agents, tools, processes, tasks, usage limits, RAG assistants, files)
+  Migrate all available resource types (agents, tools, processes, tasks, usage limits, RAG assistants, files, secrets)
 
 ``--agents <all|id1,id2,...>``
   Migrate all agents or specific agents by ID (comma-separated)
@@ -362,6 +376,9 @@ Command: ``geai migrate clone-project``
 ``--files <all|id1,id2,...>``
   Migrate all files or specific files by ID (comma-separated)
 
+``--secrets <all|id1,id2,...>``
+  Migrate all secrets or specific secrets by ID (comma-separated)
+
 ``--stop-on-error <0|1>`` or ``--soe <0|1>``
   Control migration behavior on errors. Set to ``1`` (default) to stop migration on first error, or ``0`` to continue migrating remaining resources even if some fail
 

pygeai/_docs/source/index.rst

@@ -15,6 +15,7 @@ Getting Started
 
    content/intro
    content/quickstart
+   content/authentication
 
 Core Features & API Reference
 -------------------------------
@@ -52,6 +53,7 @@ Tools & Utilities
 .. toctree::
    :maxdepth: 2
 
+   content/migration
    content/cli
    content/chat_gui
    content/debugger

pygeai/_docs/source/pygeai.analytics.rst

@@ -0,0 +1,53 @@
+pygeai.analytics package
+========================
+
+Submodules
+----------
+
+pygeai.analytics.clients module
+-------------------------------
+
+.. automodule:: pygeai.analytics.clients
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.analytics.endpoints module
+---------------------------------
+
+.. automodule:: pygeai.analytics.endpoints
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.analytics.managers module
+--------------------------------
+
+.. automodule:: pygeai.analytics.managers
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.analytics.mappers module
+-------------------------------
+
+.. automodule:: pygeai.analytics.mappers
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.analytics.responses module
+---------------------------------
+
+.. automodule:: pygeai.analytics.responses
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: pygeai.analytics
+   :members:
+   :show-inheritance:
+   :undoc-members:

pygeai/_docs/source/pygeai.cli.commands.rst

@@ -21,6 +21,14 @@ pygeai.cli.commands.admin module
    :show-inheritance:
    :undoc-members:
 
+pygeai.cli.commands.analytics module
+------------------------------------
+
+.. automodule:: pygeai.cli.commands.analytics
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 pygeai.cli.commands.assistant module
 ------------------------------------
 

pygeai/_docs/source/pygeai.rst

@@ -8,6 +8,7 @@ Subpackages
    :maxdepth: 4
 
    pygeai.admin
+   pygeai.analytics
    pygeai.assistant
    pygeai.auth
    pygeai.chat

pygeai/_docs/source/pygeai.tests.analytics.rst

@@ -0,0 +1,45 @@
+pygeai.tests.analytics package
+==============================
+
+Submodules
+----------
+
+pygeai.tests.analytics.test\_clients module
+-------------------------------------------
+
+.. automodule:: pygeai.tests.analytics.test_clients
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.tests.analytics.test\_managers module
+--------------------------------------------
+
+.. automodule:: pygeai.tests.analytics.test_managers
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.tests.analytics.test\_mappers module
+-------------------------------------------
+
+.. automodule:: pygeai.tests.analytics.test_mappers
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.tests.analytics.test\_responses module
+---------------------------------------------
+
+.. automodule:: pygeai.tests.analytics.test_responses
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: pygeai.tests.analytics
+   :members:
+   :show-inheritance:
+   :undoc-members:

pygeai/_docs/source/pygeai.tests.auth.rst

@@ -12,6 +12,14 @@ pygeai.tests.auth.test\_clients module
    :show-inheritance:
    :undoc-members:
 
+pygeai.tests.auth.test\_oauth module
+------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_oauth
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 Module contents
 ---------------
 

pygeai/_docs/source/pygeai.tests.rst

@@ -8,6 +8,7 @@ Subpackages
    :maxdepth: 4
 
    pygeai.tests.admin
+   pygeai.tests.analytics
    pygeai.tests.assistants
    pygeai.tests.auth
    pygeai.tests.chat
@@ -22,7 +23,6 @@ Subpackages
    pygeai.tests.migration
    pygeai.tests.organization
    pygeai.tests.proxy
-   pygeai.tests.snippets
 
 Module contents
 ---------------