pygeai 0.1.51b3__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/cli/texts/help.py

@@ -1,9 +1,6 @@
 AUTHORS_SECTION = """
 AUTHORS 
-    Developed and maintained by:
-        - Alejandro Trinidad <alejandro.trinidad@globant.com>
-
-    Copyright 2025, Globant.
+    Copyright 2026, Globant.
 
 REPORTING BUGS
     To report any bug, request features or make any suggestions, the following email is available:
@@ -42,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
@@ -139,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}
 """
@@ -170,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}
 """
@@ -196,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}
 """
@@ -217,15 +231,34 @@ SYNOPSIS
 DESCRIPTION
     geai chat is a command from geai cli utility, developed to chat with assistant in GEAI.
     
+    The model needs to specify an assistant_type and a specific_parameter whose format depends on that type. Its format is as follows:
+
+    "model": "saia:<assistant_type>:<specific_parameter>"
+    
+    assistant_type can be:
+    - agent: Identifies a Agent.
+    - flow: Identifies a Flow.
+    - assistant: Identifies an Assistant API, Data Analyst Assistant, Chat with Data Assistant and API Assistant.
+    - search: Identifies a RAG Assistant.
+
+    For more information, refer to the GEAI Wiki: https://wiki.genexus.com/enterprise-ai/wiki?34,Chat+API
+    
     The options are as follows:
     {{available_commands}}
     
 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}
 """
@@ -249,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}
 """
@@ -275,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}
 """
@@ -301,9 +340,30 @@ DESCRIPTION
 EXAMPLES
     The command:
         
-    
-    The command:
-        ...
+        geai migrate clone-project \\
+            --from-api-key "source_api_key_123abc456def789ghi012jkl345mno678pqr901stu234" \\
+            --from-organization-api-key "org_key_abc123def456ghi789jkl012mno345pqr678" \\
+            --from-project-id "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" \\
+            --from-instance "https://api.example.ai" \\
+            --to-project-name "Migrated Project - Complete Clone" \\
+            --admin-email "admin@example.com" \\
+            --all
+    
+    will clone entire project within the same instance
+    
+    The command: 
+    
+        geai migrate clone-project \\
+            --from-api-key "source_api_key_123abc456def789ghi012jkl345mno678pqr901stu234" \\
+            --from-organization-api-key "source_org_key_abc123def456ghi789jkl012mno345pqr678" \\
+            --from-project-id "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" \\
+            --from-instance "https://api.test.example.ai" \\
+            --to-organization-api-key "dest_org_key_stu901vwx234yz567abc890def123ghi456jkl789" \\
+            --to-project-name "Migrated Project - Complete Clone" \\
+            --admin-email "admin@example.com" \\
+            --all
+    
+    will clone entire project with ALL resources (cross-instance)
     
 {AUTHORS_SECTION}
 """
@@ -327,9 +387,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}
 """
@@ -354,9 +417,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}
 """
@@ -380,9 +450,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}
 """
@@ -502,9 +575,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}
 """
@@ -530,9 +639,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}
 """
@@ -556,9 +668,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}
 """
@@ -582,9 +697,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}
 """
@@ -608,9 +730,124 @@ 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}
+"""
+
+SPEC_HELP_TEXT = f"""
+GEAI CLI - AI LAB - SPEC
+------------------------
+
+NAME
+    geai - Command Line Interface for Globant Enterprise AI
+
+SYNOPSIS
+    geai spec <subcommand> --[flag] [flag_arg]
+
+DESCRIPTION
+    geai spec is a command from geai cli utility, developed to load components to the AI Lab in GEAI from json specifications.
+    
+    The options are as follows:
+    {{available_commands}}
+    
+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}
+"""
+
+ANALYTICS_HELP_TEXT = f"""
+GEAI CLI - ANALYTICS
+--------------------
+
+NAME
+    geai - Command Line Interface for Globant Enterprise AI
+
+SYNOPSIS
+    geai analytics <subcommand> --[flag] [flag_arg]
+
+DESCRIPTION
+    geai analytics is a command from geai cli utility, developed to retrieve analytics and metrics from GEAI.
+    
+    Date Range Defaults:
+    If --start-date and --end-date are not specified, the commands will default to the previous month
+    (from the first day to the last day of the previous month).
+    
+    The options are as follows:
+    {{available_commands}}
+    
+EXAMPLES
+    The command:
+        
+        geai analytics agents-created --start-date "2024-01-01" --end-date "2024-01-31"
+    retrieves the total number of agents created and modified in January 2024.
+    
+    The command:
+        
+        geai analytics full-report
+    retrieves a comprehensive analytics report for the previous month.
+    
+    The command:
+        
+        geai analytics full-report --start-date "2024-01-01" --end-date "2024-01-31" --csv report.csv
+    retrieves a comprehensive analytics report for January 2024 and exports it to report.csv.
+    
+    The command:
+        geai analytics total-cost -s "2024-01-01" -e "2024-01-31"
+    retrieves the total cost for January 2024.
+    
+    The command:
+        geai analytics requests-per-day -s "2024-01-01" -e "2024-01-31"
+    retrieves the total requests per day for January 2024.
+    
+    The command:
+        geai analytics top-agents -s "2024-01-01" -e "2024-01-31"
+    retrieves the top 10 agents by number of requests
     
 {AUTHORS_SECTION}
 """

pygeai/core/base/clients.py

@@ -1,33 +1,74 @@
 from abc import ABC
+from pygeai import logger
 
 from pygeai.core.base.session import get_session, Session
 from pygeai.core.common.exceptions import MissingRequirementException
 from pygeai.core.services.rest import ApiService
+from pygeai.core.utils.validators import validate_status_code
+
 
 
 class BaseClient(ABC):
+    _logged_session_config = None
 
-    def __init__(self, api_key: str = None, base_url: str = None, alias: str = "default"):
+    def __init__(self, api_key: str = None, base_url: str = None, alias: str = None, *,
+                 access_token: str = None, project_id: str = None):
         """
         If commont settings are not specified, they're retrieved from default Session, based on the
         credential files.
         :param api_key: GEAI API KEY to access services
         :param base_url: URL for GEAI instance to be used
+        :param alias: Alias to use from credentials file
+        :param access_token: OAuth access token (keyword-only)
+        :param project_id: Project ID for OAuth authentication (keyword-only)
         """
-        if not (api_key and base_url):
-            session = get_session(alias)
-            if not session:
+        if access_token and not project_id:
+            raise MissingRequirementException("project_id is required when using access_token")
+
+        if not (api_key and base_url) and not (access_token and base_url) and alias:
+            self.__session = get_session(alias)
+            if not self.__session:
                 raise MissingRequirementException("API KEY and BASE URL must be defined in order to use this functionality")
+        elif (api_key or access_token) and base_url:
+            self.__session = get_session()
+            self.__session.api_key = api_key
+            self.__session.access_token = access_token
+            self.__session.project_id = project_id
+            self.__session.base_url = base_url
+        else:
+            self.__session = get_session()
 
-            if not api_key:
-                api_key = session.api_key
-            if not base_url:
-                base_url = session.base_url
+        if self.session is None:
+            raise MissingRequirementException("Cannot access this functionality without setting API_KEY and BASE_URL")
+        
+        # Log session config only once per unique session configuration
+        session_config_key = (
+            self.session.alias,
+            self.session.base_url,
+            bool(self.session.access_token),
+            bool(self.session.api_key)
+        )
+        
+        if BaseClient._logged_session_config != session_config_key:
+            if self.session.access_token and self.session.project_id:
+                logger.info(f"Using OAuth 2.0 authentication")
+            elif self.session.api_key:
+                logger.info(f"Using API Key authentication")
+            else:
+                logger.warning("No authentication method configured")
+            
+            logger.info(f"Alias: {self.session.alias}")
+            logger.info(f"Base URL: {self.session.base_url}")
+            
+            BaseClient._logged_session_config = session_config_key
 
-        self.__session = Session(api_key=api_key, base_url=base_url)
-        self.__session.api_key = api_key
-        self.__session.base_url = base_url
-        self.__api_service = ApiService(base_url=self.session.base_url, token=self.session.api_key)
+        token = self.session.access_token if self.session.access_token else self.session.api_key
+        
+        self.__api_service = ApiService(
+            base_url=self.session.base_url,
+            token=token,
+            project_id=self.session.project_id
+        )
 
     @property
     def session(self):

pygeai/core/base/mappers.py

@@ -351,13 +351,22 @@ class ModelMapper:
     @classmethod
     def map_to_item(cls, data: dict) -> RequestItem:
         return RequestItem(
+            api_token=data.get('apiToken'),
             assistant=data.get('assistant'),
+            cost=data.get('cost'),
+            elapsed_time_ms=data.get('elapsedTimeMs'),
+            end_timestamp=data.get('endTimestamp'),
+            feedback=data.get('feedback'),
             intent=data.get('intent'),
-            timestamp=data.get('timestamp'),
+            module=data.get('module'),
             prompt=data.get('prompt'),
             output=data.get('output'),
             input_text=data.get('inputText'),
-            status=data.get('status')
+            rag_sources_consulted=data.get('ragSourcesConsulted'),
+            session_id=data.get('sessionId'),
+            start_timestamp=data.get('startTimestamp'),
+            status=data.get('status'),
+            timestamp=data.get('timestamp')
         )
 
     @classmethod

pygeai/core/base/session.py

@@ -1,11 +1,13 @@
-import os
 import sys
+from typing import Optional
 
+from pygeai import logger
 from pygeai.core.common.config import get_settings
 from pygeai.core.common.exceptions import MissingRequirementException
 from pygeai.core.singleton import Singleton
 
-settings = get_settings()
+
+_session = None
 
 
 class Session(metaclass=Singleton):
@@ -15,19 +17,36 @@ class Session(metaclass=Singleton):
     :param api_key: str - API key to interact with GEAI
     :param base_url: str - Base URL of the GEAI instance
     :param eval_url: Optional[str] - Optional evaluation endpoint URL
+    :param access_token: Optional[str] - OAuth access token (keyword-only)
+    :param project_id: Optional[str] - Project ID for OAuth authentication (keyword-only)
     :return: Session - Instance of the Session class
     :raises: ValueError - If required parameters are missing or invalid
     """
 
     def __init__(
             self,
-            api_key: str,
-            base_url: str,
-            eval_url: str = None,
+            api_key: str = None,
+            base_url: str = None,
+            eval_url: Optional[str] = None,
+            *,
+            access_token: Optional[str] = None,
+            project_id: Optional[str] = None,
+            alias: Optional[str] = None,
     ):
+        if not api_key and not access_token:
+            logger.warning("Cannot instantiate session without api_key or access_token")
+        if not base_url:
+            logger.warning("Cannot instantiate session without base_url")
+
         self.__api_key = api_key
         self.__base_url = base_url
         self.__eval_url = eval_url
+        self.__access_token = access_token
+        self.__project_id = project_id
+        self.__alias = alias if alias else "default"
+
+        global _session
+        _session = self
 
     @property
     def api_key(self):
@@ -53,18 +72,83 @@ class Session(metaclass=Singleton):
     def eval_url(self, eval_url: str):
         self.__eval_url = eval_url
 
+    @property
+    def access_token(self):
+        return self.__access_token
+
+    @access_token.setter
+    def access_token(self, access_token: str):
+        self.__access_token = access_token
+
+    @property
+    def project_id(self):
+        return self.__project_id
+
+    @project_id.setter
+    def project_id(self, project_id: str):
+        self.__project_id = project_id
+
+    @property
+    def alias(self):
+        return self.__alias
+
+    @alias.setter
+    def alias(self, alias: str):
+        self.__alias = alias
+
 
-def get_session(alias: str = "default") -> Session:
+def get_session(alias: str = None) -> Session:
     """
     Session is a singleton object:
     On the first invocation, returns Session configured with the API KEY and BASE URL corresponding to the
     alias provided. On the following invocations, it returns the first object instantiated.
     """
     try:
-        return Session(
-            api_key=settings.get_api_key(alias),
-            base_url=settings.get_base_url(alias),
-            eval_url=settings.get_eval_url(alias),
-        )
+        settings = get_settings()
+        global _session
+        if _session is None:
+            if not alias:
+                alias = "default"
+            
+            _validate_alias(alias, allow_missing_default=True)
+
+            _session = Session(
+                api_key=settings.get_api_key(alias),
+                base_url=settings.get_base_url(alias),
+                eval_url=settings.get_eval_url(alias),
+                access_token=settings.get_access_token(alias),
+                project_id=settings.get_project_id(alias),
+                alias=alias,
+            )
+                
+        elif _session is not None and alias:
+            _validate_alias(alias, allow_missing_default=False)
+            
+            _session.alias = alias
+            _session.api_key = settings.get_api_key(alias)
+            _session.base_url = settings.get_base_url(alias)
+            _session.eval_url = settings.get_eval_url(alias)
+            _session.access_token = settings.get_access_token(alias)
+            _session.project_id = settings.get_project_id(alias)
+
+        return _session
     except ValueError as e:
+        logger.warning(f"Warning: API_KEY and/or BASE_URL not set. {e}")
         sys.stdout.write("Warning: API_KEY and/or BASE_URL not set. Please run geai configure to set them up.\n")
+
+
+def _validate_alias(alias: str, allow_missing_default: bool = False):
+    settings = get_settings()
+    available_aliases = settings.list_aliases()
+    if alias not in available_aliases:
+        if allow_missing_default and alias == "default":
+            return
+        raise MissingRequirementException(
+            f"The profile '{alias}' doesn't exist. Use 'geai configure --list' to see available profiles."
+        )
+
+
+def reset_session():
+    """Reset the session instance. Useful for testing."""
+    global _session
+    _session = None