diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f46ab7833..4ce2a9568 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -9,4 +9,4 @@ repos: - id: check-yaml args: - --allow-multiple-documents - - id: check-added-large-files +# - id: check-added-large-files diff --git a/docusaurus.config.js b/docusaurus.config.js index a6c138d49..603eeeea0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -232,12 +232,13 @@ export default async function createConfigAsync() { onBrokenAnchors: process.env.FAIL_ON_BROKEN_LINKS === "true" ? "throw" : "warn", - markdown: { - hooks: { - onBrokenMarkdownLinks: - process.env.FAIL_ON_BROKEN_LINKS === "true" ? "throw" : "warn", - }, - }, + // TODO: markdown.hooks not supported in Docusaurus 3.8.1 - upgrade Docusaurus or remove + // markdown: { + // hooks: { + // onBrokenMarkdownLinks: + // process.env.FAIL_ON_BROKEN_LINKS === "true" ? "throw" : "warn", + // }, + // }, customFields: { // Put your custom environment here diff --git a/netlify.toml b/netlify.toml index d71841d05..545efc9a8 100644 --- a/netlify.toml +++ b/netlify.toml @@ -15,6 +15,8 @@ [context.deploy-preview.build.environment] INCLUDE_NEXT="true" + EXCLUDE_PLATFORM_API="true" + EXCLUDE_PLATFORM_OPENAPI="true" # Seqera API docs are too large to host / build on netlify on their own. # The appropriate ENVVAR is set to disable the API Builds on Netlify for the main docs site. diff --git a/platform-cloud/cloud-sidebar.json b/platform-cloud/cloud-sidebar.json index 4d29b05e8..7998751b4 100644 --- a/platform-cloud/cloud-sidebar.json +++ b/platform-cloud/cloud-sidebar.json @@ -125,6 +125,19 @@ "launch/advanced" ] }, + { + "type": "category", + "label": "Seqera AI CLI", + "link": {"type": "doc", "id": "seqera-ai/index"}, + "collapsed": true, + "items": [ + "seqera-ai/get-started", + "seqera-ai/installation", + "seqera-ai/authentication", + "seqera-ai/command-approval", + "seqera-ai/use-cases" + ] + }, { "type": "category", "label": "Studios", @@ -158,19 +171,6 @@ "administration/credit-management" ] }, - { - "type": "category", - "label": "Seqera AI CLI", - "link": {"type": "doc", "id": "seqera-ai/index"}, - "collapsed": true, - "items": [ - "seqera-ai/get-started", - "seqera-ai/installation", - "seqera-ai/authentication", - "seqera-ai/command-approval", - "seqera-ai/use-cases" - ] - }, { "type": "category", "label": "Developer tools", diff --git a/platform-cloud/docs/seqera-ai/authentication.md b/platform-cloud/docs/seqera-ai/authentication.md index 71b7b19c0..3dca27f47 100644 --- a/platform-cloud/docs/seqera-ai/authentication.md +++ b/platform-cloud/docs/seqera-ai/authentication.md @@ -33,46 +33,34 @@ This will: 1. Display a success message in your terminal ``` - Opening browser for authentication... - Successfully authenticated as user@example.com + [Login] Starting Seqera CLI authentication... + [Login] ✓ Authentication successful! + [Login] ✓ Organization set: ``` ### View session status -To view your current authentication status, run: +To view your current session status, use the `/status` command inside the TUI: -```bash -seqera status ``` - -You should see output similar to: - -```console -Logged in as: user@example.com -Session expires: 2025-12-16 14:30:00 +/status ``` -### Add access tokens for automation - -For automated environments, you can provide a Seqera Platform access token directly: +This shows your authentication status and organization details. -```bash -seqera ai --token -``` +### Add access tokens for automation -You can also set the token via environment variable: +For automated environments, you can provide a Seqera Platform access token directly using the `SEQERA_ACCESS_TOKEN` environment variable: ```bash -export TOWER_ACCESS_TOKEN= +export SEQERA_ACCESS_TOKEN= seqera ai ``` -This shows your login status, authenticated email, and session details. +When this environment variable is set, the CLI skips the OAuth login flow and uses the provided token directly. ### Log out -#### Standard logout - To sign out from the current session, run: ```bash @@ -81,15 +69,33 @@ seqera logout This command revokes your current authentication token and removes locally stored credentials. You will need to re-authenticate on next use. -#### Clear all sessions +## Organization management -To remove all profiles and completely reset authentication, run: +Seqera AI CLI supports managing your organization selection for billing. Use the `seqera org` command to view and switch organizations. + +**View current organization**: ```bash -seqera logout --all +seqera org ``` -This command removes all stored credentials and session data. +**List all organizations**: + +```bash +seqera org list +``` + +**Switch organization**: + +```bash +seqera org switch +``` + +**Clear organization selection**: + +```bash +seqera org clear +``` ## Token refresh diff --git a/platform-cloud/docs/seqera-ai/command-approval.md b/platform-cloud/docs/seqera-ai/command-approval.md index b21fdcffe..a3b969c28 100644 --- a/platform-cloud/docs/seqera-ai/command-approval.md +++ b/platform-cloud/docs/seqera-ai/command-approval.md @@ -17,27 +17,24 @@ Seqera AI can execute local commands and edit files in your environment. This pa ## Approval prompts -When a command requires approval, you will see output similar to: +When a command requires approval, you will see a prompt similar to: ``` -⚠ Approval required (default mode) +APPROVAL REQUIRED (default mode) +Command: rm -rf ./build/ -╭──────────────────────────────────────╮ -│ rm -rf ./build/ │ -╰──────────────────────────────────────╯ +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject - 1 Yes, run this command - 2 Yes, and don't ask again this session - 3 No, cancel and stop - -Select [1/2/3]: +Press 1, 2, or 3 to choose ``` You can: -- **1**: Run the command as shown -- **2**: Run the command and switch to `full` approval mode for the rest of the session -- **3**: Cancel the command and stop the current operation +- **1**: Run the command once (or press Enter) +- **2**: Run the command and auto-approve all commands for the rest of the session +- **3**: Reject the command (or press Escape) ## Approval modes @@ -51,6 +48,18 @@ There are three approval modes: | **default** | Safe commands and workspace file edits run automatically | Typical development | | **full** | Everything except dangerous commands runs automatically | Experienced users | +You can set the approval mode when starting the CLI: + +```bash +seqera ai --approval-mode full +``` + +Or change it during a session using the `/approval` TUI command: + +``` +/approval basic +``` + ### Basic **Rule**: Only safe, read-only commands run automatically. Everything else requires approval. @@ -82,17 +91,12 @@ This is the most restrictive mode. The assistant can only auto-execute commands ``` > Create a new file called test.txt with "hello world" -⚠ Approval required (basic mode) - -╭──────────────────────────────────────╮ -│ Write ./test.txt │ -╰──────────────────────────────────────╯ +APPROVAL REQUIRED (basic mode) +Command: Write ./test.txt - 1 Yes, run this command - 2 Yes, and don't ask again this session - 3 No, cancel and stop - -Select [1/2/3]: +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject ``` ### Default @@ -131,17 +135,12 @@ File creation in the workspace runs automatically. ``` > Edit /etc/hosts -⚠ Approval required (default mode) - -╭──────────────────────────────────────╮ -│ Edit /etc/hosts │ -╰──────────────────────────────────────╯ +APPROVAL REQUIRED (default mode) +Command: Edit /etc/hosts - 1 Yes, run this command - 2 Yes, and don't ask again this session - 3 No, cancel and stop - -Select [1/2/3]: +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject ``` Editing outside the workspace requires approval. @@ -194,17 +193,12 @@ Most operations run without prompts. ``` > Delete the build directory -⚠ Approval required (full mode) - -╭──────────────────────────────────────╮ -│ rm -rf ./build/ │ -╰──────────────────────────────────────╯ +APPROVAL REQUIRED (full mode) +Command: rm -rf ./build/ - 1 Yes, run this command - 2 Yes, and don't ask again this session - 3 No, cancel and stop - -Select [1/2/3]: +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject ``` Dangerous commands still require approval. @@ -216,15 +210,12 @@ In **default** mode, the "workspace" is your current working directory and its s - **Inside workspace**: `/path/to/workspace/src/file.txt` - auto-executes - **Outside workspace**: `/etc/config` or `~/other-project/file.txt` - requires approval -The workspace is set when you start the assistant: +The workspace is set to your current directory when you start the CLI: ```bash # Workspace is /home/user/my-project cd /home/user/my-project seqera ai - -# Or explicitly set the workspace -seqera ai -w /home/user/my-project ``` ## Best practices diff --git a/platform-cloud/docs/seqera-ai/get-started.md b/platform-cloud/docs/seqera-ai/get-started.md index 74d632c2b..0b8a2504b 100644 --- a/platform-cloud/docs/seqera-ai/get-started.md +++ b/platform-cloud/docs/seqera-ai/get-started.md @@ -20,7 +20,7 @@ To get started with Seqera AI: 1. Install the Seqera AI CLI: ```bash - pip install seqera + npm install -g seqera ``` See [Installation](./installation.mdx) for a comprehensive installation guide. @@ -40,6 +40,12 @@ To get started with Seqera AI: seqera ai ``` + You can also start with an initial query: + + ```bash + seqera ai "list my pipelines" + ``` + 1. Run your first prompt: ``` diff --git a/platform-cloud/docs/seqera-ai/index.md b/platform-cloud/docs/seqera-ai/index.md index 569971091..90e7b2ff9 100644 --- a/platform-cloud/docs/seqera-ai/index.md +++ b/platform-cloud/docs/seqera-ai/index.md @@ -51,6 +51,14 @@ Build containerized environments on-the-fly with conda packages, pip packages, o Edit files, run commands, and manage your local development environment with AI assistance and configurable approval modes. +### LSP code intelligence + +Real-time error detection and AI-powered code navigation for Nextflow, Python, and R files in your workspace. + +### Session management + +Resume previous sessions to continue your work. Use `seqera ai -c` to continue your most recent session or `seqera ai -s ` to resume a specific session. + ### Seqera Platform integration Full access to Platform capabilities including compute environments, datasets, data links, and workspace management. diff --git a/platform-cloud/docs/seqera-ai/installation.mdx b/platform-cloud/docs/seqera-ai/installation.mdx index 9c231cd6f..2c1f1b7af 100644 --- a/platform-cloud/docs/seqera-ai/installation.mdx +++ b/platform-cloud/docs/seqera-ai/installation.mdx @@ -18,126 +18,102 @@ Seqera Cloud users receive $20 in free credits to get started with Seqera AI. [C ## Requirements -- Python 3.13 or later -- macOS, Linux, or Windows with WSL +- macOS (Apple Silicon or Intel) or Linux x64 - A Seqera Platform account ([sign up for free](https://cloud.seqera.io)) - An internet connection -## Python Package Index - -The Seqera AI CLI is distributed as a Python package through PyPI, making installation simple and straightforward using standard Python tools. - -### Install +## Install - - -To install Seqera AI CLI with pip: - -1. Check your Python version: - - ```bash - python --version - # or - python3 --version - ``` - - If you need to install or upgrade Python, see [python.org](https://www.python.org/downloads/) or use your system's package manager. - -1. Install Seqera AI CLI: + - ```bash - pip install seqera - ``` +Install globally with npm: - :::tip - Consider using a virtual environment to avoid conflicts with other Python packages: +```bash +npm install -g seqera +``` - ```bash - python -m venv seqera-env - source seqera-env/bin/activate # On Windows: seqera-env\Scripts\activate - pip install seqera - ``` - ::: +Verify your installation: -1. Verify your installation: +```bash +seqera --help +``` - ```bash - seqera --version - ``` +:::tip +You can also install with yarn, pnpm, or bun: - You will see output similar to: - - ```console - seqera, version 0.1.0 - ``` +```bash +yarn global add seqera +# or +pnpm add -g seqera +# or +bun add -g seqera +``` +::: - - -To install Seqera AI CLI with [uv](https://docs.astral.sh/uv/): + -1. Install Seqera AI CLI as a tool: +Download the binary for your platform: - ```bash - uv tool install seqera - ``` +| Platform | Binary | +|----------|--------| +| macOS Apple Silicon | `seqera-darwin-arm64.tar.gz` | +| macOS Intel | `seqera-darwin-x64.tar.gz` | +| Linux x64 | `seqera-linux-x64.tar.gz` | - Alternatively, run Seqera AI CLI directly without installing: +Extract and add to your PATH: - ```bash - uvx seqera - ``` +```bash +# Example: macOS Apple Silicon +tar -xzf seqera-darwin-arm64.tar.gz +chmod +x seqera +sudo mv seqera /usr/local/bin/ +``` -1. Verify your installation: +Verify your installation: - ```bash - seqera --version - ``` - - You will see output similar to: - - ```console - seqera, version 0.1.0 - ``` +```bash +seqera --help +``` -### Upgrade +## Upgrade - + - ```bash - pip install --upgrade seqera - ``` +```bash +npm update -g seqera +``` - + - ```bash - uv tool upgrade seqera - ``` +Download the latest binary for your platform and replace the existing binary. -### Uninstall +## Uninstall - + - ```bash - pip uninstall seqera - ``` +```bash +npm uninstall -g seqera +``` - + + +Remove the `seqera` binary from your PATH: - ```bash - uv tool uninstall seqera - ``` +```bash +sudo rm /usr/local/bin/seqera +``` diff --git a/platform-cloud/docs/seqera-ai/use-cases.md b/platform-cloud/docs/seqera-ai/use-cases.md index ad966c8dc..625beec0d 100644 --- a/platform-cloud/docs/seqera-ai/use-cases.md +++ b/platform-cloud/docs/seqera-ai/use-cases.md @@ -19,6 +19,7 @@ Seqera AI is an intelligent command-line assistant that helps you build, run, an Seqera AI helps you develop, debug, and understand Nextflow pipelines with AI-powered analysis and code generation. + ![Use Seqera AI CLI to debug Nextflow pipeline scripts](./_images/pipeline-debug.gif)
@@ -69,6 +70,7 @@ Seqera AI helps you develop, debug, and understand Nextflow pipelines with AI-po Seqera AI can create containerized environments using Wave, without requiring you to write Dockerfiles. + ![Use Seqera AI CLI to build containers with Wave](./_images/building-wave-container.gif)
@@ -105,16 +107,28 @@ Customize your session with command-line options.
**Customize your session** -**Start in a specific directory**: +**Start with an initial query**: ```bash -seqera ai -w /path/to/project +seqera ai "list my pipelines" +``` + +**Continue your last session**: + +```bash +seqera ai -c +``` + +**Resume a specific session**: + +```bash +seqera ai -s ``` **Set approval mode for local commands**: ```bash -seqera ai -a full +seqera ai --approval-mode full ```
@@ -128,11 +142,11 @@ End your Seqera AI session when done. **To end your session**: -- Type `exit` or `quit` +- Type `/exit`, `/quit`, or `/q` - Press `Ctrl+C` :::note -Your conversation history is preserved for the session but not stored permanently. +Your conversation history is preserved. You can resume a session later with `seqera ai -c` to continue your most recent session. :::
@@ -142,9 +156,32 @@ Your conversation history is preserved for the session but not stored permanentl Seqera AI includes built-in slash commands for common workflows.
-**Use slash commands** +**TUI commands** + +These commands are handled locally by the CLI: + +| Command | Description | +|---------|-------------| +| `/help` | Show available commands | +| `/exit` (`/quit`, `/q`) | Exit the application | +| `/clear` | Clear conversation history | +| `/thinking` | Toggle thinking display | +| `/scroll` | Toggle auto-scroll | +| `/org` | Show current organization | +| `/lsp` | Show LSP server status | +| `/status` | Show system status | +| `/credits` | Show credit balance and usage | +| `/approval` | Show or set approval mode | +| `/feedback` | Open feedback form | +| `/help-community` | Open community help | +| `/stickers` | Get Seqera stickers | + +
+ +
+**AI commands** -**Type `/` to see all available commands**: +These commands are sent to the AI backend for processing: | Command | Description | |---------|-------------| @@ -270,6 +307,7 @@ The assistant can generate the exact Nextflow command with proper parameters for Use Seqera Platform capabilities to run and manage workflows at scale with AI assistance. + ![Use Seqera AI CLI to debug Platform run errors](./_images/sp-run-debug.gif)
@@ -299,6 +337,64 @@ Use Seqera Platform capabilities to run and manage workflows at scale with AI as
+## Headless mode + +Run Seqera AI in headless mode for scripting and automation. Output is sent to stdout instead of the interactive TUI. + +
+**Headless mode** + +**Run a query and pipe the output**: + +```bash +seqera ai --headless "list my pipelines" +``` + +**Include thinking messages in the output**: + +```bash +seqera ai --headless --show-thinking "debug my pipeline" +``` + +**Include tool calls in the output**: + +```bash +seqera ai --headless --show-tools "list my workflows" +``` + +:::note +Headless mode is also auto-detected when stdout is piped (e.g., `seqera ai "query" | grep "result"`). +::: + +
+ +## Session management + +Seqera AI preserves your conversation history across sessions. You can resume previous sessions to continue your work. + +
+**Session management** + +**Continue your most recent session**: + +```bash +seqera ai -c +``` + +**Continue with a follow-up question**: + +```bash +seqera ai -c "now run the pipeline with the test profile" +``` + +**Resume a specific session by ID**: + +```bash +seqera ai -s +``` + +
+

Learn more

- [Seqera AI CLI](index.md): Seqera AI CLI overview diff --git a/platform-cloud/docs/troubleshooting_and_faqs/seqera-ai.md b/platform-cloud/docs/troubleshooting_and_faqs/seqera-ai.md index b06598949..1a7cc4109 100644 --- a/platform-cloud/docs/troubleshooting_and_faqs/seqera-ai.md +++ b/platform-cloud/docs/troubleshooting_and_faqs/seqera-ai.md @@ -12,43 +12,42 @@ tags: [faq, help, seqera ai, troubleshooting] If you see `seqera: command not found` after installation: -1. Ensure the Python scripts directory is in your PATH: +1. Verify the installation location: ```bash - # Restart your terminal or run - source ~/.bashrc # or ~/.zshrc + which seqera ``` -1. Verify your installation location: +1. Ensure the npm global bin directory is in your PATH: ```bash - pip show seqera-ai - ``` - -##### Python version errors - -If you see errors about Python version: + # Check npm global bin directory + npm bin -g -1. Check you have Python 3.13+ installed: - - ```bash - python3 --version + # Restart your terminal or run + source ~/.bashrc # or ~/.zshrc ``` -1. If using multiple Python versions, specify the correct one: +1. If you installed the standalone binary, verify it is in a directory on your PATH: ```bash - python3.13 -m pip install seqera-ai + echo $PATH ``` -##### Permission errors +##### npm permission errors If you encounter permission errors during installation: -1. Use the `--user` flag with pip +1. Use the npm prefix option to install to a user-writable directory: ```bash - pip install --user seqera-ai + npm install -g seqera --prefix ~/.npm-global + ``` + +1. Add the directory to your PATH: + + ```bash + export PATH="$HOME/.npm-global/bin:$PATH" ``` ## Authentication @@ -71,14 +70,19 @@ If authentication times out: ##### Token storage errors -If you see keychain-related errors: +If you see errors related to credential storage: -1. Ensure your system keychain service is running -1. Check that you have permission to access the keychain +1. Check that you have write permissions to `~/.config/seqera-ai/` -:::note -The CLI will automatically fall back to file-based storage. -::: + ```bash + ls -la ~/.config/seqera-ai/ + ``` + +1. If the directory doesn't exist, create it: + + ```bash + mkdir -p ~/.config/seqera-ai + ``` ##### Session expired diff --git a/platform-enterprise_docs/enterprise-sidebar.json b/platform-enterprise_docs/enterprise-sidebar.json index fc9dad008..3e7169c47 100644 --- a/platform-enterprise_docs/enterprise-sidebar.json +++ b/platform-enterprise_docs/enterprise-sidebar.json @@ -52,6 +52,7 @@ "enterprise/configuration/pipeline_optimization" ] }, + "enterprise/install-seqera-ai", { "type": "category", "label": "Configuration", @@ -214,6 +215,19 @@ "pipeline-optimization/overview", "launch/advanced" ] + }, + { + "type": "category", + "label": "Seqera AI CLI", + "link": {"type": "doc", "id": "seqera-ai/index"}, + "collapsed": true, + "items": [ + "seqera-ai/get-started", + "seqera-ai/installation", + "seqera-ai/authentication", + "seqera-ai/command-approval", + "seqera-ai/use-cases" + ] }, { "type": "category", diff --git a/platform-enterprise_docs/enterprise/_images/seqera-ai-infrastructure.png b/platform-enterprise_docs/enterprise/_images/seqera-ai-infrastructure.png new file mode 100644 index 000000000..0736d487f Binary files /dev/null and b/platform-enterprise_docs/enterprise/_images/seqera-ai-infrastructure.png differ diff --git a/platform-enterprise_docs/enterprise/install-seqera-ai.md b/platform-enterprise_docs/enterprise/install-seqera-ai.md new file mode 100644 index 000000000..4f41c5648 --- /dev/null +++ b/platform-enterprise_docs/enterprise/install-seqera-ai.md @@ -0,0 +1,276 @@ +--- +title: "Seqera AI" +description: Install and configure Seqera AI for Seqera Platform Enterprise +date: "2026-02-03" +tags: [seqera-ai, installation, deployment, aws, helm] +--- + +:::caution +Seqera AI requires Seqera Platform Enterprise 25.3 or later. +::: + +Seqera AI is an intelligent command-line assistant that helps you build, run, and manage bioinformatics workflows. This guide describes how to deploy Seqera AI in Seqera Enterprise deployments on AWS. + +## Prerequisites + +Before you begin, you need: + +- **Seqera Enterprise 25.3+** deployed via [Helm](./platform-helm.md) +- **MySQL 8.0+ database** +- **API key** from a supported inference provider (see below) +- **MCP server** deployed and accessible from your cluster +- [Helm v3](https://helm.sh/docs/intro/install) and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed locally + +### AWS requirements + +- **AWS EKS cluster** with Seqera Platform deployed +- **Amazon RDS** for the MySQL database +- **AWS ALB Ingress Controller** installed in your cluster +- **TLS certificate** in AWS Certificate Manager +- **DNS** configured for the Seqera AI subdomain (e.g., `ai.platform.example.com`) + +## Supported inference providers + +Seqera AI uses Claude models from Anthropic. The following inference providers are supported for Enterprise deployments: + +| Inference provider | Description | +|--------------------|-------------| +| **Anthropic API** | Direct access to Claude models via Anthropic's API ([console.anthropic.com](https://console.anthropic.com/)) | +| **AWS Bedrock** | Access Claude models through [AWS Bedrock](https://aws.amazon.com/bedrock/) in your AWS account | + +## Architecture + +Seqera AI connects your local CLI environment to your Platform resources through a secure backend service: + +![Seqera AI infrastructure architecture](./_images/seqera-ai-infrastructure.png) + +**Components:** + +| Component | Description | +|-----------|-------------| +| **Agent backend** | FastAPI service that orchestrates AI interactions. Deployed as a Helm subchart alongside Platform. | +| **MCP server** | Model Context Protocol server providing Platform-aware tools (workflows, datasets, compute environments). | +| **MySQL database** | Dedicated database for session state and conversation history. **Separate from Platform database**. | + +**Flow:** + +1. Users authenticate via `seqera login`, which initiates OIDC authentication with Platform. +1. The CLI creates a session with the agent backend, passing the Platform access token. +1. The agent backend validates tokens against Platform's `/user-info` endpoint. +1. User prompts are processed by the inference provider, which can invoke Platform tools via MCP. +1. MCP tools execute Platform operations using the user's credentials. +1. Results stream back to the CLI via Server-Sent Events (SSE). + +## Provision the database + +Seqera AI requires a dedicated MySQL database separate from the Platform database. + +1. Create a MySQL 8.0+ instance in Amazon RDS: + + - **Engine**: MySQL 8.0 + - **Instance class**: `db.t3.medium` or larger + - **Storage**: 20 GB minimum with autoscaling enabled + - **Security group**: Allow inbound MySQL (port 3306) from EKS cluster + +1. Connect to the database and create the Seqera AI database and user: + + ```sql + CREATE DATABASE seqera_ai; + CREATE USER 'seqera_ai'@'%' IDENTIFIED BY ''; + GRANT ALL PRIVILEGES ON seqera_ai.* TO 'seqera_ai'@'%'; + FLUSH PRIVILEGES; + ``` + +## Create Kubernetes secrets + +1. Create a secret for the inference provider API key: + + ```bash + kubectl create secret generic anthropic-secret \ + --namespace \ + --from-literal=ANTHROPIC_API_KEY= + ``` + +1. Create a secret for the database credentials: + + ```bash + kubectl create secret generic seqera-ai-db-credentials \ + --namespace \ + --from-literal=DB_PASSWORD= + ``` + +## Configure Helm values + +Add the following configuration to your Platform Helm values file: + +```yaml +# Global configuration +global: + platformExternalDomain: platform.example.com + mcpExternalDomain: mcp.example.com + +# Enable Seqera AI agent backend +agent-backend: + enabled: true + + agentBackend: + replicaCount: 1 + + # Anthropic API key + anthropicApiKey: + existingSecretName: "anthropic-secret" + existingSecretKey: "ANTHROPIC_API_KEY" + + # Database configuration + database: + host: "seqera-ai-db.xxxxx.us-east-1.rds.amazonaws.com" + port: 3306 + name: "seqera_ai" + username: "seqera_ai" + existingSecretName: "seqera-ai-db-credentials" + existingSecretKey: "DB_PASSWORD" + dialect: mysql + + # AWS ALB ingress + ingress: + enabled: true + ingressClassName: "alb" + path: "/*" + annotations: + alb.ingress.kubernetes.io/scheme: internet-facing + alb.ingress.kubernetes.io/target-type: ip + alb.ingress.kubernetes.io/certificate-arn: "arn:aws:acm:::certificate/" + alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]' + alb.ingress.kubernetes.io/ssl-redirect: "443" + alb.ingress.kubernetes.io/healthcheck-path: /health + tls: + - hosts: + - 'ai.{{ .Values.global.platformExternalDomain }}' +``` + +## Deploy + +1. Upgrade your Platform Helm release: + + ```bash + helm upgrade my-release oci://public.cr.seqera.io/charts/platform \ + --version \ + --namespace \ + --values my-values.yaml + ``` + +1. Wait for the agent-backend pod to be ready: + + ```bash + kubectl get pods -n -l app.kubernetes.io/component=agent-backend -w + ``` + +1. Verify the deployment: + + ```bash + kubectl logs -n -l app.kubernetes.io/component=agent-backend --tail=50 + ``` + +## Configure DNS + +Create a DNS record pointing to the ALB for the Seqera AI endpoint: + +- **Record**: `ai.platform.example.com` +- **Type**: CNAME (or Alias for Route 53) +- **Value**: ALB DNS name (find with `kubectl get ingress -n `) + +## Verify the installation + +1. Check the health endpoint: + + ```bash + curl -I https://ai.platform.example.com/health + ``` + + You should receive a `200 OK` response. + +1. Test CLI connectivity: + + ```bash + export SEQERA_AI_BACKEND_URL=https://ai.platform.example.com + seqera login + seqera ai + ``` + +## Environment variables reference + +### Required + +| Variable | Description | +|----------|-------------| +| `SEQERA_PLATFORM_API_URL` | Platform API URL (e.g., `https://platform.example.com/api`) | +| `SEQERA_MCP_URL` | MCP server URL (e.g., `https://mcp.example.com/mcp`) | +| `ANTHROPIC_API_KEY` | API key for inference provider | +| `AGENT_BACKEND_DB_HOST` | MySQL database hostname | +| `AGENT_BACKEND_DB_NAME` | MySQL database name | +| `AGENT_BACKEND_DB_USER` | MySQL database username | +| `AGENT_BACKEND_DB_PASSWORD` | MySQL database password | + +### Optional + +| Variable | Description | Default | +|----------|-------------|---------| +| `ANTHROPIC_MODEL` | Model to use | `claude-sonnet-4-20250514` | +| `AGENT_BACKEND_DB_PORT` | MySQL port | `3306` | +| `SESSION_TIMEOUT_SECONDS` | Session timeout | `86400` (24 hours) | +| `MAX_SESSIONS_PER_USER` | Max concurrent sessions per user | `10` | +| `SESSION_RETENTION_DAYS` | Days to retain session data | `14` | + +## Helm values reference + +For the full list of configuration options, see the [agent-backend chart documentation](https://github.com/seqeralabs/helm-charts/tree/master/platform/charts/agent-backend). + +### Global + +| Value | Description | Default | +|-------|-------------|---------| +| `global.platformExternalDomain` | Domain where Seqera Platform listens | `example.com` | +| `global.mcpExternalDomain` | Domain where MCP server listens | `mcp.example.com` | + +### Agent backend + +| Value | Description | Default | +|-------|-------------|---------| +| `agentBackend.replicaCount` | Number of replicas | `1` | +| `agentBackend.image.registry` | Image registry | `cr.seqera.io` | +| `agentBackend.image.repository` | Image repository | `private/nf-tower-enterprise/agent-backend` | +| `agentBackend.anthropicApiKey.existingSecretName` | Existing secret with API key | `""` | +| `agentBackend.anthropicApiKey.existingSecretKey` | Key in the secret | `ANTHROPIC_API_KEY` | + +### Database + +| Value | Description | Default | +|-------|-------------|---------| +| `database.host` | MySQL hostname | `""` | +| `database.port` | MySQL port | `3306` | +| `database.name` | MySQL database name | `""` | +| `database.username` | MySQL username | `""` | +| `database.existingSecretName` | Existing secret with DB password | `""` | +| `database.existingSecretKey` | Key in the secret | `DB_PASSWORD` | + +### Ingress + +| Value | Description | Default | +|-------|-------------|---------| +| `ingress.enabled` | Enable ingress | `false` | +| `ingress.path` | Ingress path (use `/*` for AWS ALB) | `/` | +| `ingress.ingressClassName` | Ingress class name | `""` | +| `ingress.annotations` | Ingress annotations | `{}` | +| `ingress.tls` | TLS configuration | `[]` | + +## Security considerations + +- **Token validation**: Every request validates the user's Platform token +- **User isolation**: Sessions are isolated by user ID +- **Credential passthrough**: MCP tools use the user's credentials for Platform operations +- **No credential storage**: The agent backend does not store user credentials +- **TLS required**: All communication should use HTTPS + +## Next steps + +- See [Use cases](../seqera-ai/use-cases.md) for CLI usage. diff --git a/platform-enterprise_docs/seqera-ai/_images/building-wave-container.gif b/platform-enterprise_docs/seqera-ai/_images/building-wave-container.gif new file mode 100644 index 000000000..3899bd334 Binary files /dev/null and b/platform-enterprise_docs/seqera-ai/_images/building-wave-container.gif differ diff --git a/platform-enterprise_docs/seqera-ai/_images/pipeline-debug.gif b/platform-enterprise_docs/seqera-ai/_images/pipeline-debug.gif new file mode 100644 index 000000000..217062213 Binary files /dev/null and b/platform-enterprise_docs/seqera-ai/_images/pipeline-debug.gif differ diff --git a/platform-enterprise_docs/seqera-ai/_images/rnaseq-alignment-methods.gif b/platform-enterprise_docs/seqera-ai/_images/rnaseq-alignment-methods.gif new file mode 100644 index 000000000..e74693433 Binary files /dev/null and b/platform-enterprise_docs/seqera-ai/_images/rnaseq-alignment-methods.gif differ diff --git a/platform-enterprise_docs/seqera-ai/_images/sp-run-debug.gif b/platform-enterprise_docs/seqera-ai/_images/sp-run-debug.gif new file mode 100644 index 000000000..fae9aab8b Binary files /dev/null and b/platform-enterprise_docs/seqera-ai/_images/sp-run-debug.gif differ diff --git a/platform-enterprise_docs/seqera-ai/authentication.md b/platform-enterprise_docs/seqera-ai/authentication.md new file mode 100644 index 000000000..3dca27f47 --- /dev/null +++ b/platform-enterprise_docs/seqera-ai/authentication.md @@ -0,0 +1,114 @@ +--- +title: "Authentication" +description: "Login, logout, and session management for Seqera AI CLI" +date: "15 Dec 2025" +tags: [seqera-ai, cli, authentication, login] +--- + +:::caution Seqera AI CLI is in beta +Seqera AI CLI is currently in beta. Features and commands may change as we continue to improve the product. +::: + +:::note +Seqera Cloud users receive $20 in free credits to get started with Seqera AI. [Contact us](https://seqera.io/platform/seqera-ai/request-credits/) for additional credits. +::: + +Seqera AI uses your Seqera Platform account for authentication. This page describes authentication concepts and step-by-step instructions for managing your sessions. + +## Authenticating Seqera AI + +### Log in + +To authenticate with your Seqera Platform account, run: + +```bash +seqera login +``` + +This will: + +1. Open your default browser to the Seqera login page +1. Prompt you to sign in with your Seqera Platform credentials +1. Automatically capture the authentication token +1. Display a success message in your terminal + + ``` + [Login] Starting Seqera CLI authentication... + [Login] ✓ Authentication successful! + [Login] ✓ Organization set: + ``` + +### View session status + +To view your current session status, use the `/status` command inside the TUI: + +``` +/status +``` + +This shows your authentication status and organization details. + +### Add access tokens for automation + +For automated environments, you can provide a Seqera Platform access token directly using the `SEQERA_ACCESS_TOKEN` environment variable: + +```bash +export SEQERA_ACCESS_TOKEN= +seqera ai +``` + +When this environment variable is set, the CLI skips the OAuth login flow and uses the provided token directly. + +### Log out + +To sign out from the current session, run: + +```bash +seqera logout +``` + +This command revokes your current authentication token and removes locally stored credentials. You will need to re-authenticate on next use. + +## Organization management + +Seqera AI CLI supports managing your organization selection for billing. Use the `seqera org` command to view and switch organizations. + +**View current organization**: + +```bash +seqera org +``` + +**List all organizations**: + +```bash +seqera org list +``` + +**Switch organization**: + +```bash +seqera org switch +``` + +**Clear organization selection**: + +```bash +seqera org clear +``` + +## Token refresh + +Seqera AI CLI automatically refreshes your authentication token when needed. You are not required to log in again unless: + +- You explicitly log out +- Your refresh token expires (typically after extended inactivity) +- Your Seqera Platform account permissions change + +## Learn more + +- [Seqera AI CLI](index.md): Seqera AI CLI overview +- [Installation](./installation.mdx): Detailed installation instructions +- [Command approval](./command-approval.md): Control which commands run automatically +- [Use cases](./use-cases.md): Seqera AI use cases +- [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors diff --git a/platform-enterprise_docs/seqera-ai/command-approval.md b/platform-enterprise_docs/seqera-ai/command-approval.md new file mode 100644 index 000000000..a3b969c28 --- /dev/null +++ b/platform-enterprise_docs/seqera-ai/command-approval.md @@ -0,0 +1,234 @@ +--- +title: "Command approval" +description: "Control which local commands require user approval in Seqera AI" +date: "15 Dec 2025" +tags: [seqera-ai, cli, approval, security] +--- + +:::caution Seqera AI CLI is in beta +Seqera AI CLI is currently in beta. Features and commands may change as we continue to improve the product. +::: + +:::note +Seqera Cloud users receive $20 in free credits to get started with Seqera AI. [Contact us](https://seqera.io/platform/seqera-ai/request-credits/) for additional credits. +::: + +Seqera AI can execute local commands and edit files in your environment. This page explains approval modes that control which operations run automatically versus which require your permission, including dangerous commands, workspace boundaries, and best practices. + +## Approval prompts + +When a command requires approval, you will see a prompt similar to: + +``` +APPROVAL REQUIRED (default mode) +Command: rm -rf ./build/ + +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject + +Press 1, 2, or 3 to choose +``` + +You can: + +- **1**: Run the command once (or press Enter) +- **2**: Run the command and auto-approve all commands for the rest of the session +- **3**: Reject the command (or press Escape) + +## Approval modes + +Approval modes control which local commands Seqera AI can execute automatically and which require your explicit approval. This provides a balance between convenience and safety when working with local files and commands. + +There are three approval modes: + +| Mode | Description | Best for | +|------|-------------|----------| +| **basic** | Only safe, read-only commands run automatically | Maximum security | +| **default** | Safe commands and workspace file edits run automatically | Typical development | +| **full** | Everything except dangerous commands runs automatically | Experienced users | + +You can set the approval mode when starting the CLI: + +```bash +seqera ai --approval-mode full +``` + +Or change it during a session using the `/approval` TUI command: + +``` +/approval basic +``` + +### Basic + +**Rule**: Only safe, read-only commands run automatically. Everything else requires approval. + +This is the most restrictive mode. The assistant can only auto-execute commands that view information without making changes. + +**Auto-executes**: + +- `cat` - View file contents +- `ls` - List directory contents +- `pwd` - Show current directory +- `head` - View file beginning +- `tail` - View file end +- `tree` - Display directory tree +- `echo` - Print text (without file redirection) +- `date` - Show current date/time +- `whoami` - Show current user +- `env` - Display environment variables +- `printenv` - Print environment variables +- `stat` - Show file status +- `uptime` - Show system uptime + +**Requires approval**: All other commands, including file edits, directory creation, and any other command execution. Safe commands that include file redirections (e.g., `echo "hello" > file.txt`) also require approval. + +**Use when**: You want maximum control and visibility over every action the assistant takes. + +**Examples**: + +``` +> Create a new file called test.txt with "hello world" + +APPROVAL REQUIRED (basic mode) +Command: Write ./test.txt + +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject +``` + +### Default + +**Rule**: Safe commands and file operations within your workspace run automatically. All other commands require approval. + +This is the recommended mode for most users. It allows productive workflow while protecting system files and preventing destructive operations. + +**Auto-executes**: +- All safe commands from basic mode (without file redirections) +- File edits **within your current workspace**: + - Creating files (`touch`, file creation) + - Editing files (text modifications) + - Creating directories (`mkdir`) + - Copying files (`cp` within workspace) + - Moving files (`mv` within workspace) + +**Requires approval**: +- File operations **outside your workspace** +- All dangerous commands (see below) +- Commands with file redirects to paths outside workspace +- All other commands (e.g., `curl`, `wget`, `git`, `npm`, `python`, etc.) + +**Use when**: You're doing typical development work and want convenience without compromising safety. + +**Examples**: + +``` +> Create a new file called test.txt with "hello world" + +Created ./test.txt +``` + +File creation in the workspace runs automatically. + +``` +> Edit /etc/hosts + +APPROVAL REQUIRED (default mode) +Command: Edit /etc/hosts + +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject +``` + +Editing outside the workspace requires approval. + + +### Full + +**Rule**: Everything runs automatically except explicitly dangerous commands. + +This is the most permissive mode. Use it when you fully trust the assistant's actions and want minimal interruption. + +**Auto-executes**: All commands except those on the dangerous list. + +**Requires approval**: Only dangerous commands (see below). + +**Use when**: You're an experienced user comfortable with automated command execution, or when working in an isolated/disposable environment. + +## Dangerous commands + +These commands **always require approval** in any mode: + +| Command | Risk | +|---------|------| +| `rm` | Delete files/directories | +| `chmod` | Change file permissions | +| `chown` | Change file ownership | +| `kill` | Terminate processes | +| `killall` | Terminate multiple processes | +| `pkill` | Kill processes by name | +| `sudo` | Execute as superuser | +| `dd` | Low-level data operations | +| `mount` | Mount filesystems | +| `umount` | Unmount filesystems | +| `mkfs` | Create filesystems | +| `reboot` | Restart system | +| `shutdown` | Power off system | + +**Examples**: + +``` +> Create files and directories as needed + +Created ./src/utils.py +Created ./tests/test_utils.py +Created ./config/settings.json +``` + +Most operations run without prompts. + +``` +> Delete the build directory + +APPROVAL REQUIRED (full mode) +Command: rm -rf ./build/ + +[1] Yes, approve this command +[2] Always approve this session +[3] No, reject +``` + +Dangerous commands still require approval. + +## Workspace boundaries + +In **default** mode, the "workspace" is your current working directory and its subdirectories. File operations are evaluated as: + +- **Inside workspace**: `/path/to/workspace/src/file.txt` - auto-executes +- **Outside workspace**: `/etc/config` or `~/other-project/file.txt` - requires approval + +The workspace is set to your current directory when you start the CLI: + +```bash +# Workspace is /home/user/my-project +cd /home/user/my-project +seqera ai +``` + +## Best practices + +- **Start with default mode**: It provides a good balance for most workflows +- **Use basic mode for unfamiliar projects**: When exploring new codebases +- **Reserve full mode for trusted contexts**: Disposable environments or well-understood tasks +- **Review dangerous command prompts carefully**: These commands can have significant impact + +## Learn more + +- [Seqera AI CLI](index.md): Seqera AI CLI overview +- [Installation](./installation): Detailed installation instructions +- [Authentication](./authentication): Log in, log out, and session management +- [Use cases](./use-cases.md): Seqera AI use cases +- [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors diff --git a/platform-enterprise_docs/seqera-ai/get-started.md b/platform-enterprise_docs/seqera-ai/get-started.md new file mode 100644 index 000000000..0b8a2504b --- /dev/null +++ b/platform-enterprise_docs/seqera-ai/get-started.md @@ -0,0 +1,63 @@ +--- +title: "Get started" +description: "AI-powered assistant for bioinformatics workflows and Seqera Platform" +date: "2025-12-16" +tags: [seqera-ai, cli, ai] +--- + +:::caution Seqera AI CLI is in beta +Seqera AI CLI is currently in beta. Features and commands may change as we continue to improve the product. +::: + +:::note +Seqera Cloud users receive $20 in free credits to get started with Seqera AI. [Contact us](https://seqera.io/platform/seqera-ai/request-credits/) for additional credits. +::: + +## Get started + +To get started with Seqera AI: + +1. Install the Seqera AI CLI: + + ```bash + npm install -g seqera + ``` + + See [Installation](./installation.mdx) for a comprehensive installation guide. + +1. Log in to your Seqera account: + + ```bash + seqera login + ``` + + See [Authentication](./authentication.md) for a comprehensive authentication guide. + + +1. Start Seqera AI: + + ```bash + seqera ai + ``` + + You can also start with an initial query: + + ```bash + seqera ai "list my pipelines" + ``` + +1. Run your first prompt: + + ``` + /debug + ``` + + See [Use cases](./use-cases.md) for a comprehensive list of use cases. + +## Learn more + +- [Installation](./installation.mdx): Detailed installation instructions +- [Authentication](./authentication.md): Log in, log out, and session management +- [Command approval](./command-approval.md): Control which commands run automatically +- [Use cases](./use-cases.md): Seqera AI CLI use cases +- [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors diff --git a/platform-enterprise_docs/seqera-ai/index.md b/platform-enterprise_docs/seqera-ai/index.md new file mode 100644 index 000000000..90e7b2ff9 --- /dev/null +++ b/platform-enterprise_docs/seqera-ai/index.md @@ -0,0 +1,72 @@ +--- +title: "Seqera AI CLI" +description: "AI-powered assistant for bioinformatics workflows and Seqera Platform" +date: "2025-12-15" +tags: [seqera-ai, cli, ai] +--- + +:::caution Seqera AI CLI is in beta +Seqera AI CLI is currently in beta. Features and commands may change as we continue to improve the product. +::: + +:::note +Seqera Cloud users receive $20 in free credits to get started with Seqera AI. [Contact us](https://seqera.io/platform/seqera-ai/request-credits/) for additional credits. +::: + +Seqera AI CLI is an intelligent command-line assistant that helps you build, run, and manage bioinformatics workflows. Powered by advanced AI, it provides an interactive terminal experience for working with Nextflow pipelines and Seqera Platform. + +Seqera AI has access to: + +- **Your Seqera Platform workspace**: View and manage workflows, pipelines, and data through your authenticated account +- **Your local environment**: Execute commands and edit files in your working directory (with configurable approval controls) +- **AI capabilities**: Natural language understanding, code generation, and intelligent suggestions + +## Seqera AI features + +### Natural language interface + +Interact with Seqera Platform using plain English. Ask questions, launch workflows, and manage pipelines through conversational commands. + +### Workflow management + +Launch, monitor, and debug Nextflow workflows directly from your terminal. Get real-time status updates, view logs, and analyze run metrics. + +### Pipeline development + +Generate Nextflow configurations, create pipeline schemas, and convert scripts from other workflow languages (WDL, Snakemake) to Nextflow. + +### nf-core integration + +Search and discover nf-core modules, get detailed execution information, and access ready-to-run Nextflow commands for over 1,000 standardized bioinformatics tools. + +### Data management + +Browse cloud storage through data links, manage datasets, generate download and upload URLs, and access reference genomes and sequencing data. + +### Wave containers + +Build containerized environments on-the-fly with conda packages, pip packages, or custom Docker images. Create reproducible containers for your bioinformatics tools without writing Dockerfiles. + +### Local file operations + +Edit files, run commands, and manage your local development environment with AI assistance and configurable approval modes. + +### LSP code intelligence + +Real-time error detection and AI-powered code navigation for Nextflow, Python, and R files in your workspace. + +### Session management + +Resume previous sessions to continue your work. Use `seqera ai -c` to continue your most recent session or `seqera ai -s ` to resume a specific session. + +### Seqera Platform integration + +Full access to Platform capabilities including compute environments, datasets, data links, and workspace management. + +## Learn more + +- [Installation](./installation.mdx): Detailed installation instructions +- [Authentication](./authentication.md): Log in, log out, and session management +- [Command approval](./command-approval.md): Control which commands run automatically +- [Use cases](./use-cases.md): Seqera AI CLI use cases +- [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors diff --git a/platform-enterprise_docs/seqera-ai/installation.mdx b/platform-enterprise_docs/seqera-ai/installation.mdx new file mode 100644 index 000000000..2c1f1b7af --- /dev/null +++ b/platform-enterprise_docs/seqera-ai/installation.mdx @@ -0,0 +1,127 @@ +--- +title: "Installation" +description: "Install and configure Seqera AI CLI" +date: "15 Dec 2025" +tags: [seqera-ai, cli, installation] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +:::caution Seqera AI CLI is in beta +Seqera AI CLI is currently in beta. Features and commands may change as we continue to improve the product. +::: + +:::note +Seqera Cloud users receive $20 in free credits to get started with Seqera AI. [Contact us](https://seqera.io/platform/seqera-ai/request-credits/) for additional credits. +::: + +## Requirements + +- macOS (Apple Silicon or Intel) or Linux x64 +- A Seqera Platform account ([sign up for free](https://cloud.seqera.io)) +- An internet connection + +## Install + + + + +Install globally with npm: + +```bash +npm install -g seqera +``` + +Verify your installation: + +```bash +seqera --help +``` + +:::tip +You can also install with yarn, pnpm, or bun: + +```bash +yarn global add seqera +# or +pnpm add -g seqera +# or +bun add -g seqera +``` +::: + + + + +Download the binary for your platform: + +| Platform | Binary | +|----------|--------| +| macOS Apple Silicon | `seqera-darwin-arm64.tar.gz` | +| macOS Intel | `seqera-darwin-x64.tar.gz` | +| Linux x64 | `seqera-linux-x64.tar.gz` | + +Extract and add to your PATH: + +```bash +# Example: macOS Apple Silicon +tar -xzf seqera-darwin-arm64.tar.gz +chmod +x seqera +sudo mv seqera /usr/local/bin/ +``` + +Verify your installation: + +```bash +seqera --help +``` + + + + +## Upgrade + + + + +```bash +npm update -g seqera +``` + + + + +Download the latest binary for your platform and replace the existing binary. + + + + +## Uninstall + + + + +```bash +npm uninstall -g seqera +``` + + + + +Remove the `seqera` binary from your PATH: + +```bash +sudo rm /usr/local/bin/seqera +``` + + + + +## Learn more + +- [Seqera AI CLI](index.md): Seqera AI CLI overview +- [Authentication](./authentication.md): Login, logout, and session management +- [Command approval](./command-approval.md): Control which commands run automatically +- [Use cases](./use-cases.md): Seqera AI CLI use cases +- [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors diff --git a/platform-enterprise_docs/seqera-ai/use-cases.md b/platform-enterprise_docs/seqera-ai/use-cases.md new file mode 100644 index 000000000..625beec0d --- /dev/null +++ b/platform-enterprise_docs/seqera-ai/use-cases.md @@ -0,0 +1,404 @@ +--- +title: "Use cases" +description: "Learn how to use Seqera AI CLI for bioinformatics workflows, pipeline development, and data management" +date: "2025-12-15" +tags: [seqera-ai, cli, ai, use cases] +--- + +:::caution Seqera AI CLI is in beta +Seqera AI CLI is currently in beta. Features and commands may change as we continue to improve the product. +::: + +:::note +Seqera Cloud users receive $20 in free credits to get started with Seqera AI. [Contact us](https://seqera.io/platform/seqera-ai/request-credits/) for additional credits. +::: + +Seqera AI is an intelligent command-line assistant that helps you build, run, and manage bioinformatics workflows. The following sections describe several common use cases. + +## Work with Nextflow + +Seqera AI helps you develop, debug, and understand Nextflow pipelines with AI-powered analysis and code generation. + + +![Use Seqera AI CLI to debug Nextflow pipeline scripts](./_images/pipeline-debug.gif) + +
+**Working with Nextflow** + +**Understand your pipeline structure**: + +``` +> Show me the structure of main.nf +``` + +``` +> What processes are defined in this pipeline? +``` + +**Generate a `nextflow.config` file**: + +``` +> /config +``` + +**Debug your pipeline**: + +``` +> /debug +``` + +``` +> Why is my pipeline failing? +``` + +**Generate a schema (`nextflow_schema.json`) file**: + +``` +> /schema +``` + + +**Convert scripts to Nextflow**: + +``` +> /convert-python-script +``` + +
+ +## Build containers with Wave + +Seqera AI can create containerized environments using Wave, without requiring you to write Dockerfiles. + + +![Use Seqera AI CLI to build containers with Wave](./_images/building-wave-container.gif) + +
+**Building containers with Wave** + +**Create a container with conda packages**: + +``` +> Create a container with samtools and bwa from bioconda +``` + +**Create a container with pip packages**: + +``` +> Build a container with pandas, numpy, and scikit-learn +``` + +**Get a container for a specific tool**: + +``` +> I need a container with FastQC version 0.12.1 +``` + +:::note +The assistant will generate a Wave container URL that you can use directly in your Nextflow pipelines or pull with Docker. +::: + +
+ +## Customize your session + +Customize your session with command-line options. + +
+**Customize your session** + +**Start with an initial query**: + +```bash +seqera ai "list my pipelines" +``` + +**Continue your last session**: + +```bash +seqera ai -c +``` + +**Resume a specific session**: + +```bash +seqera ai -s +``` + +**Set approval mode for local commands**: + +```bash +seqera ai --approval-mode full +``` + +
+ +## Exit the assistant + +End your Seqera AI session when done. + +
+**Exit the assistant** + +**To end your session**: + +- Type `/exit`, `/quit`, or `/q` +- Press `Ctrl+C` + +:::note +Your conversation history is preserved. You can resume a session later with `seqera ai -c` to continue your most recent session. +::: + +
+ +## Use slash commands + +Seqera AI includes built-in slash commands for common workflows. + +
+**TUI commands** + +These commands are handled locally by the CLI: + +| Command | Description | +|---------|-------------| +| `/help` | Show available commands | +| `/exit` (`/quit`, `/q`) | Exit the application | +| `/clear` | Clear conversation history | +| `/thinking` | Toggle thinking display | +| `/scroll` | Toggle auto-scroll | +| `/org` | Show current organization | +| `/lsp` | Show LSP server status | +| `/status` | Show system status | +| `/credits` | Show credit balance and usage | +| `/approval` | Show or set approval mode | +| `/feedback` | Open feedback form | +| `/help-community` | Open community help | +| `/stickers` | Get Seqera stickers | + +
+ +
+**AI commands** + +These commands are sent to the AI backend for processing: + +| Command | Description | +|---------|-------------| +| `/config` | Generate a nextflow.config file | +| `/schema` | Generate a Nextflow schema | +| `/debug` | Run nextflow lint and preview | +| `/debug-last-run` | Debug the last local run | +| `/debug-last-run-on-seqera` | Debug the last Platform run | +| `/migrate-from-wdl` | Convert WDL to Nextflow | +| `/migrate-from-snakemake` | Convert Snakemake to Nextflow | +| `/convert-python-script` | Convert Python script to Nextflow | +| `/convert-r-script` | Convert R script to Nextflow | +| `/convert-jupyter-notebook` | Convert Jupyter notebook to Nextflow | +| `/write-nf-test` | Write nf-tests for your pipeline | + +
+ +## Work with data + +Seqera AI helps you manage data through Platform data links and access reference datasets. + +
+**Working with data** + +**Browse data links**: + +``` +> List my data links +``` + +``` +> Show me the contents of my S3 data link +``` + +**Download and upload files**: + +``` +> Generate a download URL for results/final_report.html +``` + +``` +> Upload my local results to the data link +``` + +**Access reference data**: + +``` +> Find the human reference genome GRCh38 +``` + +``` +> Search for RNA-Seq test data +``` + +
+ +## Work with local files + +Seqera AI can interact with files in your current working directory. + +
+**Work with local files** + +**Start the assistant from your project folder**: + +```bash +cd /path/to/your/project +seqera ai +``` + +**Then, ask the assistant to help with local tasks**: + +``` +> Show me the structure of main.nf +``` + +``` +> Add a new process to handle quality control +``` + +:::note +Local file operations are controlled by [approval modes](./command-approval.md#approval-modes). By default, the assistant will ask for your approval before making changes outside your working directory or running potentially dangerous commands. +::: + +
+ +## Work with nf-core modules + +Seqera AI provides access to over 1,000 nf-core modules for common bioinformatics tasks. + +
+**Working with nf-core modules** + +**Search for modules**: + +``` +> Find nf-core modules for sequence alignment +``` + +``` +> What modules are available for variant calling? +``` + +**Get module details**: + +``` +> Show me how to use the nf-core/bwa/mem module +``` + +**Run a module**: + +``` +> Run FastQC on my FASTQ files +``` + +:::note +The assistant can generate the exact Nextflow command with proper parameters for your data. +::: + +
+ +## Work with Seqera Platform + +Use Seqera Platform capabilities to run and manage workflows at scale with AI assistance. + + +![Use Seqera AI CLI to debug Platform run errors](./_images/sp-run-debug.gif) + +
+**Working with Seqera Platform** + +**List your workflows**: + +``` +> List my recent workflows +``` + +**Launch a pipeline**: + +``` +> Launch the nf-core/rnaseq pipeline with the test profile +``` + +**Debug failed runs**: + +``` +> Why did my last workflow fail? +``` + +``` +> Get the logs for the failed task in my last run +``` + +
+ +## Headless mode + +Run Seqera AI in headless mode for scripting and automation. Output is sent to stdout instead of the interactive TUI. + +
+**Headless mode** + +**Run a query and pipe the output**: + +```bash +seqera ai --headless "list my pipelines" +``` + +**Include thinking messages in the output**: + +```bash +seqera ai --headless --show-thinking "debug my pipeline" +``` + +**Include tool calls in the output**: + +```bash +seqera ai --headless --show-tools "list my workflows" +``` + +:::note +Headless mode is also auto-detected when stdout is piped (e.g., `seqera ai "query" | grep "result"`). +::: + +
+ +## Session management + +Seqera AI preserves your conversation history across sessions. You can resume previous sessions to continue your work. + +
+**Session management** + +**Continue your most recent session**: + +```bash +seqera ai -c +``` + +**Continue with a follow-up question**: + +```bash +seqera ai -c "now run the pipeline with the test profile" +``` + +**Resume a specific session by ID**: + +```bash +seqera ai -s +``` + +
+ +

Learn more

+ +- [Seqera AI CLI](index.md): Seqera AI CLI overview +- [Installation](./installation.mdx): Detailed installation instructions +- [Authentication](./authentication.md): Log in, log out, and session management +- [Command approval](./command-approval.md): Control which commands run automatically +- [Troubleshooting](../troubleshooting_and_faqs/seqera-ai.md): Troubleshoot common errors