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

pygeai/_docs/source/content/api_reference.rst

@@ -0,0 +1,46 @@
+API Reference
+=============
+
+This document provides a comprehensive overview of **API Reference**, outlining its structure and available functionalities.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    api_reference/chat
+    api_reference/project
+    api_reference/rag
+    api_reference/embeddings
+
+
+Authentication
+--------------
+To use the API, you need to authenticate each request using `API Tokens <https://wiki.genexus.com/enterprise-ai/wiki?564,API+Tokens>`_. These tokens are managed in `Globant Enterprise AI Backoffice <https://wiki.genexus.com/enterprise-ai/wiki?42,Globant+Enterprise+AI+Backoffice>`_.
+
+The following properties are common to every interaction with **API Reference**:
+
+==========================  ================================================================
+Variable                        Description
+==========================  ================================================================
+`GEAI_API_BASE_URL`              `$BASE_URL`. The base URL for your Globant Enterprise AI installation (e.g., https://api.saia.ai or a custom value).
+`GEAI_API_KEY`                   `$SAIA_APITOKEN`. An API token generated for each project or organization.
+==========================  ================================================================
+
+Interaction Levels
+------------------
+The API is designed with three levels of abstraction to cater to different use cases and developer preferences:
+
+Command Line
+~~~~~~~~~~~~
+This level provides a straightforward way to interact with the `Globant Enterprise AI <https://wiki.genexus.com/enterprise-ai/wiki?8,Table+of+contents%3AEnterprise+AI>`_ using simple commands. It handles the communication with the REST API and presents the responses in an easy-to-understand format.
+
+Low-Level Service Layer
+~~~~~~~~~~~~~~~~~~~~~~~
+This layer offers more granular control over API interactions. You work directly with client classes that handle the HTTP requests and responses. This layer returns data in JSON format, providing flexibility for further processing.
+
+High-Level Service Layer
+~~~~~~~~~~~~~~~~~~~~~~~~
+This layer abstracts away the complexities of handling raw JSON data. It uses manager classes that map the JSON responses to Python objects, simplifying data manipulation and integration with your application logic.
+
+Each item in this section has these three ways of implementing a function. The user can choose the one that adequate
+better to their use case.

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,126 @@
+geai - cli examples
+===================
+
+In this section, you can find examples of commands using the geai utility to perform basic tasks in GEAI.
+
+# 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
+

pygeai/_docs/source/content/debugger.rst

@@ -0,0 +1,188 @@
+PyGEAI Debugger
+===============
+
+Overview
+--------
+
+``geai-dbg`` is a command-line debugger for the ``geai`` CLI tool, part of the ``pygeai`` package. It allows developers to pause execution at specified points (breakpoints) in the ``geai`` codebase, inspect local variables, execute arbitrary Python code in the current context, and control program flow interactively. Breakpoints can be set by module or function name, providing flexibility for debugging complex CLI workflows.
+
+The debugger is invoked by running the ``geai-dbg`` command, typically with the same arguments as the ``geai`` CLI. It pauses execution at predefined or user-specified breakpoints, presenting an interactive prompt ``(geai-dbg)`` for issuing commands.
+
+Installation and Setup
+---------------------
+
+``geai-dbg`` is included in the ``pygeai`` package. Ensure ``pygeai`` is installed in your Python environment:
+
+.. code-block:: bash
+
+    pip install pygeai
+
+No additional setup is required. The debugger script (``debugger.py``) is located in the ``pygeai.dbg`` module and can be invoked via the ``geai-dbg`` command.
+
+Usage
+-----
+
+To use ``geai-dbg``, run it with the same arguments you would pass to the ``geai`` CLI. For example:
+
+.. code-block:: bash
+
+    geai-dbg ail lrs
+
+This command runs the ``geai`` CLI with the arguments ``ail lrs`` under the debugger. The debugger automatically sets a breakpoint at the ``main`` function in the ``pygeai.cli.geai`` module, pausing execution before the ``geai`` command processes the arguments.
+
+Upon hitting a breakpoint, the debugger displays:
+
+- The location (module and function) where execution is paused.
+- Local variables in the current context.
+- An interactive prompt ``(geai-dbg)`` for entering commands.
+
+You can then inspect variables, add breakpoints, execute code, or control execution using the available commands.
+
+Commands
+--------
+
+At the ``(geai-dbg)`` prompt, the following commands are available:
+
+continue, c
+    Resume execution until the next breakpoint is hit or the program completes.
+
+quit, q, Ctrl+D
+    Exit the debugger, terminating the program with a clean exit status (0).
+
+run, r
+    Run the program to completion, disabling all breakpoints and skipping further pauses.
+
+breakpoint-module, bm
+    Add a breakpoint for a specific module. Prompts for a module name (e.g., ``pygeai.cli.commands``). Press Enter to set a wildcard breakpoint (any module).
+
+breakpoint-function, bf
+    Add a breakpoint for a specific function, optionally scoped to a module. Prompts for a function name (e.g., ``main``) and an optional module name. Press Enter for wildcards (any function or module).
+
+list-modules, lm
+    List all loaded modules starting with ``pygeai``, useful for identifying valid module names for breakpoints.
+
+help, h
+    Display a list of available commands and their descriptions.
+
+<Python code>
+    Execute arbitrary Python code in the current context. For example, ``print(sys.argv)`` displays the command-line arguments. Errors are caught and logged without crashing the debugger.
+
+Ctrl+C
+    Interrupt the current command input and resume execution, equivalent to ``continue``.
+
+Examples
+--------
+
+**Example 1: Debugging a geai Command**
+
+Suppose you want to debug the ``geai ail lrs`` command to inspect its execution. Run:
+
+.. code-block:: bash
+
+    geai-dbg ail lrs
+
+Output:
+
+.. code-block:: text
+
+    2025-05-12 15:04:57,263 - geai - INFO - GEAI debugger started.
+    2025-05-12 15:04:57,263 - geai - INFO - geai module: pygeai.cli.geai
+    2025-05-12 15:04:57,263 - geai - INFO - Breakpoint added: pygeai.cli.geai:main
+    2025-05-12 15:04:57,264 - geai - INFO - Setting trace and running geai
+    2025-05-12 15:04:57,264 - geai - INFO - Breakpoint hit at pygeai.cli.geai.main
+    2025-05-12 15:04:57,264 - geai - INFO - Local variables: {}
+
+    Paused at pygeai.cli.geai.main
+    Enter commands to execute in the current context (type 'continue' to resume, 'quit' to exit, 'help' to display available commands):
+    (geai-dbg)
+
+List available commands:
+
+.. code-block:: text
+
+    (geai-dbg) h
+    Available commands:
+      continue, c: Resume execution until next breakpoint
+      quit, q: Exit the debugger
+      run, r: Run program without further pauses
+      breakpoint-module, bm: Add a module breakpoint
+      breakpoint-function, bf: Add a function breakpoint
+      list-modules, lm: List available modules
+      <Python code>: Execute arbitrary Python code in the current context
+
+List modules to find valid breakpoint targets:
+
+.. code-block:: text
+
+    (geai-dbg) lm
+    2025-05-12 15:05:03,595 - geai - INFO - Listing available modules
+    Available modules: ['pygeai', 'pygeai.dbg', 'pygeai.cli', ...]
+
+Continue to the next breakpoint (e.g., another hit on ``main`` in a different context):
+
+.. code-block:: text
+
+    (geai-dbg) c
+    2025-05-12 15:05:18,424 - geai - DEBUG - Alias: default
+    2025-05-12 15:05:18,424 - geai - DEBUG - Base URL: api.beta.saia.ai/
+    2025-05-12 15:05:18,425 - geai - INFO - Breakpoint hit at pygeai.cli.geai.main
+    2025-05-12 15:05:18,425 - geai - INFO - Local variables: {'self': <pygeai.cli.geai.CLIDriver object at 0x100f34080>, 'args': None}
+
+    Paused at pygeai.cli.geai.main
+    Enter commands to execute in the current context (type 'continue' to resume, 'quit' to exit, 'help' to display available commands):
+    (geai-dbg)
+
+Run the program to completion:
+
+.. code-block:: text
+
+    (geai-dbg) run
+    2025-05-12 15:05:21,221 - geai - INFO - Running program without further pauses.
+    2025-05-12 15:05:21,222 - geai - DEBUG - Running geai with: /path/to/venv/bin/geai-dbg ail lrs
+    2025-05-12 15:05:21,222 - geai - DEBUG - Listing reasoning strategies
+    [geai output listing reasoning strategies]
+    2025-05-12 15:05:21,878 - geai - INFO - Cleaning up trace
+
+**Example 2: Inspecting Variables**
+
+At a breakpoint, inspect command-line arguments:
+
+.. code-block:: text
+
+    (geai-dbg) print(sys.argv)
+    2025-05-12 15:05:21,300 - geai - INFO - Executing interactive command: print(sys.argv)
+    ['/path/to/venv/bin/geai-dbg', 'ail', 'lrs']
+
+**Example 3: Adding a Breakpoint**
+
+Add a breakpoint for the ``pygeai.cli.commands`` module:
+
+.. code-block:: text
+
+    (geai-dbg) bm
+    2025-05-12 15:05:21,400 - geai - INFO - Adding breakpoint on module
+    (geai-dbg) Enter module name (or press Enter for any module): pygeai.cli.commands
+    2025-05-12 15:05:21,500 - geai - INFO - Breakpoint added: pygeai.cli.commands:*
+
+Notes
+-----
+
+- **Ctrl+D and Ctrl+C**:
+  - Pressing ``Ctrl+D`` at the ``(geai-dbg)`` prompt terminates the debugger gracefully, logging "Debugger terminated by user (EOF)." and exiting with status 0.
+  - Pressing ``Ctrl+C`` resumes execution, equivalent to the ``continue`` command.
+
+- **Python Code Execution**:
+  - Arbitrary Python code executed at the prompt runs in the context of the paused frame, with access to local and global variables. Use with caution, as it can modify program state.
+
+- **Breakpoint Wildcards**:
+  - Use ``bm`` or ``bf`` with empty inputs to set wildcard breakpoints, pausing on any module or function. This is useful for exploratory debugging.
+
+- **Logging**:
+  - The debugger logs to stdout with timestamps, including breakpoint hits, local variables, and command execution. Errors in Python code execution are logged without crashing the debugger.
+
+For issues or feature requests, contact the ``pygeai`` development team.
+
+.. seealso::
+
+   - ``geai`` CLI documentation for details on the underlying command-line tool.
+   - Python's ``sys.settrace`` documentation for technical details on the debugging mechanism.

pygeai/_docs/source/content/intro.rst

@@ -0,0 +1,67 @@
+Introduction
+============
+
+About SDKs
+----------
+An SDK (Software Development Kit) is a set of tools, libraries, documentation, code samples, processes and guides that
+developers use to create software applications for a specific platform or service.
+SDKs simplify the integration process by providing pre-built functionality and standardized methods for interfacing with APIs or systems.
+
+- Tools: compilers, debuggers and other utilities
+- Libraries: Collection of pre-written code that can be integrated into an application to extend its functionality.
+- Documentation: Guides, API references, tutorials and best practices for using the SDK.
+- Code samples: Snippets demonstrating how to use the SDK’s features
+- Processes: Guidelines on how to develop, test and deploy applications using the SDK
+
+The goal of `PyGEA </pygeai>`_ is to provide this set of resources in order to interact with `Globant Enterprise AI <https://wiki.genexus.com/enterprise-ai/wiki?8,Table+of+contents%3AEnterprise+AI>`_.
+
+Requirements
+------------
+The SDK was designed to comply with the following requirements:
+
+- Cross-platform: It runs on MacOS, Windows, Linux distributions and BSD variants.
+- Easy to install: It offers ease of installation through pip or as an individual package.
+- Easy to set up: It offers assistance during the setup process.
+- Intuitive: Flags and options resemble those available in similar tools in order to provide a familiar interface to work with.
+- Common use cases can be accomplished in a few steps.
+- Native look for any Python developer, including naming conventions, style, etc.
+- Comprehensive test suite to ensure reliability and consistency across releases.
+
+Architecture
+------------
+The SDK is composed of libraries (libs), code samples, and documentation. The command-line utility interacts with the SDK to facilitate tasks. The geai-chat utility provides an interactive experience when dealing with the cli utility.
+The lower level of the SDK handles interaction with the APIs available in Globant Enterprise AI.
+
+Tools
+-----
+- geai-cli is the command-line utility through which you can interact with the SDK libraries.
+- geai-chat is an interactive tool to perform common tasks with the Globant Enterprise AI in an automated manner.
+- geai-dbg is a debugging tool that provides a detailed view of what the SDK is doing in order to find and fix any issues.
+
+Libraries
+---------
+
+The user can import the different modules from the libraries in order to interact with GEAI services. The proposed structure for the libraries and tools is as follows
+
+- pygeai: Meta-package that encapsulates all the components of the SDK.
+    - pygeai-cli: Command-line tool to interact with the SDK.
+    - pygeai-chat: Interactive version of the cli tool.
+    - pygeai-dbg: Debugger to deal with potential issues in the SDK and have a detailed view of what it’s doing.
+    - pygeai-core: To handle interaction with base components of Globant Enterprise AI. Also, to handle users, groups, permissions, API Tokens, etc.
+    - pygeai-organization: To handle `Organizations <https://wiki.genexus.com/enterprise-ai/wiki?42,Globant+Enterprise+AI+Backoffice#Organization+Options>`_, `Projects <https://wiki.genexus.com/enterprise-ai/wiki?565,Projects>`_, etc.
+    - pygeai-agent: To handle interactions with Agent Studio.
+    - pygeai-assistant: To handle interaction with `Data Analyst Assistants <https://wiki.genexus.com/enterprise-ai/wiki?886,Data+Analyst+Assistant+2.0>`_, `RAG Assistants <https://wiki.genexus.com/enterprise-ai/wiki?44,RAG+Assistants+Introduction>`_, `Chat with Data Assistants <https://wiki.genexus.com/enterprise-ai/wiki?159,Chat+with+Data+Assistant>`_, `Chat with API Assistants <https://wiki.genexus.com/enterprise-ai/wiki?110,API+Assistant>`_, and `Chat Assistants <https://wiki.genexus.com/enterprise-ai/wiki?708,Chat+Assistant>`_.
+    - pygeai-flows: To handle interactions with `Flows <https://wiki.genexus.com/enterprise-ai/wiki?321,Flows+in+Globant+Enterprise+AI>`_.
+
+Samples
+-------
+
+Code samples should illustrate how to use each module at a high level, including additional references to appropriate documentation when deeper understanding is required.
+
+Documentation
+-------------
+
+The following basic documents are available to help you get started:
+
+- `Quickstart </docs/source/content/quickstart.rst>`_: A simple guide showing the process of installing, configuring and starting the SDK.
+- `API reference </docs/source/content/api_reference.rst>`_: A detailed description of each module.

pygeai/_docs/source/content/modules.rst

@@ -0,0 +1,7 @@
+PyGEAI - Modules
+================
+
+.. toctree::
+   :maxdepth: 4
+
+   content/pygeai