pygeai 0.1.6__py3-none-any.whl → 0.6.0b15__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/chat_gui.rst

@@ -0,0 +1,121 @@
+GEAI Chat GUI Documentation
+===========================
+
+Overview
+--------
+
+The GEAI Chat GUI is a Streamlit-based graphical user interface (GUI) for interacting with AI agents provided by the Globant Enterprise AI (GEAI) platform. This interface is launched via the `geai chat agent` command with the `--gui` or `-g` flag. It allows users to chat with specified agents, manage chat sessions, switch between agents, and customize session storage settings.
+
+This documentation provides an overview of the GUI's features, usage instructions, and command-line invocation.
+
+Command-Line Invocation
+-----------------------
+
+The Streamlit GUI is not run as a standalone Streamlit app but is invoked through the GEAI CLI. The relevant command and options are as follows:
+
+.. code-block:: bash
+
+    geai chat agent --agent-name <agent_name> --gui
+
+**Options:**
+
+- ``--agent-name`` or ``-n``: Specifies the name or ID of the agent to interact with. This is a required argument.
+- ``--gui`` or ``-g``: Launches the Streamlit GUI for an interactive chat experience. No additional argument is needed for this flag.
+
+**Example:**
+
+.. code-block:: bash
+
+    geai chat agent --agent-name "MyAgent" --gui
+
+This command launches the Streamlit GUI for chatting with the agent named "MyAgent".
+
+Features of the Streamlit GUI
+-----------------------------
+
+The GEAI Chat GUI provides a user-friendly interface for interacting with AI agents. Below are the key features, organized by their location in the interface (main area and sidebar).
+
+Main Interface
+~~~~~~~~~~~~~~
+
+1. **Chat Window:**
+   - Displays the conversation history with the selected agent.
+   - Supports real-time message streaming for agent responses.
+   - Allows searching through chat history using a keyword filter.
+   - Provides options to edit the last user message and regenerate the agent's response if needed.
+   - Includes a "Complete Answer" button to prompt the agent to continue an incomplete response.
+
+2. **Chat Input:**
+   - Located at the bottom of the main window, allowing users to type and send messages to the agent.
+
+3. **Session Information:**
+   - Displays the path where the current session will be saved (e.g., ``chats/chat_session_<agent_name>_<date>.json``).
+
+4. **Reset Chat:**
+   - A button to clear the current chat history and start a fresh session with the agent's introductory message.
+
+Sidebar Features
+~~~~~~~~~~~~~~~~
+
+The sidebar contains controls for session management and agent switching.
+
+1. **Session Management:**
+   - **Auto-Save Session:** A toggle to enable or disable automatic saving of chat history to a server-side file after each message or action.
+   - **Custom Session Filename:** An input field to specify a custom filename for saving the session (stored in the ``chats`` directory).
+   - **Save Session (JSON):** A download button to save the current chat history as a JSON file locally.
+   - **Restore Session (JSON):** A file uploader to load a previously saved JSON session file into the current chat.
+   - **Available Sessions:** A list of saved session files in the ``chats`` directory, with options to load or delete them. Note: The active session file cannot be deleted.
+   - **Help Section:** An expandable section explaining session saving and restoring functionalities.
+
+2. **Agent Switching:**
+   - **Select Alias:** A dropdown to choose a profile (alias) for accessing specific API configurations.
+   - **Enter Project ID:** An input field for specifying the project ID to list available agents.
+   - **Select Agent:** A dropdown to pick an agent from the list retrieved based on the alias and project ID.
+   - **Agent Description Preview:** Displays a brief description of the selected agent (if available).
+   - **Recent Agents:** A list of recently used agents for quick switching.
+   - **Confirmation for Switching:** Prompts the user to confirm before switching to a new agent, which starts a fresh session in a new tab.
+   - **Help Section:** An expandable section explaining the agent switching process.
+
+Usage Instructions
+------------------
+
+1. **Launching the GUI:**
+   - Run the command ``geai chat agent --agent-name <agent_name> --gui`` to start the Streamlit interface for the specified agent.
+   - The browser will open automatically (if configured) or provide a URL to access the interface.
+
+2. **Chatting with an Agent:**
+   - Type your message in the chat input field at the bottom of the main window and press Enter.
+   - The agent's response will stream in real-time in the chat window.
+   - Use the "Complete Answer" button if the agent's response seems incomplete.
+   - Search through the chat history using the search bar above the chat window.
+   - Edit your last message by clicking the edit button (✏️) next to it, modify the content, and save to regenerate the agent's response.
+
+3. **Managing Sessions:**
+   - Enable "Auto-Save Session" in the sidebar to automatically save chat history to a server-side file.
+   - Specify a custom filename for the session if desired.
+   - Download the current session as a JSON file using the "Save Session (JSON)" button.
+   - Upload a previously saved JSON file to restore a session using the file uploader.
+   - View and manage saved sessions under "Available Sessions" (load or delete files as needed).
+
+4. **Switching Agents:**
+   - In the sidebar under "Switch Agent", select an alias and enter a project ID to list available agents.
+   - Choose an agent from the dropdown and review its description (if available).
+   - Confirm the switch to start a new session with the selected agent in a new tab.
+   - Alternatively, switch to a recently used agent directly from the "Recent Agents" list.
+
+5. **Resetting the Chat:**
+   - Click the "Reset Chat" button in the main interface to clear the current session and start fresh with the agent's introduction.
+
+File Storage
+------------
+
+- **Default Session Files:** Chat sessions are saved by default in the ``chats`` directory with filenames in the format ``chat_session_<agent_name>_<YYYY-MM-DD>.json``.
+- **Custom Filenames:** Users can specify custom filenames via the sidebar, which are also stored in the ``chats`` directory.
+- **Recent Agents:** A list of recently used agents is saved in ``recent_agents.json`` for quick access across sessions.
+
+Troubleshooting
+---------------
+
+- **Agent Not Found:** If the specified agent does not exist, an error message will be displayed. Verify the agent name or ID and try again.
+- **Session File Errors:** Errors during saving or loading session files are logged and displayed as Streamlit error messages. Ensure the ``chats`` directory has appropriate read/write permissions.
+- **Unexpected Errors:** Any unhandled exceptions are logged and displayed in the GUI. Contact support at ``geai-sdk@globant.com`` for assistance.

pygeai/_docs/source/content/cli.rst

@@ -0,0 +1,203 @@
+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
+
+    geai h
+
+.. code-block:: shell
+
+    geai org h
+
+.. code-block:: shell
+
+    geai ast h
+
+
+.. code-block:: shell
+
+    geai chat h
+
+
+# Create project
+
+.. code-block:: shell
+
+    geai org create-project \
+      -n "SDKTest2" \
+      -e "geai-sdk@globant.com" \
+      -d "Test project for SDK"
+
+# Update project
+
+.. code-block:: shell
+
+     geai org update-project \
+      --id 12345678-1234-1234-1234-123456789abc \
+      --name "SDK Test 3" \
+      --description "Test description"
+
+# List projects
+
+.. code-block:: shell
+
+    geai org list-projects
+
+.. code-block:: shell
+
+    geai org list-projects -d full
+
+# Get tokens from organization
+
+.. code-block:: shell
+
+    geai org get-tokens --id aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
+
+# List assistants
+
+.. code-block:: shell
+
+    geai org list-assistants
+
+# Get assistant information
+
+.. code-block:: shell
+
+    geai ast get-assistant --id 11111111-2222-3333-4444-555555555555
+
+# Chat with assistant
+
+.. code-block:: shell
+
+    geai ast chat \
+      --name "Welcome data Assistant" \
+      --msg '[{"role": "user", "content": "Translate the phrase free software is the software that protects users freedoms"}, {"role": "user", "content": "now translate to french"]'
+
+
+# Create assistant
+
+.. code-block:: shell
+
+    geai ast create-assistant \
+      --type chat \
+      --name "Welcome data Assistant 3" \
+      --prompt "Translate to French" \
+      --wd-title "Assistant with WelcomeData" \
+      --wd-description "It is to test WelcomeData" \
+      --wd-feature '[{"title": "First Feature", "description": "First Feature Description"}, {"title": "Second Feature", "description": "Second Feature Description"}]' \
+      --wd-example-prompt '{"title": "First Prompt Example", "description": "First Prompt Example Description", "prompt_text": "You are an assistant specialized in translating"}'
+
+
+# Update assistant
+
+.. code-block:: shell
+
+    geai ast update-assistant \
+      --assistant-id 99999999-8888-7777-6666-555555555555 \
+      --action savePublishNewRevision \
+      --prompt "translate the following text to Latin" \
+      --provider-name "openai" \
+      --model-name "gpt-3.5-turbo" \
+      --temperature 0.0 \\n  --wd-title "Assistant with WelcomeData" \
+      --wd-description "It is to test WelcomeData" \
+      --wd-feature "Second Feature: Second Feature Description" \
+      --wd-feature "First Feature: First Feature Description" \
+      --wd-example-prompt "First Prompt Example: First Prompt Example Description: You are an assistant specialized in translating"
+
+# Delete assistant
+
+.. code-block:: shell
+
+    geai ast delete-assistant --id 99999999-8888-7777-6666-555555555555
+
+
+# Chat completion
+
+.. code-block:: shell
+
+    geai chat completion \
+      --model "saia:assistant:Welcome data Assistant 3" \
+      --msg '[{"role": "user", "content": "Translate the phrase free software is the software that protects users freedoms"}, {"role": "user", "content": "now translate to french and italian"}]' \
+      --stream 0
+