pygeai 0.6.0b13__tar.gz → 0.6.0b14__tar.gz

{pygeai-0.6.0b13/pygeai.egg-info → pygeai-0.6.0b14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeai
-Version: 0.6.0b13
+Version: 0.6.0b14
 Summary: Software Development Kit to interact with Globant Enterprise AI.
 Author-email: Globant <geai-sdk@globant.com>
 License-Expression: MIT

{pygeai-0.6.0b13 → pygeai-0.6.0b14}/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
 ----------------