pygeai 0.6.0b13__py3-none-any.whl → 0.6.1__py3-none-any.whl

pygeai/_docs/source/content/migration.rst

@@ -109,6 +109,383 @@ The required API keys depend on whether you're creating a new project or migrati
 .. warning::
    When migrating to an existing project (using ``--to-project-id``), you MUST provide ``--to-api-key``. This is a project scope token that has write access to the destination project.
 
+Interactive Mode
+----------------
+
+The migration tool provides an **interactive mode** that guides you through the migration process with step-by-step prompts. This mode is ideal when:
+
+- You're new to the migration tool and want guidance
+- You don't know the exact IDs of resources to migrate
+- You want to browse and select resources interactively
+- You prefer a wizard-style interface over command-line arguments
+
+Invoking Interactive Mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To start the interactive migration wizard, use the ``--interactive`` or ``-i`` flag:
+
+.. code-block:: shell
+
+    geai migrate clone-project --interactive
+
+or shorter:
+
+.. code-block:: shell
+
+    geai migrate clone-project -i
+
+Interactive Mode Walkthrough
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you launch interactive mode, the wizard will guide you through the following steps:
+
+**Step 1: Migration Type Selection**
+
+Choose whether you're migrating within the same instance or to a different instance:
+
+.. code-block:: text
+
+    ================================================================================
+    PROJECT MIGRATION ASSISTANT
+    ================================================================================
+
+    Migration type (1=same instance, 2=cross instance):
+
+- Option ``1``: Migrate within the same GEAI instance (destination instance will be same as source)
+- Option ``2``: Migrate to a different GEAI instance (you'll provide separate destination credentials)
+
+**Step 2: Source Configuration**
+
+Provide your source project credentials:
+
+.. code-block:: text
+
+    --- Source Configuration ---
+    Source API key: [enter your source API key]
+    Source instance URL: [enter source instance URL, e.g., https://api.dev.example.ai]
+    Source project ID: [enter source project ID]
+
+The wizard will automatically retrieve your source organization ID from the API token.
+
+**Step 3: Project Creation or Selection**
+
+Decide whether to create a new destination project or use an existing one:
+
+.. code-block:: text
+
+    Create new destination project? (y/n):
+
+- If you choose ``y`` (yes): You'll provide organization API keys, project name, and admin email to create a new project
+- If you choose ``n`` (no): You'll provide an existing destination project ID
+
+**For new project creation:**
+
+.. code-block:: text
+
+    Source organization API key: [enter organization scope API key]
+    Destination organization API key: [same as source for same instance, or enter different key]
+    New project name: [enter name for new project]
+    Admin email: [enter admin email for project]
+
+**For existing project:**
+
+.. code-block:: text
+
+    Destination project ID: [enter existing project ID]
+
+**Step 4: Destination Configuration**
+
+If you selected cross-instance migration (option 2) or using an existing project, provide destination details:
+
+.. code-block:: text
+
+    --- Destination Configuration ---
+    Destination instance URL: [enter destination URL if cross-instance]
+    Destination API key: [enter project API key for destination]
+
+**Step 5: Resource Type Selection**
+
+Select which types of resources you want to migrate:
+
+.. code-block:: text
+
+    --- Resource Type Selection ---
+    Which resource types do you want to migrate?
+      1. Agents
+      2. Tools
+      3. Agentic Processes
+      4. Tasks
+      5. RAG Assistants
+      6. Files
+      7. Usage Limits
+      8. Secrets
+
+    Select resource types (comma-separated numbers, or empty for all):
+
+- Enter specific numbers (e.g., ``1,2,5`` for Agents, Tools, and RAG Assistants)
+- Press Enter without typing anything to migrate **all** resource types
+
+**Step 6: Resource Selection**
+
+For each selected resource type, the wizard fetches available resources and displays an interactive menu:
+
+.. code-block:: text
+
+    --- Retrieving Available Resources ---
+
+    Available agents:
+      0. Cancel (don't migrate this resource type)
+      1. Customer Support Agent (ID: agent-abc-123)
+      2. Data Analysis Agent (ID: agent-def-456)
+      3. Code Review Agent (ID: agent-ghi-789)
+
+    Select agents (comma-separated numbers, or empty for all):
+
+Selection options:
+
+- Press **Enter** without typing: Migrate **all** resources of this type
+- Enter **0**: Skip this resource type entirely
+- Enter **specific numbers**: Migrate only selected resources (e.g., ``1,3`` to migrate items 1 and 3)
+
+This process repeats for each resource type you selected in Step 5.
+
+**Step 7: Migration Summary and Confirmation**
+
+Review your migration configuration before execution:
+
+.. code-block:: text
+
+    --- Migration Summary ---
+    Source: https://api.dev.example.ai / Project: source-project-123
+    Destination: https://api.prod.example.ai / Project: Production Release
+    Resources: agents, tools, rag_assistants
+
+    Stop migration on first error? (Y/n):
+
+- Enter ``Y`` or press Enter to stop migration if any resource fails
+- Enter ``n`` to continue migrating remaining resources even if some fail
+
+.. code-block:: text
+
+    Proceed with migration? (y/n):
+
+- Enter ``y`` to start the migration
+- Enter ``n`` to cancel and exit without making changes
+
+**Step 8: Migration Execution**
+
+The migration proceeds with real-time progress updates:
+
+.. code-block:: text
+
+    ============================================================
+    Migration Progress: 0/15 completed
+    ============================================================
+
+    [1/15] Migrating agent 'Customer Support Agent'...
+    ✓ Successfully migrated agent 'Customer Support Agent'
+
+    [2/15] Migrating agent 'Data Analysis Agent'...
+    ✓ Successfully migrated agent 'Data Analysis Agent'
+
+    [3/15] Migrating tool 'Database Query Tool'...
+    ✓ Successfully migrated tool 'Database Query Tool'
+
+    ...
+
+    ============================================================
+    Migration Complete: 15/15 successful
+    ============================================================
+
+Interactive Mode Benefits
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**1. No Need to Remember IDs**
+
+   You don't need to know resource IDs beforehand. The wizard fetches and displays all available resources with their names and IDs.
+
+**2. Visual Resource Selection**
+
+   Browse resources in numbered menus and select exactly what you want to migrate.
+
+**3. Guided Configuration**
+
+   Step-by-step prompts ensure you provide all required information in the correct order.
+
+**4. Input Validation**
+
+   The wizard validates your input at each step and prompts you to retry if something is invalid.
+
+**5. Pre-Migration Summary**
+
+   Review all settings before execution with a clear summary of what will be migrated.
+
+**6. Flexible Selection**
+
+   Easily mix migration strategies: migrate all agents, specific tools, all RAG assistants, etc.
+
+**7. Error Recovery**
+
+   If you make a mistake during prompts, the wizard will ask again instead of failing the entire operation.
+
+Interactive vs. CLI Mode Comparison
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++----------------------------+---------------------------+---------------------------+
+| Feature                    | Interactive Mode          | CLI Mode                  |
++============================+===========================+===========================+
+| **Ease of Use**            | Beginner-friendly wizard  | Requires knowledge of     |
+|                            |                           | all CLI arguments         |
++----------------------------+---------------------------+---------------------------+
+| **Resource Discovery**     | Automatic with menus      | Manual (use API or docs)  |
++----------------------------+---------------------------+---------------------------+
+| **Input Validation**       | Real-time with retry      | Fails if invalid args     |
++----------------------------+---------------------------+---------------------------+
+| **Automation**             | Not scriptable            | Fully scriptable          |
++----------------------------+---------------------------+---------------------------+
+| **Best For**               | One-time migrations,      | CI/CD pipelines,          |
+|                            | exploration, learning     | automation, scripting     |
++----------------------------+---------------------------+---------------------------+
+
+When to Use Interactive Mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+✅ **Use Interactive Mode when:**
+
+- You're performing a one-time migration
+- You're unsure of exact resource IDs or names
+- You want to browse available resources before selecting
+- You're learning how migration works
+- You prefer guided prompts over memorizing command syntax
+
+❌ **Use CLI Mode instead when:**
+
+- You're automating migrations in scripts or CI/CD pipelines
+- You already know exact resource IDs to migrate
+- You need to run the same migration multiple times
+- You want to version control migration commands
+
+Example Interactive Session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here's a complete example of an interactive migration session:
+
+.. code-block:: text
+
+    $ geai migrate clone-project -i
+
+    ================================================================================
+    PROJECT MIGRATION ASSISTANT
+    ================================================================================
+
+    Migration type (1=same instance, 2=cross instance): 2
+
+    --- Source Configuration ---
+    Source API key: sk_dev_abc123...
+    Source instance URL: https://api.dev.example.ai
+    Source project ID: proj-dev-001
+
+    Create new destination project? (y/n): y
+    Source organization API key: sk_org_dev_xyz789...
+    Destination organization API key: sk_org_prod_def456...
+    New project name: Production Release v2.0
+    Admin email: admin@example.com
+
+    --- Destination Configuration ---
+    Destination instance URL: https://api.prod.example.ai
+    Destination API key: (will be created after project creation)
+
+    --- Resource Type Selection ---
+    Which resource types do you want to migrate?
+      1. Agents
+      2. Tools
+      3. Agentic Processes
+      4. Tasks
+      5. RAG Assistants
+      6. Files
+      7. Usage Limits
+      8. Secrets
+
+    Select resource types (comma-separated numbers, or empty for all): 1,2,5
+
+    --- Retrieving Available Resources ---
+
+    Available agents:
+      0. Cancel (don't migrate this resource type)
+      1. Customer Support Agent (ID: agent-001)
+      2. Sales Assistant (ID: agent-002)
+      3. HR Onboarding Agent (ID: agent-003)
+
+    Select agents (comma-separated numbers, or empty for all): 
+
+    Available tools:
+      0. Cancel (don't migrate this resource type)
+      1. Database Query Tool (ID: tool-001)
+      2. Email Sender (ID: tool-002)
+      3. Calendar Integration (ID: tool-003)
+
+    Select tools (comma-separated numbers, or empty for all): 1,3
+
+    Available RAG assistants:
+      0. Cancel (don't migrate this resource type)
+      1. Documentation Assistant (ID: doc-assistant-001)
+      2. Code Helper (ID: code-assistant-002)
+
+    Select RAG assistants (comma-separated numbers, or empty for all): 
+
+    --- Migration Summary ---
+    Source: https://api.dev.example.ai / Project: proj-dev-001
+    Destination: https://api.prod.example.ai / Project: Production Release v2.0
+    Resources: agents, tools, rag_assistants
+
+    Stop migration on first error? (Y/n): Y
+
+    Proceed with migration? (y/n): y
+
+    Creating new project 'Production Release v2.0'...
+    Project 'Production Release v2.0' created successfully with ID: proj-prod-002
+    Creating project API key for new project...
+    Project API key created successfully
+
+    ============================================================
+    Migration Progress: 0/7 completed
+    ============================================================
+
+    [1/7] Migrating agent 'Customer Support Agent'...
+    ✓ Successfully migrated agent 'Customer Support Agent'
+
+    [2/7] Migrating agent 'Sales Assistant'...
+    ✓ Successfully migrated agent 'Sales Assistant'
+
+    [3/7] Migrating agent 'HR Onboarding Agent'...
+    ✓ Successfully migrated agent 'HR Onboarding Agent'
+
+    [4/7] Migrating tool 'Database Query Tool'...
+    ✓ Successfully migrated tool 'Database Query Tool'
+
+    [5/7] Migrating tool 'Calendar Integration'...
+    ✓ Successfully migrated tool 'Calendar Integration'
+
+    [6/7] Migrating RAG assistant 'Documentation Assistant'...
+    ✓ Successfully migrated RAG assistant 'Documentation Assistant'
+
+    [7/7] Migrating RAG assistant 'Code Helper'...
+    ✓ Successfully migrated RAG assistant 'Code Helper'
+
+    ============================================================
+    Migration Complete: 7/7 successful
+    ============================================================
+
+    Migration completed: 7/7 successful
+
+This example demonstrates:
+
+- Cross-instance migration (dev to prod)
+- New project creation
+- Selective resource type migration (agents, tools, RAG assistants only)
+- Mixed selection strategies (all agents, specific tools, all RAG assistants)
+- Successful completion with progress tracking
+
 Basic Usage
 -----------
 
@@ -310,7 +687,12 @@ Command: ``geai migrate clone-project``
 
 **Description:** Clone a project with selective or complete resource migration.
 
-**Required Arguments:**
+**Interactive Mode Flag:**
+
+``--interactive`` or ``-i``
+  Launch the interactive migration wizard with step-by-step prompts. When this flag is used, all other arguments are ignored and the wizard will prompt for all required information. See the :ref:`Interactive Mode` section for details.
+
+**Required Arguments (CLI Mode):**
 
 ``--from-api-key <key>``
   Project scope API key for the source GEAI instance (for migrating resources)
@@ -425,12 +807,14 @@ Best Practices
 --------------
 
 1. **Test First**: Always test migrations in a development environment before production
-2. **Use --all for Complete Clones**: When creating backups or full clones, use ``--all``
-3. **Verify Credentials**: Double-check API keys and instance URLs before running migrations
-4. **Monitor Progress**: Watch the console output for discovery counts and migration status
-5. **Check Results**: Review the migration result summary after completion
-6. **Incremental Migration**: For large projects, consider migrating resource types incrementally
-7. **Document Migrations**: Keep track of what was migrated and when
+2. **Start with Interactive Mode**: If you're new to migrations or unsure about resource IDs, use ``--interactive`` mode for guided assistance
+3. **Use --all for Complete Clones**: When creating backups or full clones, use ``--all``
+4. **Verify Credentials**: Double-check API keys and instance URLs before running migrations
+5. **Monitor Progress**: Watch the console output for discovery counts and migration status
+6. **Check Results**: Review the migration result summary after completion
+7. **Incremental Migration**: For large projects, consider migrating resource types incrementally
+8. **Document Migrations**: Keep track of what was migrated and when
+9. **Automate Repeated Migrations**: Once you know the exact resources and IDs, convert interactive sessions to CLI commands for repeatability
 
 Common Use Cases
 ----------------

pygeai/_docs/source/pygeai.core.common.rst

@@ -12,6 +12,14 @@ pygeai.core.common.config module
    :show-inheritance:
    :undoc-members:
 
+pygeai.core.common.constants module
+-----------------------------------
+
+.. automodule:: pygeai.core.common.constants
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 pygeai.core.common.decorators module
 ------------------------------------
 

pygeai/_docs/source/pygeai.tests.auth.rst

@@ -4,6 +4,22 @@ pygeai.tests.auth package
 Submodules
 ----------
 
+pygeai.tests.auth.test\_cli\_configuration module
+-------------------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_cli_configuration
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.tests.auth.test\_client\_initialization module
+-----------------------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_client_initialization
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 pygeai.tests.auth.test\_clients module
 --------------------------------------
 
@@ -12,6 +28,22 @@ pygeai.tests.auth.test\_clients module
    :show-inheritance:
    :undoc-members:
 
+pygeai.tests.auth.test\_config\_manager module
+----------------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_config_manager
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.tests.auth.test\_header\_injection module
+------------------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_header_injection
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 pygeai.tests.auth.test\_oauth module
 ------------------------------------
 
@@ -20,6 +52,30 @@ pygeai.tests.auth.test\_oauth module
    :show-inheritance:
    :undoc-members:
 
+pygeai.tests.auth.test\_session\_logging module
+-----------------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_session_logging
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.tests.auth.test\_session\_validation module
+--------------------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_session_validation
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+pygeai.tests.auth.test\_singleton\_reset module
+-----------------------------------------------
+
+.. automodule:: pygeai.tests.auth.test_singleton_reset
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 Module contents
 ---------------
 

pygeai/_docs/source/pygeai.tests.cli.rst

@@ -13,6 +13,14 @@ Subpackages
 Submodules
 ----------
 
+pygeai.tests.cli.test\_credentials\_flag module
+-----------------------------------------------
+
+.. automodule:: pygeai.tests.cli.test_credentials_flag
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 pygeai.tests.cli.test\_error\_handler module
 --------------------------------------------
 

pygeai/admin/clients.py

@@ -1,9 +1,7 @@
-
-from pygeai import logger
 from pygeai.admin.endpoints import GET_API_TOKEN_VALIDATION_V1, GET_AUTHORIZED_ORGANIZATIONS_V1, \
     GET_AUTHORIZED_PROJECTS_V1, GET_PROJECT_VISIBILITY_V1, GET_PROJECT_API_TOKEN_V1
 from pygeai.core.base.clients import BaseClient
-from pygeai.core.common.exceptions import InvalidAPIResponseException
+
 from pygeai.core.utils.validators import validate_status_code
 from pygeai.core.utils.parsers import parse_json_response
 

pygeai/analytics/clients.py

@@ -53,7 +53,7 @@ class AnalyticsClient(BaseClient):
 
     def __build_headers(self):
         return {
-            "Authorization": self.api_service.token,
+            "Authorization": f"Bearer {self.api_service.token}",
             "OrganizationId": self.organization_id,
             "ProjectId": self.project_id
         }

pygeai/assistant/clients.py

@@ -1,11 +1,6 @@
-
-from pygeai import logger
-from pygeai.assistant.endpoints import GET_ASSISTANT_DATA_V1, CREATE_ASSISTANT_V1, UPDATE_ASSISTANT_V1, BEGIN_CONVERSATION_V1, \
-    SEND_TEXT_PROMPT_V1, SEND_CHAT_REQUEST_V1, GET_REQUEST_STATUS_V1, CANCEL_REQUEST_V1
-from pygeai.assistant.data_analyst.endpoints import GET_DATA_ANALYST_STATUS_V1, EXTEND_DATA_ANALYST_DATASET_V1
+from pygeai.assistant.endpoints import GET_ASSISTANT_DATA_V1, CREATE_ASSISTANT_V1, UPDATE_ASSISTANT_V1, \
+    SEND_CHAT_REQUEST_V1, GET_REQUEST_STATUS_V1, CANCEL_REQUEST_V1
 from pygeai.core.base.clients import BaseClient
-from pygeai.core.common.decorators import handler_server_error
-from pygeai.core.common.exceptions import InvalidAPIResponseException
 from pygeai.core.utils.validators import validate_status_code
 from pygeai.core.utils.parsers import parse_json_response
 

pygeai/assistant/data/clients.py

@@ -1,12 +1,4 @@
-import json
-
 from pygeai.assistant.clients import AssistantClient
-from pygeai.assistant.endpoints import GET_ASSISTANT_DATA_V1, CREATE_ASSISTANT_V1, UPDATE_ASSISTANT_V1, BEGIN_CONVERSATION_V1, \
-    SEND_TEXT_PROMPT_V1, SEND_CHAT_REQUEST_V1, GET_REQUEST_STATUS_V1, CANCEL_REQUEST_V1
-from pygeai.assistant.data_analyst.endpoints import GET_DATA_ANALYST_STATUS_V1, EXTEND_DATA_ANALYST_DATASET_V1
-from pygeai.core.base.clients import BaseClient
-from pygeai.core.common.decorators import handler_server_error
-from pygeai.core.utils.validators import validate_status_code
 
 
 class ChatWithDataAssistantClient(AssistantClient):

pygeai/assistant/data_analyst/clients.py

@@ -1,9 +1,7 @@
 from pathlib import Path
 
-from pygeai import logger
 from pygeai.assistant.clients import AssistantClient
 from pygeai.assistant.data_analyst.endpoints import GET_DATA_ANALYST_STATUS_V1, EXTEND_DATA_ANALYST_DATASET_V1
-from pygeai.core.common.exceptions import InvalidAPIResponseException
 from pygeai.core.utils.validators import validate_status_code
 from pygeai.core.utils.parsers import parse_json_response
 

pygeai/assistant/managers.py

@@ -4,7 +4,7 @@ from pygeai.assistant.clients import AssistantClient
 from pygeai.assistant.rag.clients import RAGAssistantClient
 from pygeai.assistant.rag.mappers import RAGAssistantMapper
 from pygeai.assistant.rag.responses import DocumentListResponse
-from pygeai.core.base.mappers import ErrorMapper, ResponseMapper
+from pygeai.core.base.mappers import ResponseMapper
 from pygeai.core.handlers import ErrorHandler
 from pygeai.core.models import Assistant, TextAssistant, ChatAssistant, ChatMessageList, AssistantRevision, \
     ChatVariableList, LlmSettings, ChatWithDataAssistant, ChatToolList, ToolChoice

pygeai/assistant/rag/clients.py

@@ -3,14 +3,12 @@ import logging
 from pathlib import Path
 from typing import Any
 
-from pygeai import logger
 from pygeai.assistant.rag.endpoints import GET_ASSISTANTS_FROM_PROJECT_V1, GET_ASSISTANT_V1, CREATE_ASSISTANT_V1, \
     UPDATE_ASSISTANT_V1, DELETE_ASSISTANT_V1, GET_DOCUMENTS_V1, DELETE_ALL_DOCUMENTS_V1, RETRIEVE_DOCUMENT_V1, \
     UPLOAD_DOCUMENT_V1, DELETE_DOCUMENT_V1, EXECUTE_QUERY_V1
 from pygeai.core.base.clients import BaseClient
 import urllib.parse
 
-from pygeai.core.common.exceptions import InvalidAPIResponseException
 from pygeai.core.utils.validators import validate_status_code
 from pygeai.core.utils.parsers import parse_json_response
 

pygeai/assistant/rag/mappers.py

@@ -186,14 +186,13 @@ class RAGAssistantMapper(ModelMapper):
 
     @classmethod
     def map_to_document_list(cls, data: dict) -> list[Document]:
-        document_list = list()
-        documents = data.get("documents")
+        documents = data.get('documents')
+
         if documents is not None and any(documents):
-            for document_data in documents:
-                document = cls.map_to_document(document_data)
-                document_list.append(document)
 
-        return document_list
+            return [cls.map_to_document(document_data) for document_data in documents]
+
+        return []
 
     @classmethod
     def map_to_document(cls, data: dict) -> Document:
@@ -211,14 +210,13 @@ class RAGAssistantMapper(ModelMapper):
 
     @classmethod
     def map_to_document_metadata_list(cls, data: dict) -> List[DocumentMetadata]:
-        metadata_list = list()
         metadata = data.get('metadata')
+
         if metadata is not None and any(metadata):
-            for metadata_data in metadata:
-                new_metadata = cls.map_to_document_metadata(metadata_data)
-                metadata_list.append(new_metadata)
 
-        return metadata_list
+            return [cls.map_to_metadata(metadata_data) for metadata_data in metadata]
+
+        return []
 
     @classmethod
     def map_to_document_metadata(cls, data: dict) -> DocumentMetadata: