pygeai 0.6.0b13__py3-none-any.whl → 0.6.1__py3-none-any.whl

pygeai/__init__.py

@@ -1,10 +1,9 @@
 import logging
-import os
 import sys
 from pathlib import Path
 
 __author__ = 'Globant'
-__version__ = '0.6.0'
+__version__ = '0.6.1'
 
 # Add vendor directory to Python path
 package_root = Path(__file__).parent

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

@@ -736,3 +736,395 @@ Replace `<project_id>` with the actual project Id. For example:
 
     tokens: ProjectTokensResponse = client.get_project_tokens(project_id=project_id)
     print(f"tokens: {tokens}")
+
+
+Access Control
+==============
+The Access Control API provides tools to manage memberships, roles, and members across organizations and projects.
+
+* Get Memberships: Retrieves organizations where you are a member.
+* Get Project Memberships: Retrieves projects where a user is a member.
+* Get Project Roles: Retrieves all roles supported by a specific project.
+* Get Project Members: Retrieves all members and their roles for a specific project.
+* Get Organization Members: Retrieves all members and their roles for a specific organization.
+* Get Plugin Runtime Policies: Retrieves plugin runtime policies defined for an organization.
+
+Get Memberships
+~~~~~~~~~~~~~~~
+
+Retrieves all organizations where you are a member using `PyGEA </pygeai>`_. Supports pagination and filtering options.
+
+To achieve this, you have two 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>`_
+
+Command line
+^^^^^^^^^^^^
+
+Use the following command to retrieve your organization memberships:
+
+.. code-block:: shell
+
+    geai org get-memberships
+
+With optional pagination parameters:
+
+.. code-block:: shell
+
+    geai org get-memberships \
+      --start-page 1 \
+      --page-size 10 \
+      --order-direction asc
+
+Low level service layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to retrieve memberships:
+
+.. code-block:: python
+
+    from pygeai.organization.clients import OrganizationClient
+
+    client = OrganizationClient()
+    result = client.get_memberships(
+        start_page=1,
+        page_size=10,
+        order_direction="asc"
+    )
+    print(result)
+
+
+Get Project Memberships
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieves projects where a specific user is a member using `PyGEA </pygeai>`_. Supports pagination, sorting, and filtering by email.
+
+To achieve this, you have two 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>`_
+
+Command line
+^^^^^^^^^^^^
+
+Use the following command to retrieve project memberships for a specific user:
+
+.. code-block:: shell
+
+    geai org get-project-memberships \
+      --email user@example.com \
+      --start-page 1 \
+      --page-size 10
+
+With optional sorting and filtering:
+
+.. code-block:: shell
+
+    geai org get-project-memberships \
+      --email user@example.com \
+      --start-page 1 \
+      --page-size 10 \
+      --order-key name \
+      --order-direction desc \
+      --role-types backend,frontend
+
+Where:
+
+* `--email`: User email address to filter by (required).
+* `--start-page`: Page number for pagination (optional, default: 1).
+* `--page-size`: Number of items per page (optional, default: 20).
+* `--order-key`: Field for sorting (only 'name' supported, optional).
+* `--order-direction`: Sort direction: 'asc' or 'desc' (optional, default: 'desc').
+* `--role-types`: Comma-separated list of role types (optional, case-insensitive).
+
+Low level service layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to retrieve project memberships:
+
+.. code-block:: python
+
+    from pygeai.organization.clients import OrganizationClient
+
+    client = OrganizationClient()
+    result = client.get_project_memberships(
+        email="user@example.com",
+        start_page=1,
+        page_size=10,
+        order_key="name",
+        order_direction="desc",
+        role_types="backend,frontend"
+    )
+    print(result)
+
+
+Get Project Roles
+~~~~~~~~~~~~~~~~~
+
+Retrieves all roles supported by a specific project using `PyGEA </pygeai>`_. Supports pagination, sorting, and filtering by role types.
+
+To achieve this, you have two 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>`_
+
+Command line
+^^^^^^^^^^^^
+
+Use the following command to retrieve project roles:
+
+.. code-block:: shell
+
+    geai org get-project-roles \
+      --project-id <project_id>
+
+With optional pagination and filtering:
+
+.. code-block:: shell
+
+    geai org get-project-roles \
+      --project-id 12345678-90ab-cdef-1234-567890abcdef \
+      --start-page 1 \
+      --page-size 10 \
+      --order-key name \
+      --order-direction asc \
+      --role-types backend
+
+Where:
+
+* `--project-id`: The unique identifier (GUID) of the project (required).
+* `--start-page`: Page number for pagination (optional, default: 1).
+* `--page-size`: Number of items per page (optional, default: 20).
+* `--order-key`: Field for sorting (only 'name' supported, optional).
+* `--order-direction`: Sort direction: 'asc' or 'desc' (optional, default: 'desc').
+* `--role-types`: Comma-separated list of role types: 'backend', 'frontend' (optional, case-insensitive).
+
+Low level service layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to retrieve project roles:
+
+.. code-block:: python
+
+    from pygeai.organization.clients import OrganizationClient
+
+    project_id = "12345678-90ab-cdef-1234-567890abcdef"
+
+    client = OrganizationClient()
+    result = client.get_project_roles(
+        project_id=project_id,
+        start_page=1,
+        page_size=10,
+        order_key="name",
+        order_direction="asc",
+        role_types="backend"
+    )
+    print(result)
+
+
+Get Project Members
+~~~~~~~~~~~~~~~~~~~
+
+Retrieves all members and their roles for a specific project using `PyGEA </pygeai>`_. Supports pagination, sorting, and filtering by role types.
+
+To achieve this, you have two 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>`_
+
+Command line
+^^^^^^^^^^^^
+
+Use the following command to retrieve project members:
+
+.. code-block:: shell
+
+    geai org get-project-members \
+      --project-id <project_id>
+
+With optional pagination and filtering:
+
+.. code-block:: shell
+
+    geai org get-project-members \
+      --project-id 12345678-90ab-cdef-1234-567890abcdef \
+      --start-page 1 \
+      --page-size 10 \
+      --order-key name \
+      --order-direction desc \
+      --role-types backend,frontend
+
+Where:
+
+* `--project-id`: The unique identifier (GUID) of the project (required).
+* `--start-page`: Page number for pagination (optional, default: 1).
+* `--page-size`: Number of items per page (optional, default: 20).
+* `--order-key`: Field for sorting (only 'name' supported, optional).
+* `--order-direction`: Sort direction: 'asc' or 'desc' (optional, default: 'desc').
+* `--role-types`: Comma-separated list of role types: 'backend', 'frontend' (optional, case-insensitive).
+
+Low level service layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to retrieve project members:
+
+.. code-block:: python
+
+    from pygeai.organization.clients import OrganizationClient
+
+    project_id = "12345678-90ab-cdef-1234-567890abcdef"
+
+    client = OrganizationClient()
+    result = client.get_project_members(
+        project_id=project_id,
+        start_page=1,
+        page_size=10,
+        order_key="name",
+        order_direction="desc",
+        role_types="backend,frontend"
+    )
+    print(result)
+
+
+Get Organization Members
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieves all members and their roles for a specific organization using `PyGEA </pygeai>`_. Supports pagination, sorting, and filtering by role types.
+
+To achieve this, you have two 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>`_
+
+Command line
+^^^^^^^^^^^^
+
+Use the following command to retrieve organization members:
+
+.. code-block:: shell
+
+    geai org get-organization-members \
+      --organization-id <organization_id>
+
+With optional pagination and filtering:
+
+.. code-block:: shell
+
+    geai org get-organization-members \
+      --organization-id 12345678-90ab-cdef-1234-567890abcdef \
+      --start-page 1 \
+      --page-size 10 \
+      --order-key email \
+      --order-direction asc \
+      --role-types backend
+
+Where:
+
+* `--organization-id` or `--oid`: The unique identifier (GUID) of the organization (required).
+* `--start-page`: Page number for pagination (optional, default: 1).
+* `--page-size`: Number of items per page (optional, default: 20).
+* `--order-key`: Field for sorting (only 'email' supported, optional).
+* `--order-direction`: Sort direction: 'asc' or 'desc' (optional, default: 'desc').
+* `--role-types`: Comma-separated list of role types. Only 'backend' is supported for organizations (optional, case-insensitive).
+
+Low level service layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to retrieve organization members:
+
+.. code-block:: python
+
+    from pygeai.organization.clients import OrganizationClient
+
+    organization_id = "12345678-90ab-cdef-1234-567890abcdef"
+
+    client = OrganizationClient()
+    result = client.get_organization_members(
+        organization_id=organization_id,
+        start_page=1,
+        page_size=10,
+        order_key="email",
+        order_direction="asc",
+        role_types="backend"
+    )
+    print(result)
+
+
+Get Plugin Runtime Policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieves the plugin runtime policies defined for a given organization using `PyGEA </pygeai>`_. If no policies are defined, the response indicates that individual policies will apply.
+
+Plugin runtime policies control permissions for organization agents at The Station, including chat sharing and external execution permissions.
+
+To achieve this, you have two 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>`_
+
+Command line
+^^^^^^^^^^^^
+
+Use the following command to retrieve plugin runtime policies:
+
+.. code-block:: shell
+
+    geai org get-plugin-runtime-policies \
+      --organization-id <organization_id>
+
+Replace `<organization_id>` with the actual organization GUID. For example:
+
+.. code-block:: shell
+
+    geai org get-plugin-runtime-policies \
+      --organization-id 12345678-90ab-cdef-1234-567890abcdef
+
+You can also use the short alias:
+
+.. code-block:: shell
+
+    geai org get-plugin-runtime-policies --oid 12345678-90ab-cdef-1234-567890abcdef
+
+**Response Examples:**
+
+1. **Organizations without policies:**
+
+   .. code-block:: json
+
+       {
+         "messages": {
+           "description": "Organization plugin runtime policies not defined. Individual policy will apply."
+         }
+       }
+
+2. **Organizations with policies:**
+
+   .. code-block:: json
+
+       {
+         "policies": {
+           "chatSharingPermissions": "project",
+           "externalExecutionPermissions": "organization"
+         }
+       }
+
+   Where:
+
+   - `chatSharingPermissions`: Maximum execution permissions for organization Agents. Values: "none", "project", "organization".
+   - `externalExecutionPermissions`: Allows sharing conversation by anonymous users. Values: "none", "project", "organization".
+
+Low level service layer
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following code snippet to retrieve plugin runtime policies:
+
+.. code-block:: python
+
+    from pygeai.organization.clients import OrganizationClient
+
+    organization_id = "12345678-90ab-cdef-1234-567890abcdef"
+
+    client = OrganizationClient()
+    result = client.get_plugin_runtime_policies(organization_id=organization_id)
+    print(result)

pygeai/_docs/source/content/authentication.rst

@@ -27,6 +27,8 @@ When prompted, enter your API key and base URL:
     -> Insert your GEAI API BASE URL: https://api.saia.ai
     GEAI API BASE URL for alias 'default' saved successfully!
 
+The ``geai configure`` command creates or updates the credentials file at ``~/.geai/credentials`` with the specified alias profile.
+
 Usage in Code
 ~~~~~~~~~~~~~
 
@@ -258,6 +260,127 @@ The SDK validates authentication parameters:
         project_id="project-123"
     )
 
+Advanced Features
+-----------------
+
+Mixed Authentication
+~~~~~~~~~~~~~~~~~~~~
+
+The SDK supports using both API Key and OAuth 2.0 authentication simultaneously through the ``allow_mixed_auth`` parameter. When both are provided, OAuth takes precedence.
+
+.. code-block:: python
+
+    from pygeai.lab.clients import AILabClient
+    
+    client = AILabClient(
+        api_key="your_api_key",
+        base_url="https://api.saia.ai",
+        access_token="your_oauth_token",
+        project_id="your-project-id",
+        allow_mixed_auth=True  # Required when providing both
+    )
+    # OAuth authentication will be used (takes precedence)
+
+**Validation:**
+
+- If both ``api_key`` and ``access_token`` are provided without ``allow_mixed_auth=True``, a ``MixedAuthenticationException`` is raised.
+- When mixed auth is allowed, OAuth 2.0 (``access_token``) takes precedence over the API key.
+
+Organization ID
+~~~~~~~~~~~~~~~
+
+The optional ``organization_id`` parameter provides organization-level context for API requests:
+
+.. code-block:: python
+
+    client = AILabClient(
+        base_url="https://api.saia.ai",
+        access_token="your_oauth_token",
+        project_id="your-project-id",
+        organization_id="your-org-id"
+    )
+
+When provided, the SDK automatically includes the ``OrganizationId`` header in API requests.
+
+Environment Variables
+~~~~~~~~~~~~~~~~~~~~~
+
+All authentication parameters can be configured via environment variables:
+
+**API Key Authentication:**
+
+- ``GEAI_API_KEY`` - Your API key
+- ``GEAI_API_BASE_URL`` - Base URL for the API
+- ``GEAI_PROJECT_ID`` - (Optional) Project ID
+
+**OAuth 2.0 Authentication:**
+
+- ``GEAI_OAUTH_ACCESS_TOKEN`` - Your OAuth 2.0 access token
+- ``GEAI_PROJECT_ID`` - Your project ID (required with OAuth)
+- ``GEAI_API_BASE_URL`` - Base URL for the API
+- ``GEAI_ORGANIZATION_ID`` - (Optional) Organization ID
+
+**Example:**
+
+.. code-block:: shell
+
+    export GEAI_OAUTH_ACCESS_TOKEN="your_oauth_token"
+    export GEAI_PROJECT_ID="your-project-id"
+    export GEAI_API_BASE_URL="https://api.saia.ai"
+    export GEAI_ORGANIZATION_ID="your-org-id"
+
+Session Utilities
+~~~~~~~~~~~~~~~~~
+
+The SDK provides utility methods to inspect the current authentication state:
+
+.. code-block:: python
+
+    from pygeai.core.base.session import get_session
+    from pygeai.core.common.constants import AuthType
+    
+    session = get_session()
+    
+    # Check authentication type
+    if session.is_oauth():
+        print("Using OAuth 2.0 authentication")
+        print(f"Project ID: {session.project_id}")
+    elif session.is_api_key():
+        print("Using API Key authentication")
+    
+    # Get the active token
+    active_token = session.get_active_token()
+    
+    # Check auth type enum
+    if session.auth_type == AuthType.OAUTH_TOKEN:
+        print("OAuth authentication active")
+    elif session.auth_type == AuthType.API_KEY:
+        print("API Key authentication active")
+    elif session.auth_type == AuthType.NONE:
+        print("No authentication configured")
+
+Warning Behaviors
+~~~~~~~~~~~~~~~~~
+
+The SDK provides helpful warnings in the following scenarios:
+
+1. **Project ID without OAuth token**: If ``project_id`` is provided without ``access_token``, a ``UserWarning`` is issued since project_id is only used with OAuth 2.0.
+
+2. **No authentication configured**: If neither ``api_key`` nor ``access_token`` is provided, a warning is logged.
+
+3. **Missing base URL**: If ``base_url`` is not configured, a warning is logged.
+
+4. **Mixed authentication in config**: When loading credentials from a config file that contains both API key and OAuth parameters, a warning is logged indicating OAuth will take precedence.
+
+Exception Reference
+~~~~~~~~~~~~~~~~~~~
+
+The SDK raises specific exceptions for authentication errors:
+
+- ``MissingRequirementException``: Raised when OAuth ``access_token`` is provided without required ``project_id``.
+- ``MixedAuthenticationException``: Raised when both ``api_key`` and ``access_token`` are provided without ``allow_mixed_auth=True``.
+- ``APIResponseError``: Raised for API-level authentication failures (invalid tokens, expired tokens, etc.).
+
 Best Practices
 --------------
 
@@ -273,7 +396,11 @@ Best Practices
 
 .. code-block:: python
 
-    from pygeai.core.common.exceptions import MissingRequirementException, APIResponseError
+    from pygeai.core.common.exceptions import (
+        MissingRequirementException, 
+        MixedAuthenticationException,
+        APIResponseError
+    )
     
     try:
         client = AILabClient(
@@ -284,6 +411,8 @@ Best Practices
         agents = client.list_agents()
     except MissingRequirementException as e:
         print(f"Configuration error: {e}")
+    except MixedAuthenticationException as e:
+        print(f"Mixed authentication error: {e}")
     except APIResponseError as e:
         print(f"Authentication failed: {e}")