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

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

@@ -0,0 +1,379 @@
+Authentication & Token Management
+==================================
+
+The GEAI SDK provides functionality to manage authentication and API tokens for Globant Enterprise AI. This includes OAuth2 authentication, user profile retrieval, and project API token management through the command line interface and the low-level service layer (AuthClient).
+
+OAuth2 Access Token
+~~~~~~~~~~~~~~~~~~~
+
+Retrieves an OAuth2 access token for authentication with Globant Enterprise AI. This token is required for accessing user profile information and other authenticated endpoints.
+
+Command Line
+^^^^^^^^^^^^
+
+The `geai auth get-access-token` command retrieves an OAuth2 access token using client credentials and user authentication.
+
+.. code-block:: shell
+
+    geai auth get-access-token \
+      --client-id "your-client-id" \
+      --username "user@example.com" \
+      --password "your-password" \
+      --scope "gam_user_data gam_user_roles"
+
+Using short form aliases:
+
+.. code-block:: shell
+
+    geai auth gat \
+      --cid "your-client-id" \
+      -u "user@example.com" \
+      -p "your-password" \
+      -s "gam_user_data gam_user_roles"
+
+Low Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `AuthClient` class provides a low-level interface to obtain OAuth2 access tokens.
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.get_oauth2_access_token(
+        client_id="your-client-id",
+        username="user@example.com",
+        password="your-password",
+        scope="gam_user_data gam_user_roles"
+    )
+    print(response)
+
+User Profile Information
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieves user profile information using an OAuth2 access token obtained from the previous endpoint.
+
+Command Line
+^^^^^^^^^^^^
+
+The `geai auth get-user-info` command retrieves the current user's profile information.
+
+.. code-block:: shell
+
+    geai auth get-user-info \
+      --access-token "your-access-token"
+
+Using short form aliases:
+
+.. code-block:: shell
+
+    geai auth gui \
+      --token "your-access-token"
+
+Low Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `AuthClient` class provides a low-level interface to retrieve user profile information.
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.get_user_profile_information(
+        access_token="your-access-token"
+    )
+    print(response)
+
+Create Project API Token
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates a new API token for a specific project. This operation requires organization-level or GAM authentication.
+
+Command Line
+^^^^^^^^^^^^
+
+The `geai auth create-project-api-token` command creates a new API token for a project.
+
+.. code-block:: shell
+
+    geai auth create-project-api-token \
+      --project-id "2ca6883f-6778-40bb-bcc1-85451fb11107" \
+      --name "MyAPIToken" \
+      --description "API token for production environment"
+
+Creating a token without description (minimal):
+
+.. code-block:: shell
+
+    geai auth create-api-token \
+      --pid "2ca6883f-6778-40bb-bcc1-85451fb11107" \
+      --name "TestToken"
+
+Using the shortest alias:
+
+.. code-block:: shell
+
+    geai auth cat \
+      --pid "2ca6883f-6778-40bb-bcc1-85451fb11107" \
+      -n "TestToken" \
+      -d "Optional description"
+
+Low Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `AuthClient` class provides a low-level interface to create project API tokens.
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.create_project_api_token(
+        project_id="2ca6883f-6778-40bb-bcc1-85451fb11107",
+        name="MyAPIToken",
+        description="API token for production environment"
+    )
+    print(response)
+
+Without description (optional parameter):
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.create_project_api_token(
+        project_id="2ca6883f-6778-40bb-bcc1-85451fb11107",
+        name="MyAPIToken"
+    )
+    print(response)
+
+Get Project API Token
+~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieves detailed information about a specific project API token.
+
+Command Line
+^^^^^^^^^^^^
+
+The `geai auth get-project-api-token` command retrieves details of a specific API token.
+
+.. code-block:: shell
+
+    geai auth get-project-api-token \
+      --api-token-id "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+
+Using short form aliases:
+
+.. code-block:: shell
+
+    geai auth get-api-token \
+      --tid "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+
+Using the shortest alias:
+
+.. code-block:: shell
+
+    geai auth gat \
+      --tid "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+
+Low Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `AuthClient` class provides a low-level interface to retrieve project API token details.
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.get_project_api_token(
+        api_token_id="default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+    )
+    print(response)
+
+Update Project API Token
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Updates an existing API token's description and/or status. Status can be set to 'active' or 'blocked'.
+
+Command Line
+^^^^^^^^^^^^
+
+The `geai auth update-project-api-token` command updates an existing API token.
+
+Update description only:
+
+.. code-block:: shell
+
+    geai auth update-project-api-token \
+      --api-token-id "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY" \
+      --description "Updated description for API token"
+
+Update status to blocked:
+
+.. code-block:: shell
+
+    geai auth update-api-token \
+      --tid "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY" \
+      --status "blocked"
+
+Update status to active:
+
+.. code-block:: shell
+
+    geai auth uat \
+      --tid "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY" \
+      --status "active"
+
+Update both description and status:
+
+.. code-block:: shell
+
+    geai auth update-api-token \
+      --api-token-id "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY" \
+      --description "Production API token" \
+      --status "active"
+
+Low Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `AuthClient` class provides a low-level interface to update project API tokens.
+
+Update description:
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.update_project_api_token(
+        api_token_id="default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY",
+        description="Updated description for API token"
+    )
+    print(response)
+
+Update status:
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.update_project_api_token(
+        api_token_id="default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY",
+        status="blocked"
+    )
+    print(response)
+
+Update both description and status:
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.update_project_api_token(
+        api_token_id="default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY",
+        description="Production API token",
+        status="active"
+    )
+    print(response)
+
+Delete Project API Token
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Revokes an API token by setting its status to "revoked". Deleted tokens cannot be updated or reactivated.
+
+Command Line
+^^^^^^^^^^^^
+
+The `geai auth delete-project-api-token` command deletes/revokes an API token.
+
+.. code-block:: shell
+
+    geai auth delete-project-api-token \
+      --api-token-id "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+
+Using short form aliases:
+
+.. code-block:: shell
+
+    geai auth delete-api-token \
+      --tid "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+
+Using the shortest alias:
+
+.. code-block:: shell
+
+    geai auth dat \
+      --tid "default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+
+Low Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `AuthClient` class provides a low-level interface to delete project API tokens.
+
+.. code-block:: python
+
+    from pygeai.auth.clients import AuthClient
+
+    client = AuthClient()
+
+    response = client.delete_project_api_token(
+        api_token_id="default_rnLl2eCuOuXJ_e8y8pXLMCnp1p4WcNu0I_-9mtD-AzY"
+    )
+    print(response)
+
+Command Aliases Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following command aliases are available for convenience:
+
+==========================  ================================================================
+Command                     Aliases
+==========================  ================================================================
+get-access-token            gat
+get-user-information        get-user-info, gui
+create-project-api-token    create-api-token, cat
+delete-project-api-token    delete-api-token, dat
+update-project-api-token    update-api-token, uat
+get-project-api-token       get-api-token, gat
+==========================  ================================================================
+
+Option Aliases Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following option aliases are available for convenience:
+
+==========================  ================================================================
+Option                      Aliases
+==========================  ================================================================
+--project-id                --pid
+--api-token-id              --tid
+--name                      -n
+--description               -d
+--access-token              --token
+--client-id                 --cid
+--username                  -u
+--password                  -p
+--scope                     -s
+==========================  ================================================================
+
+Security Notes
+~~~~~~~~~~~~~~
+
+* API tokens must be managed using organization-level API tokens or GAM tokens
+* Project API tokens cannot manage other API tokens
+* Deleted tokens cannot be updated or reactivated
+* Status values: 'active' (token can be used) or 'blocked' (token cannot be used)

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

@@ -0,0 +1,58 @@
+Health & Status
+===============
+
+The Health module provides functionality to check the operational status of Globant Enterprise AI services and endpoints.
+
+This section covers:
+
+* Checking API health status
+* Verifying service availability
+
+For each operation, you have two implementation options:
+
+* `Command Line`_
+* `Low-Level Service Layer`_
+
+.. note::
+   The Health module currently does not have a High-Level Service Layer (Manager class).
+
+
+Check API Status
+~~~~~~~~~~~~~~~~
+
+Checks the health and availability of the Globant Enterprise AI API.
+
+Command Line
+^^^^^^^^^^^^
+
+.. code-block:: shell
+
+    geai status
+
+Or using the alias:
+
+.. code-block:: shell
+
+    geai s
+
+Low-Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    from pygeai.health.clients import HealthClient
+
+    client = HealthClient()
+    
+    status = client.get_health()
+    print(status)
+
+Example response:
+
+.. code-block:: json
+
+    {
+        "status": "healthy",
+        "version": "1.0.0",
+        "timestamp": "2026-01-06T12:00:00Z"
+    }

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

@@ -68,7 +68,7 @@ Use the following code snippet to list projects with the desired detail level:
 
 .. code-block:: python
 
-    from pygeai.organization.clients import OrganizationClient()
+    from pygeai.organization.clients import OrganizationClient
 
     client = OrganizationClient()
     project_list = client.get_project_list(detail="full")  # Use "summary" for less detail
@@ -156,7 +156,7 @@ For more control, you can use the low-level service layer. To do so:
 
 .. code-block:: python
 
-    from pygeai.organization.clients import OrganizationClient()
+    from pygeai.organization.clients import OrganizationClient
 
     name="Project Name"
     description="Project Description"
@@ -181,13 +181,13 @@ The high-level service layer offers a more structured approach:
 .. code-block:: python
 
     from pygeai.organization.managers import OrganizationManager
-    from pygeai.core.models import ProjectUsageLimit, Project
+    from pygeai.core.models import UsageLimit, Project
 
     manager = OrganizationManager()
 
-    usage_limit = ProjectUsageLimit(
+    usage_limit = UsageLimit(
         subscription_type="Monthly",  # Options: Freemium, Daily, Weekly, Monthly
-        usage_unit="Requests",        # Options: Cost (Only Cost is allowed for organization limits)
+        usage_unit="Requests",        # Options: Requests, Cost
         soft_limit=500.0,             # Recommended usage limit
         hard_limit=1000.0,            # Maximum allowed usage
         renewal_status="Renewable"    # Options: Renewable, NonRenewable
@@ -253,9 +253,9 @@ Use the following code snippet to update a project using the low-level service l
 
 .. code-block:: python
 
-    from pygeai.organization.clients import OrganizationClient()
+    from pygeai.organization.clients import OrganizationClient
 
-    project_id="<project_id>"
+    project_iid="<project_id>"
     name="<new_project_name>"
     description="<new_project_description>"
 
@@ -284,7 +284,7 @@ Use the following code snippet to update a project using the high-level service
     client = OrganizationManager()
 
     project = Project(
-        d="<project_id>",
+        id="<project_id>",
         name="<new_project_name>",
         description="<new_project_description>",
     )
@@ -335,7 +335,7 @@ Use the following code snippet to delete a project using the low-level service l
 
 .. code-block:: python
 
-    from pygeai.organization.clients import OrganizationClient()
+    from pygeai.organization.clients import OrganizationClient
 
     project_id = "<project_id>"
     client = OrganizationClient()
@@ -346,11 +346,13 @@ Replace <`project_id`> with the actual project Id. For example:
 
 .. code-block:: python
 
-    from pygeai.organization.clients import OrganizationClient()
+    from pygeai.organization.clients import OrganizationClient
 
     project_id="12345678-90ab-cdef-1234-567890abcdef"
     client = OrganizationClient()
-    deleted_project = client.delete_project(
+    deleted_project = client.delete_project(project_id=project_id)
+    print(deleted_project)
+
 
 High level service layer
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -370,7 +372,7 @@ Replace <`project_id`> with the actual project Id. For example:
 
 .. code-block:: python
 
-    from pygeai.core.managers import OrganizationManager
+    from pygeai.organization.managers import OrganizationManager
 
     manager = OrganizationManager()
     response = manager.delete_project("12345678-90ab-cdef-1234-567890abcdef")
@@ -415,9 +417,9 @@ Use the following code snippet to retrieve project data using the low-level serv
 
 .. code-block:: python
 
-    from pygeai.organization.clients import OrganizationClient()
+    from pygeai.organization.clients import OrganizationClient
 
-    project_id="<project_id>"
+    project_iid="<project_id>"
     client = OrganizationClient()
     project_data = client.get_project_data(project_id=project_id)
     print(project_data)
@@ -427,7 +429,7 @@ Replace `<project_id>` with the actual project Id. For example:
 
 .. code-block:: python
 
-    from pygeai.organization.clients import OrganizationClient()
+    from pygeai.organization.clients import OrganizationClient
 
     project_id="12345678-90ab-cdef-1234-567890abcdef"
     client = OrganizationClient()
@@ -447,7 +449,7 @@ Use the following code snippet to retrieve project data using the high-level ser
 
     manager = OrganizationManager(alias="sdkorg")
 
-    project = manager.get_project_data(project_id="<project_id>")
+    project = manager.get_project_data(project_iid="<project_id>")
     print(f"project: {project}")
 
 
@@ -455,7 +457,7 @@ Replace `<project_id>` with the actual project Id. For example:
 
 .. code-block:: python
 
-    from pygeai.core.managers import OrganizationManager
+    from pygeai.organization.managers import OrganizationManager
 
     manager = OrganizationManager(alias="sdkorg")
     project = manager.get_project_data(project_id="12345678-90ab-cdef-1234-567890abcdef")
@@ -528,7 +530,7 @@ Use the following code snippet to retrieve project tokens using the high-level s
 
 .. code-block:: python
 
-    from pygeai.core.managers import OrganizationManager
+    from pygeai.organization.managers import OrganizationManager
     from pygeai.core.base.models import ProjectTokensResponse
 
     client = OrganizationManager()

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

@@ -0,0 +1,94 @@
+Reranking
+=========
+
+The Rerank module provides functionality to reorder document chunks based on their relevance to a query. This is particularly useful in retrieval-augmented generation (RAG) systems to prioritize the most relevant context.
+
+This section covers:
+
+* Reranking document chunks based on relevance
+* Selecting top-N most relevant documents
+
+For each operation, you have two implementation options:
+
+* `Command Line`_
+* `Low-Level Service Layer`_
+
+.. note::
+   The Rerank module currently does not have a High-Level Service Layer (Manager class).
+
+
+Rerank Chunks
+~~~~~~~~~~~~~
+
+Reranks a list of document chunks based on their relevance to a given query.
+
+Command Line
+^^^^^^^^^^^^
+
+.. code-block:: shell
+
+    geai rerank rerank-chunks \
+      --query "What is machine learning?" \
+      --documents '["Machine learning is a subset of AI", "Python is a programming language", "Deep learning uses neural networks"]' \
+      --model "cohere/rerank-english-v3.0" \
+      --top-n 2
+
+Using the alias:
+
+.. code-block:: shell
+
+    geai rerank chunks \
+      -q "What is machine learning?" \
+      -d "Machine learning is a subset of AI" \
+      --top-n 2
+
+Low-Level Service Layer
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    from pygeai.core.rerank.clients import RerankClient
+
+    client = RerankClient()
+    
+    query = "What is machine learning?"
+    documents = [
+        "Machine learning is a subset of AI",
+        "Python is a programming language",
+        "Deep learning uses neural networks"
+    ]
+    
+    results = client.rerank_chunks(
+        query=query,
+        documents=documents,
+        model="cohere/rerank-english-v3.0",
+        top_n=2
+    )
+    print(results)
+
+Example response:
+
+.. code-block:: json
+
+    {
+        "results": [
+            {
+                "index": 0,
+                "document": "Machine learning is a subset of AI",
+                "relevance_score": 0.95
+            },
+            {
+                "index": 2,
+                "document": "Deep learning uses neural networks",
+                "relevance_score": 0.72
+            }
+        ]
+    }
+
+Parameters
+^^^^^^^^^^
+
+* **query** (required): The search query to rank documents against
+* **documents** (required): List of document strings to rerank
+* **model** (optional): The reranking model to use (default: "cohere/rerank-english-v3.0")
+* **top_n** (optional): Number of top results to return (default: returns all)

pygeai/_docs/source/content/api_reference.rst

@@ -7,10 +7,15 @@ This document provides a comprehensive overview of **API Reference**, outlining
     :maxdepth: 2
     :caption: Contents:
 
+    api_reference/auth
+    api_reference/admin
+    api_reference/assistant
     api_reference/chat
+    api_reference/embeddings
+    api_reference/health
     api_reference/project
     api_reference/rag
-    api_reference/embeddings
+    api_reference/rerank
 
 
 Authentication