pygeai 0.5.0__py3-none-any.whl → 0.6.0b3__py3-none-any.whl

pygeai/__init__.py

@@ -4,7 +4,7 @@ import sys
 from pathlib import Path
 
 __author__ = 'Globant'
-__version__ = '0.5.0'
+__version__ = '0.6.0'
 
 # Add vendor directory to Python path
 package_root = Path(__file__).parent

pygeai/auth/clients.py

@@ -0,0 +1,55 @@
+from json import JSONDecodeError
+
+from pygeai import logger
+from pygeai.auth.endpoints import GET_USER_PROFILE_INFO, GET_OAUTH2_ACCESS_TOKEN
+from pygeai.core.base.clients import BaseClient
+from pygeai.core.common.exceptions import InvalidAPIResponseException
+
+
+class AuthClient(BaseClient):
+
+    def get_oauth2_access_token(
+            self,
+            client_id: str,
+            username: str,
+            password: str,
+            scope: str = "gam_user_data gam_user_roles"
+    ) -> dict:
+        """
+        Retrieves the list of projects that the user is authorized to access within a specific organization.
+
+        :param client_id: str - The client identifier provided by Globant
+        :param username: str - Username for authentication
+        :param password: str - Password for authentication
+        :param scope: str - Space-separated list of requested scopes
+        :return: dict - The API response containing the list of authorized projects in JSON format.
+        """
+        response = self.api_service.get(
+            endpoint=GET_OAUTH2_ACCESS_TOKEN,
+            params={
+                "client_id": client_id,
+                "scope": scope,
+                "username": username,
+                "password": password
+            }
+        )
+        try:
+            return response.json()
+        except JSONDecodeError as e:
+            logger.error(f"Unable to obtain Oauth2 access token: JSON parsing error (status {response.status_code}): {e}. Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to  obtain Oauth2 access token: {response.text}")
+
+    def get_user_profile_information(self, access_token: str) -> dict:
+        """
+        Get user profile information
+
+        :param access_token: str - Token obtained in the POST to /oauth/access_token
+        :return: dict - The API response containing the user profile information
+        """
+        self.api_service.token = access_token
+        response = self.api_service.get(endpoint=GET_USER_PROFILE_INFO)
+        try:
+            return response.json()
+        except JSONDecodeError as e:
+            logger.error(f"Unable to retrieve user profile information: JSON parsing error (status {response.status_code}): {e}. Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to retrieve user profile information: {response.text}")

pygeai/auth/endpoints.py

@@ -0,0 +1,2 @@
+GET_OAUTH2_ACCESS_TOKEN = "/oauth/access_token"      # POST -> Obtain an OAuth 2.0 access token
+GET_USER_PROFILE_INFO = "/openid/userinfo"          # GET -> Retrieve user profile information

pygeai/cli/__init__.py

@@ -4,5 +4,4 @@ GEAI - ClI
 Command line interface to interact with Globant Enterprise AI.
 """
 
-__version__ = '0.5.0'
 

pygeai/cli/commands/auth.py

@@ -0,0 +1,123 @@
+from pygeai.auth.clients import AuthClient
+from pygeai.cli.commands import Command, Option, ArgumentsEnum
+from pygeai.cli.commands.builders import build_help_text
+from pygeai.cli.texts.help import AUTH_HELP_TEXT
+from pygeai.core.common.exceptions import MissingRequirementException, WrongArgumentError
+from pygeai.core.utils.console import Console
+
+
+def show_help():
+    """
+    Displays help text in stdout
+    """
+    help_text = build_help_text(auth_commands, AUTH_HELP_TEXT)
+    Console.write_stdout(help_text)
+
+
+def get_oauth2_access_token(option_list: list):
+    client_id = None
+    username = None
+    password = None
+    scope = "gam_user_data gam_user_roles"
+    for option_flag, option_arg in option_list:
+        if option_flag.name == "client_id":
+            client_id = option_arg
+        if option_flag.name == "username":
+            username = option_arg
+        if option_flag.name == "password":
+            password = option_arg
+        if option_flag.name == "scope":
+            scope = option_arg
+
+    if not (client_id and username and password):
+        raise MissingRequirementException("Cannot obtain Oauth2 access token without client_id, username and password")
+
+    client = AuthClient()
+    result = client.get_oauth2_access_token(
+        client_id=client_id,
+        username=username,
+        password=password,
+        scope=scope
+    )
+    Console.write_stdout(f"Authorized projects detail: \n{result}")
+
+
+get_oauth2_access_token_options = [
+    Option(
+        "client_id",
+        ["--client-id", "--cid"],
+        "The client identifier provided by Globant.",
+        True
+    ),
+    Option(
+        "username",
+        ["--username", "-u"],
+        "Username for authentication.",
+        True
+    ),
+    Option(
+        "password",
+        ["--password", "-p"],
+        "Password for authentication.",
+        True
+    ),
+    Option(
+        "scope",
+        ["--scope", "-s"],
+        "Space-separated list of requested scopes. (Optional)",
+        True
+    ),
+
+]
+
+
+def get_user_profile_information(option_list: list):
+    access_token = None
+    for option_flag, option_arg in option_list:
+        if option_flag.name == "access_token":
+            access_token = option_arg
+
+    client = AuthClient()
+    result = client.get_user_profile_information(access_token=access_token)
+    Console.write_stdout(f"User profile information: \n{result}")
+
+
+get_user_profile_information_options = [
+    Option(
+        "access_token",
+        ["--access-token", "--token"],
+        "Token obtained with the --get-access-token option",
+        True
+    ),
+]
+
+
+auth_commands = [
+    Command(
+        "help",
+        ["help", "h"],
+        "Display help text",
+        show_help,
+        ArgumentsEnum.NOT_AVAILABLE,
+        [],
+        []
+    ),
+    Command(
+        "get_oauth2_access_token",
+        ["get-access-token", "gat"],
+        "Get Oauth acess token for Globant Enterprise AI instance",
+        get_oauth2_access_token,
+        ArgumentsEnum.REQUIRED,
+        [],
+        get_oauth2_access_token_options
+    ),
+    Command(
+        "get_user_profile_information_options",
+        ["get-user-information", "get-user-info", "gui"],
+        "Retrieve user profile information",
+        get_user_profile_information_options,
+        ArgumentsEnum.REQUIRED,
+        [],
+        get_user_profile_information_options
+    ),
+]

pygeai/cli/commands/base.py

@@ -1,9 +1,11 @@
 from pygeai.cli.commands import ArgumentsEnum, Command, Option
 from pygeai.cli.commands.admin import admin_commands
 from pygeai.cli.commands.assistant import assistant_commands
+from pygeai.cli.commands.auth import auth_commands
 from pygeai.cli.commands.builders import build_help_text
 from pygeai.cli.commands.chat import chat_commands
 from pygeai.cli.commands.configuration import configure, configuration_options
+from pygeai.cli.commands.docs import docs_commands
 from pygeai.cli.commands.embeddings import embeddings_commands
 from pygeai.cli.commands.evaluation import evaluation_commands
 from pygeai.cli.commands.feedback import feedback_commands
@@ -20,7 +22,7 @@ from pygeai.cli.commands.secrets import secrets_commands
 from pygeai.cli.commands.usage_limits import usage_limit_commands
 from pygeai.cli.commands.version import check_new_version
 from pygeai.cli.texts.help import HELP_TEXT
-from pygeai.cli import __version__ as cli_version
+from pygeai import __version__ as cli_version
 from pygeai.core.utils.console import Console
 from pygeai.health.clients import HealthClient
 
@@ -155,6 +157,16 @@ base_commands = [
         admin_commands,
         []
     ),
+    Command(
+        "auth",
+        ["auth"],
+        "Invoke auth endpoints for token generation",
+        None,
+        ArgumentsEnum.REQUIRED,
+        auth_commands,
+        []
+    ),
+
     Command(
         "llm",
         ["llm"],
@@ -263,6 +275,15 @@ base_commands = [
         migrate_commands,
         []
     ),
+    Command(
+        "docs",
+        ["docs"],
+        "View PyGEAI SDK documentation",
+        None,
+        ArgumentsEnum.NOT_AVAILABLE,
+        docs_commands,
+        []
+    ),
 
 ]
 

pygeai/cli/commands/docs.py

@@ -0,0 +1,105 @@
+import os
+import subprocess
+import webbrowser
+from pathlib import Path
+
+from pygeai.cli.commands import Command, ArgumentsEnum
+from pygeai.cli.commands.builders import build_help_text
+from pygeai.cli.texts.help import DOCS_HELP_TEXT
+from pygeai.core.utils.console import Console
+
+
+def show_help():
+    help_text = build_help_text(docs_commands, DOCS_HELP_TEXT)
+    Console.write_stdout(help_text)
+
+
+def open_documentation():
+    try:
+        import sphinx
+    except ImportError:
+        Console.write_stdout(
+            "Documentation dependencies (sphinx, sphinx-rtd-theme) are not installed.\n"
+            "Would you like to install them now? [Y/n]: "
+        )
+        response = input().strip().lower()
+        
+        if response in ['', 'y', 'yes']:
+            Console.write_stdout("Installing documentation dependencies...")
+            try:
+                subprocess.run(
+                    ["pip", "install", "pygeai[docs]"],
+                    check=True,
+                    text=True
+                )
+                Console.write_stdout("Documentation dependencies installed successfully.")
+            except subprocess.CalledProcessError as e:
+                Console.write_stderr(f"ERROR: Failed to install dependencies.\n{e}")
+                return
+            except FileNotFoundError:
+                Console.write_stderr("ERROR: pip command not found.")
+                return
+        else:
+            Console.write_stdout("Installation cancelled. Documentation dependencies are required.")
+            return
+
+    package_root = Path(__file__).parent.parent.parent.parent
+    docs_dir = package_root / "docs"
+    build_dir = docs_dir / "build" / "html"
+    index_file = build_dir / "index.html"
+
+    if not index_file.exists():
+        Console.write_stdout("Documentation not found. Building documentation (this may take a minute)...")
+        source_dir = docs_dir / "source"
+        
+        try:
+            result = subprocess.run(
+                ["sphinx-build", "-b", "html", str(source_dir), str(build_dir)],
+                check=True,
+                capture_output=True,
+                text=True,
+                timeout=300
+            )
+            Console.write_stdout("Documentation built successfully.")
+        except subprocess.CalledProcessError as e:
+            Console.write_stderr(f"ERROR: Failed to build documentation.\n{e.stderr}")
+            return
+        except subprocess.TimeoutExpired:
+            Console.write_stderr("ERROR: Documentation build timed out after 5 minutes.")
+            return
+        except FileNotFoundError:
+            Console.write_stderr(
+                "ERROR: sphinx-build command not found.\n"
+                "Install documentation dependencies: pip install pygeai[docs]"
+            )
+            return
+
+    doc_url = f"file://{index_file.absolute()}"
+    Console.write_stdout(f"Opening documentation at: {doc_url}")
+    
+    try:
+        webbrowser.open(doc_url)
+    except Exception as e:
+        Console.write_stderr(f"ERROR: Failed to open browser.\n{e}")
+
+
+docs_commands = [
+    Command(
+        "open",
+        ["open", "o"],
+        "Open documentation in web browser",
+        open_documentation,
+        ArgumentsEnum.NOT_AVAILABLE,
+        [],
+        []
+    ),
+    Command(
+        "help",
+        ["help", "h"],
+        "Display help text",
+        show_help,
+        ArgumentsEnum.NOT_AVAILABLE,
+        [],
+        []
+    ),
+]

pygeai/cli/texts/help.py

@@ -1,6 +1,6 @@
 AUTHORS_SECTION = """
 AUTHORS 
-    Copyright 2025, Globant.
+    Copyright 2026, Globant.
 
 REPORTING BUGS
     To report any bug, request features or make any suggestions, the following email is available:
@@ -39,7 +39,7 @@ ERROR CODES
 Certain error descriptions can contain up to %n references specific to that error. 
 These references are described with %1, %2,... ,%n.
 
-    ErrorCode     	 Description    
+    ErrorCode            Description    
         1       Assistant Not Found 
         2       Provider Type Not Found 
         3       Request Not Found
@@ -136,15 +136,20 @@ DESCRIPTION
     
 EXAMPLES
     The command:
-        geai c
-    starts an interactive tool to configure API KEY and BASE URL to work with GEAI.
+        geai org list-projects
+    lists available projects in your organization.
     
     The command:
-        geai organization list-projects
-    list available projects. For this, an organization API KEY is required.
+        geai org list-projects -d full
+    lists all projects with full details.
     
     The command:
-        ...
+        geai org create-project -n "SDKTest" -e "admin@example.com" -d "Test project for SDK"
+    creates a new project with specified name, email and description.
+    
+    The command:
+        geai org get-tokens --id <PROJECT_UUID>
+    retrieves API tokens for a specific project
     
 {AUTHORS_SECTION}
 """
@@ -167,10 +172,16 @@ DESCRIPTION
     
 EXAMPLES
     The command:
-        
+        geai ast get-assistant --id <ASSISTANT_UUID>
+    retrieves detailed information about a specific assistant.
     
     The command:
-        ...
+        geai ast create-assistant --type chat --name "MyAssistant" --prompt "You are a helpful assistant"
+    creates a new assistant with the specified type, name and prompt.
+    
+    The command:
+        geai ast chat --name "MyAssistant" --msg '[{{{{"role": "user", "content": "Hello"}}}}]'
+    starts a chat session with the specified assistant
     
 {AUTHORS_SECTION}
 """
@@ -193,10 +204,16 @@ DESCRIPTION
     
 EXAMPLES
     The command:
-        
+        geai rag list-assistants
+    lists all RAG assistants in the current project.
     
     The command:
-        ...
+        geai rag get-assistant --name "MyRAG"
+    retrieves information about a specific RAG assistant.
+    
+    The command:
+        geai rag upload-document --name "MyRAG" --file "document.pdf"
+    uploads a document to a RAG assistant's knowledge base
     
 {AUTHORS_SECTION}
 """
@@ -232,9 +249,16 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai chat iris
+    starts an interactive chat session with Iris assistant.
     
     The command:
-        ...
+        geai chat agent --name "MyAgent"
+    starts a chat session with a specific agent.
+    
+    The command:
+        geai chat completion --model "saia:assistant:MyAssistant" --msg '[{{{{"role": "user", "content": "Hello"}}}}]' --stream 0
+    sends a completion request to the specified assistant
     
 {AUTHORS_SECTION}
 """
@@ -258,9 +282,12 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai gam get-access-token
+    retrieves the current GAM access token.
     
     The command:
-        ...
+        geai gam get-user-info
+    retrieves user information from GAM
     
 {AUTHORS_SECTION}
 """
@@ -284,9 +311,12 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai secrets create-secret --name "API_KEY" --value "secret_value"
+    creates a new secret in the secrets manager.
     
     The command:
-        ...
+        geai secrets list-secrets
+    lists all secrets stored in the project
     
 {AUTHORS_SECTION}
 """
@@ -310,9 +340,12 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai migrate agent --agent-id "UUID" --target-project "TARGET_UUID"
+    migrates an agent to a different project.
     
     The command:
-        ...
+        geai migrate process --process-id "UUID" --target-project "TARGET_UUID"
+    migrates an agentic process to another project
     
 {AUTHORS_SECTION}
 """
@@ -336,9 +369,12 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai rerank rerank-chunks --query "search term" --documents '["doc1", "doc2"]' --model "cohere/rerank-english-v3.0"
+    reranks the provided documents based on relevance to the query.
     
     The command:
-        ...
+        geai rerank chunks -q "my query" -d "document text" --top-n 5
+    reranks chunks and returns top 5 results
     
 {AUTHORS_SECTION}
 """
@@ -363,9 +399,16 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai emb generate -i "Help me with Globant Enterprise AI" -m "openai/text-embedding-3-small"
+    generates embeddings for the provided text.
     
     The command:
-        ...
+        geai emb generate -i "Help me with" -i "Globant Enterprise AI" -m "openai/text-embedding-3-small" --cache 1
+    generates embeddings with caching enabled for multiple inputs.
+    
+    The command:
+        geai emb generate -i "text" -m "vertex_ai/text-embedding-004" --input-type "SEMANTIC_SIMILARITY"
+    generates embeddings with a specific input type
         
 {AUTHORS_SECTION}
 """
@@ -389,9 +432,12 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai feedback send --request-id "UUID" --rating 5 --comment "Great response"
+    sends positive feedback for an assistant response.
     
     The command:
-        ...
+        geai feedback list --assistant-id "UUID"
+    lists all feedback for a specific assistant
         
 {AUTHORS_SECTION}
 """
@@ -511,9 +557,45 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai admin validate-token
+    validates the current API token.
     
     The command:
-        ...
+        geai admin list-authorized-organizations
+    lists all organizations the current user has access to.
+    
+    The command:
+        geai admin project-visibility --project-id "UUID"
+    retrieves visibility settings for a specific project
+    
+{AUTHORS_SECTION}
+"""
+
+AUTH_HELP_TEXT = f"""
+GEAI CLI - AUTH
+-----------------------
+
+NAME
+    geai - Command Line Interface for Globant Enterprise AI
+
+SYNOPSIS
+    geai auth <subcommand> --[flag] [flag_arg]
+
+DESCRIPTION
+    geai auth is a command from geai cli utility, developed to manage authentication access tokens instance of GEAI.
+    
+    The options are as follows:
+    {{available_commands}}
+    
+EXAMPLES
+    The command:
+        
+        geai auth get-access-token
+    retrieves an OAuth2 access token for authentication.
+    
+    The command:
+        geai auth get-user-info
+    retrieves the current user's profile information
     
 {AUTHORS_SECTION}
 """
@@ -539,9 +621,12 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai llm list-models
+    lists all available LLM models in GEAI.
     
     The command:
-        ...
+        geai llm list-providers
+    lists all available LLM providers
     
 {AUTHORS_SECTION}
 """
@@ -565,9 +650,12 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai files upload --file "document.pdf" --purpose "assistants"
+    uploads a file to GEAI for use with assistants.
     
     The command:
-        ...
+        geai files list
+    lists all uploaded files in the project
     
 {AUTHORS_SECTION}
 """
@@ -591,9 +679,16 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai -a myorg usage-limit set-organization-limit --organization <ORG_UUID> --subscription-type Monthly --usage-unit Cost --soft-limit 1000 --hard-limit 5000 --renewal-status Renewable
+    sets usage limits for an organization.
     
     The command:
-        ...
+        geai -a myorg usage-limit get-latest-org-lim --organization <ORG_UUID>
+    retrieves the latest usage limit for an organization.
+    
+    The command:
+        geai -a myorg usage-limit up-org-lim --organization <ORG_UUID> --lid <LIMIT_UUID> --renewal-status Renewable --soft-limit 5000 --hard-limit 8000
+    updates an existing usage limit for an organization
     
 {AUTHORS_SECTION}
 """
@@ -617,9 +712,16 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai ai-lab create-agent --name "MyAgent" --instructions "You are a helpful agent"
+    creates a new agent in the AI Lab.
     
     The command:
-        ...
+        geai ai-lab list-agents
+    lists all agents in the current project.
+    
+    The command:
+        geai ai-lab create-process --name "MyProcess" --description "Automated workflow"
+    creates a new agentic process
     
 {AUTHORS_SECTION}
 """
@@ -643,9 +745,40 @@ DESCRIPTION
 EXAMPLES
     The command:
         
+        geai spec load-agent --file "agent_spec.json"
+    loads an agent from a JSON specification file.
     
     The command:
-        ...
+        geai spec load-process --file "process_spec.json"
+    loads an agentic process from a JSON specification file
+    
+{AUTHORS_SECTION}
+"""
+
+DOCS_HELP_TEXT = f"""
+GEAI CLI - DOCS
+---------------
+
+NAME
+    geai - Command Line Interface for Globant Enterprise AI
+
+SYNOPSIS
+    geai docs <subcommand>
+
+DESCRIPTION
+    geai docs is a command from geai cli utility to view the PyGEAI SDK documentation.
+    
+    The options are as follows:
+    {{available_commands}}
+    
+EXAMPLES
+    The command:
+        
+        geai docs
+    opens the HTML documentation in your web browser.
+    
+    If documentation dependencies are not installed, you will be prompted to install them.
+    If the documentation is not built, it will be automatically generated.
     
 {AUTHORS_SECTION}
 """