# Access SeekrFlow Source: https://docs.seekr.com/flow/app/access-seekrflow System requirements, account setup, and sign-in instructions for SeekrFlow. **Self-hosted deployments** Your administrator provides your SeekrFlow URL and may create accounts on your behalf or use a different authentication method. Contact your administrator for access instructions. ## System requirements SeekrFlow runs entirely in your web browser. No software installation is required. | Requirement | Details | | ------------ | ------------------------------------------------------------------------- | | Device | Desktop only | | Screen width | 1024px minimum | | Browser | Chrome, Firefox, Safari, or Edge (current version and two prior versions) | | Internet | Stable internet connection | ## Create your account Go to [apps.seekr.com/flow](https://apps.seekr.com/flow). Click **Create Account**. Fill in your name, role, industry, email, and password. Review and agree to the Privacy Policy and Terms and Conditions. Click **Sign Up**. Check your email for a confirmation message and confirm within one hour. After confirming your email, sign in to request access or contact sales to get started with SeekrFlow. ## Sign in Go to [apps.seekr.com/flow](https://apps.seekr.com/flow). Enter your **Email** and **Password**. Click **Sign In**. The Dashboard appears after a successful sign-in. ## Sign out Click your profile icon in the top-right corner. Select **Sign Out**. Sign out when you finish working, especially on shared devices. # Agent Builder Source: https://docs.seekr.com/flow/app/agent-builder Create and manage agents in the SeekrFlow user interface. Agent Builder provides a no-code interface for building and managing agents and tools. ## In this section * [Agents](/flow/app/agents) – Create and manage agents * [Tool Library](/flow/app/tool-library) – Create and manage custom tools for your agents # Agents Source: https://docs.seekr.com/flow/app/agents Create and manage agents in the SeekrFlow user interface. An agent is an AI system that reasons through problems and executes tasks autonomously. Agents are configured by specifying models, tools, instructions, and reasoning approach—providing everything needed to accomplish tasks from simple workflows to complex, open-ended objectives. For more information, see [Agents](/flow/components/agents). To build agents using the SDK, see [Agents SDK reference](/flow/sdk/agents). ## In this section * [Create an agent](/flow/app/create-an-agent) – Build a new agent with models and tools * [Manage agents](/flow/app/manage-agents) – View, activate, and deactivate agents # AI-Ready Data Source: https://docs.seekr.com/flow/app/ai-ready-data Generate training data from your unstructured documents to fine-tune a model. The AI-Ready Data page lists your data generation jobs and their current status. Each job processes your uploaded documents and generates a training dataset you can use to fine-tune a model. AI-Ready Data Jobs list view showing job IDs, statuses, and creation dates. ## Create an AI-Ready Data job Navigate to **Data Engine > AI-Ready Data**. Click **+ Create Job**. In the **Define Goal and Upload Data Sources** step: * Enter your fine-tuning goal. Describe the outcome you want to achieve with your fine-tuned model. For example: "I'm developing a chat assistant that must align with the ethical standards and organizational values of my company brand." * Upload your data source files. Drag and drop or click **Browse**. You can upload up to 10 files at a time. Accepted file formats: PDF, Word, Markdown, JSON. Maximum size 100 MB per file. Click **Next** to review your setup. On the **Confirm and Start Job** page, review your fine-tuning goal and data sources, then click **Start Job**. **Ingestion mode** AI-Ready Data jobs always use speed-optimized ingestion. To use accuracy-optimized ingestion, use the SDK instead. ## Job status Each job moves through the following states: | Status | Description | | --------- | ------------------------------------------------------------------ | | Queued | Job is in line to start | | Running | Documents are being processed and training data is being generated | | Completed | Training data has been generated and is ready to use | | Failed | Something went wrong — review your files and try again | ## Output Once a job completes, the generated training dataset is automatically saved to: * The **AI-Ready Data** page * **Data Engine > Storage** No download is required. When creating a fine-tuning job, you can select the dataset directly from your saved files in SeekrFlow. ## Next steps * [Create a fine-tuning job](/flow/app/fine-tuning) – Use your generated dataset to train a model * [Storage](/flow/app/storage) – View and manage your files and generated outputs # Chat with an agent Source: https://docs.seekr.com/flow/app/chat-with-an-agent Test agents in Agent Chat. Use Agent Chat to interact with agents and test their behavior before integrating them into your applications. ## Start a conversation Navigate to **Playground > Agent Chat** in the sidebar. Select an agent from the dropdown. Only active agents appear in the list. Type a message and press **Send**. The agent processes your message and returns a response. If the agent has tools configured, you can see which tools were called during the response. ## Manage threads Each conversation with an agent creates a thread. Previous threads are saved and accessible from the thread list on the left. To start a new conversation, click the **+** button. ## Model parameters Use the model parameters panel to adjust how the agent generates responses: | Parameter | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | Temperature | Controls response randomness. Lower values produce more predictable responses; higher values produce more varied responses. | | Top P | Controls the range of tokens the model considers. Lower values narrow the selection to more likely tokens. | | Frequency Penalty | Reduces repetition of tokens based on how often they have appeared in the response so far. | | Presence Penalty | Reduces repetition of tokens that have already appeared in the response, regardless of frequency. | Click **Reset All to Default** to restore all parameters to their default values. # Create a tool Source: https://docs.seekr.com/flow/app/create-a-tool Build a new custom tool in the SeekrFlow Tool Library. This guide walks through creating a tool in the SeekrFlow UI. ## Create the tool Navigate to **Agent Builder > Tool Library** in the sidebar. Click **Create Tool**. Enter the tool details: * **Tool Name** – A unique name for the tool. * **Configure Tools** – Select the tool type: * **File Search Tool** – Retrieves results from files you have indexed in a vector store. * **Web Search Tool** – Retrieves results from live web sources. If using **File Search Tool**, configure the additional settings: * **Select Vector Store** – Choose the vector store the tool will search. You can select one vector store per File Search tool. * **Tool Instructions** – Describe what the tool does and when the agent should use it. * **Search Parameters**: * **Top K** – Number of results to retrieve (5–10 for precision, 20–50 for broader coverage). * **Score Threshold** – Minimum similarity score for returned results (0.7–0.9 for strict relevance, 0.2–0.5 for exploratory searches). If using **Web Search Tool**, enter: * **Tool Instructions** – Describe what the tool does and when the agent should use it. Click **Create Tool**. ## Next steps * [Manage tools](/flow/app/manage-tools) – View, edit, clone, and delete tools * [Create an agent](/flow/app/create-an-agent) – Add your tool to an agent # Create an agent Source: https://docs.seekr.com/flow/app/create-an-agent Build a new agent with models and tools in the SeekrFlow UI. This guide walks through creating an agent in the SeekrFlow UI. ## Before you begin * Decide which model to use – see [Models](/flow/components/agents/models) for guidance on base models and fine-tuned deployments. * If using file search, create a vector store first – see [Create a vector store](/flow/app/vector-stores). ## Create the agent Navigate to **Agent Builder > Agents** in the sidebar. Click **Create Agent**. Enter the agent details: * **Name** – A unique identifier for the agent * **Instructions** – The system prompt that defines how the agent responds. Be specific about the task, expected behavior, and any constraints. * **Reasoning mode** – Choose based on your use case: * **Speed-optimized** – For straightforward tasks requiring quick responses * **Performance-optimized** – For complex tasks requiring deeper analysis For more on reasoning modes, see [Agents](/flow/components/agents). Select a model: * **Base models** – Pre-trained models hosted on the SeekrFlow platform * **Deployments** – Your fine-tuned models (must have an active deployment) Configure tools (optional). For available tools, see [Tools](/flow/components/agents/tools). For each tool, provide **tool instructions** that tell the agent when to use it. If adding file search: a. Select a **vector store** containing your documents.

b. Set **Top K** – Number of results to retrieve (5–10 for precision, 20–50 for broader coverage).

c. Set **Score threshold** – Minimum similarity score (0.7–0.9 for strict relevance, 0.2–0.5 for exploratory searches). Review your configuration and click **Create Agent**. The agent appears in your agents list with a **Pending** status while SeekrFlow provisions it. After a few minutes, the status changes to **Active** and the agent is ready to use. ## Next steps * [Manage agents](/flow/app/manage-agents) – Activate, deactivate, or modify agents * [Chat with an agent](/flow/app/chat-with-an-agent) – Test your agent in Agent Chat # Dashboard Source: https://docs.seekr.com/flow/app/dashboard Your home screen for quick actions, recent work, and deployment stats. SeekrFlow dashboard with numbered callouts | # | Region | Purpose | | - | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | 1 | Agent Builder | Build and manage AI agents and tools. Includes Agents and Tool Library. | | 2 | Data Engine | Create AI-ready training data. Includes AI-Ready Data and Storage. | | 3 | Model Development | Fine-tune and deploy models. Includes Fine-Tuning, Deployments, and Model Library. | | 4 | Playground | Test models and agents. Includes Model Chat and Agent Chat. | | 5 | Welcome cards | Quick actions to start core workflows: Create an Agent, Generate AI-Ready Data, Fine-Tune a Model, Go to Playground. | | 6 | Getting Started | Onboarding content: Quickstart Guide, Intro to the Data Engine, Explore Use Cases. Click **X** to dismiss. | | 7 | Recent Work | Tabs showing your most recent Agents, AI-Ready Data, and Fine-tuning jobs. | | 8 | Deployments | Deployment counts by status, active deployments, and inference token metrics. | | 9 | User menu | Access account settings and generate API keys. | # Data Engine Source: https://docs.seekr.com/flow/app/data-engine Manage files, generate training datasets, and build vector stores for fine-tuning and retrieval. The data engine transforms raw content into structured, AI-ready data. It manages the complete data lifecycle from file ingestion through preparation for training and retrieval workflows. ## In this section * [AI-Ready Data](/flow/app/ai-ready-data) – Generate structured datasets for fine-tuning and retrieval * [Storage](/flow/app/storage) – Upload and manage files, and create vector stores # Deployments Source: https://docs.seekr.com/flow/app/deployments Deploy and manage model endpoints for real-time inference from the SeekrFlow Deployment Dashboard. ## Deployment Dashboard The Deployment Dashboard provides a real-time view of all your deployments and their performance. At the top of the page: * **Status** — A donut chart showing total deployment count broken down by status: Active, Pending, Failed, and Inactive. * **Active Deployments** — Count of currently active deployments and total active hours to date. * **Inference Tokens** — Total input and output tokens consumed across all deployments to date. The deployments table lists all deployments with the following columns: **Deployment Name**, **Status**, **Model Type**, **Total Input Tokens**, **Total Output Tokens**, and **Last Modified**. Hover a row to reveal inline actions. Available actions depend on status: | Status | Meaning | Available actions | | -------- | -------------------------------------------- | ----------------- | | Pending | Deployment requested, provisioning underway. | Pause · Delete | | Active | Serving traffic. | Pause · Delete | | Inactive | Paused; no inference traffic. | Resume · Delete | | Failed | Error during start-up or runtime. | Delete | ## Create a deployment Click **+ Create Deployment** to open a four-step wizard. **Deployment Details** — Name (up to 100 characters) and describe (up to 1000 characters) the deployment. **Select Model** — Choose a model to make available for inference. Use the **Fine-Tuned Models** tab to select from your completed fine-tuning jobs, or the **Base Models** tab for open-source and partner models. Each card shows the provider, model name, and license tags (Open Source, Warning). **Select Hardware Configuration** — Set the number of AMD Instinct MI300X instances for your deployment. You can choose up to 50 instances. **Confirm and Start Deployment** — Review your deployment details and model and hardware configuration. Accept the selected model's license terms, then click **Start Deployment**. After submitting, a success screen confirms "Your model is deploying." The process may take a few minutes; track status in the Deployment Summary. Click **Go to Deployment** to navigate there directly, or navigate away — the deployment continues in the background. ## Deployment Summary Click any deployment name to open its summary page. The summary includes: * **Deployment Details** — Name (editable), ID, Model Type, Status, Date Created, Date Deployed, and description (editable). * **Integrating Deployment for Inference** — Quickstart Guide with instructions for setting up the SDK, sending API requests, and integrating your deployment. * **Data Sources & Training Prompt** — Training file and prompt from the originating fine-tuning job. * **Model, Hardware, and Hyperparameters** — The exact configuration running for this deployment. * **Fine-Tuning Job Details** — Link back to the source fine-tuning job. * **Agent Details** — Agents linked to this deployment and their statuses, if applicable. * **Event Timeline** — Right-hand feed of deployment lifecycle events (e.g., Deployment Pending, Deployment Complete). ## Pause and resume a deployment Click **Pause** on the summary page or from the inline row action in the dashboard to stop traffic without deleting the endpoint. Resume from the deployments table when ready to serve traffic again. ## Delete a deployment Deployments can be deleted from the inline row actions in the deployments table. # File Storage Source: https://docs.seekr.com/flow/app/file-storage Upload, organize, and manage the source documents and system-generated files used across SeekrFlow. File Storage is where you upload and manage all source documents used throughout the platform, including files for training data, vector stores, and agents. ## Supported file types Accepted formats depend on the file purpose selected at upload. **Raw Data** | File type | Notes | | --------- | -------------------------------------------------------------------------------------------------------------------------- | | `.pdf` | Converted to Markdown when used in AI-Ready Data or vector store workflows | | `.docx` | Converted to Markdown when used in AI-Ready Data or vector store workflows | | `.ppt` | Converted to Markdown when used in AI-Ready Data or vector store workflows | | `.md` | Used as-is | | `.json` | Must follow SeekrFlow's tree-like JSON structure – see [JSON formatting requirements](#json-formatting-requirements) below | **Fine-tuning Data (Instruction Tuning Data and Reinforcement Tuning Data)** | File type | Notes | | ---------- | ---------- | | `.jsonl` | Used as-is | | `.parquet` | Used as-is | Upload limits: 20 files at a time, maximum 150 MB per file. Files in unsupported formats or exceeding size limits are rejected with an error. ## Upload files Navigate to **Data Engine > Storage**, then select the **Files** tab. Click **Upload Files**. Select a file purpose: * **Raw Data** – unstructured data used to power vector stores or generate AI-ready fine-tuning data * **Instruction Tuning Data** – data with instructions and responses for domain-specific fine-tuning * **Reinforcement Tuning Data** – data for reinforcement-based fine-tuning to optimize outputs against reference answers Click **Next**, then drag and drop your files or browse your device to select them. SeekrFlow validates the files and shows any issues. Click **Upload Files** to confirm. Your uploads begin immediately and appear in the file list. ## File list Each file in storage displays: * **File name** * **Source type** – how the file entered the system: * `Uploaded` – manually uploaded by the user * `Converted` – created via ingestion from a PDF, DOCX, or PPT * `Generated` – created by a SeekrFlow process, such as an alignment parquet file * **File type** * **Date added** ## File details Click any file to open its details panel, which shows: * **ID** * **File size** * **File purpose** – the purpose selected at upload (Raw Data, Instruction Tuning Data, or Reinforcement Tuning Data) * **Source type** * **Date added** * **Used by** – any deployments, fine-tuning jobs, AI-Ready Data jobs, or vector stores that reference this file * **Delete** – remove the file if it is not actively used elsewhere ## System-generated files SeekrFlow automatically adds files to your storage as part of platform workflows: * **Converted markdown files** – When a PDF, DOCX, or PPT is used in a workflow requiring ingestion (AI-Ready Data or vector stores), SeekrFlow saves the converted `.md` output with source type `Converted`. * **Parquet datasets** – When an AI-Ready Data job completes, the generated parquet file is saved with source type `Generated`. Generated and converted files behave like any other file and can be reused in future jobs, vector stores, or fine-tuning workflows. ## File formatting requirements Before uploading, ensure your files are properly formatted. **PDF and DOCX** – Use clear headings and ensure text content is structured logically for conversion. Avoid images without surrounding context. **Markdown** – Use correct header hierarchy (`# H1`, `## H2`, `### H3`, etc.), limit headers to six levels, and ensure all sections have meaningful content. Avoid empty or skipped header levels. Google Docs users can export files as Markdown, PDF, or DOCX. ### JSON formatting requirements JSON files must follow a tree-like structure where each node represents a section of content and may contain nested child sections. Required fields for each node: * **`label`** – A short title or question for the section. * **`content`** – The main body text for the section. * **`children`** – An array of child objects with the same structure. Use an empty array (`[]`) if there are no children. * **`level`** – The depth of the section in the hierarchy: `"0"` for root, `"1"` for first-level child, and so on. ```json JSON theme={null} { "label": "Seekr Ingestion Rules", "content": "This document explains seekr ingestion...", "children": [ { "label": "JSON Example", "content": "You can upload json files...", "children": [], "level": "1" } ], "level": "0" } ``` ## Next steps * [Vector Stores](/flow/app/vector-stores) – Create semantic indexes from your uploaded files * [AI-Ready Data](/flow/app/ai-ready-data) – Generate training datasets from your files # Fine-Tuning Source: https://docs.seekr.com/flow/app/fine-tuning Create and manage fine-tuning projects and jobs through the SeekrFlow web interface. For conceptual background on fine-tuning methods, training requirements, and when to use each approach, see [Fine-tuning](/flow/components/fine-tuning). ## Fine-Tuning Projects The Fine-Tuning page lists all your projects with the following columns: **Project Name**, **Jobs**, **Date Created**, and **Last Modified**. From here you can create new projects and open existing ones. ## Create a project Click **+ Create Project** to open the Create Fine-Tuning Project modal. Enter a name (up to 100 characters) and description (up to 1000 characters), then click **Create Project**. Once created, click **Go to Project** to open the project and start adding jobs. ## Create a fine-tuning job From inside a project, click **+ Create Job**. The wizard walks through the following steps: **Job Details** — Name and describe the job, then select a fine-tuning method: * **Instruction Tuning** (Standard) — Fine-tune with domain-specific instructions and responses. Best for reliable outputs that reflect expert knowledge. * **Reinforcement Tuning** (Advanced) — Optimize outputs through reinforcement learning. Best for tasks with clear, verifiable answers. **Select Data for Fine-Tuning** — Choose an existing file from your storage or upload a new one. Accepted formats: JSONL or Parquet. Maximum file size: 150 MB. For reinforcement tuning, download a sample dataset to see the expected format: **Select Model** — Choose a base model to build upon. **Select Hardware Configuration** — Choose compute resources on AMD Instinct MI300X hardware: * **1 Instance** — Ideal for fine-tuning a smaller model with a lighter dataset. * **8 Instances** — Recommended for fine-tuning a larger model with an extensive dataset. **Tune Hyperparameters** — Adjust training parameters: * **Number of Epochs** — Default 1, integer from 1 to 2000. * **Batch Size** — Default 1, integer from 1 to 1024. * **Learning Rate** — Default 1e-05, number between 0 and 1. **Confirm and Start Job** — Review your configuration (job details, data sources, model, hardware, and hyperparameters). Accept the selected model's license terms, then click **Start Job**. ## Monitor training progress Each job has a summary page with the following sections: **Job Details** — Job name, ID, status, method, creation and completion timestamps, and description. **Loss Metrics** — Training loss and validation loss values with a chart tracking both over steps and epochs. Select **How to Read This Chart** for an explanation of the values. **Accuracy Metrics** — Training accuracy and validation accuracy values with a chart tracking both over steps and epochs. Select **How to Read This Chart** for an explanation of the values. **Data Sources** — Training file, training data type, and training prompt used for the job. **Model, Hardware, and Hyperparameters** — Base model, hardware configuration, and the full set of parameters used for the run. **Reward Function** — Shown for Reinforcement Tuning jobs. Displays the reward criteria (e.g., Math Accuracy, String Check, Text Similarity) with their weights and operations. **Deployment Details** — Table of all deployments created from this job, showing Deployment Name, Status, Date Created, and Last Modified. ## Deploy a fine-tuned model After a job completes, deploy the resulting model for inference directly from the job summary page. Existing deployments and their statuses appear in the Deployment Details table at the bottom of the summary. ## Demote a deployment Active deployments can be demoted (undeployed) when no longer needed, freeing infrastructure resources. # Manage agents Source: https://docs.seekr.com/flow/app/manage-agents View, edit, activate, and deactivate agents in the SeekrFlow UI. This guide covers managing agents after creation. ## View agents Navigate to **Agent Builder > Agents** to see all your agents. Each agent displays its name, status, date created, and last modified date. Click an agent to view its full configuration: * Name and ID * Status * Date created and date deployed * Agent instructions * Reasoning configuration * Model details ## Agent statuses | Status | Description | | -------- | --------------------------------- | | Active | Ready to serve requests | | Pending | Transitioning between states | | Inactive | Not deployed, requires activation | | Failed | Deployment or update failed | ## Activate an agent **From the agents list:** Click the **more** menu (⋮) next to the agent. Click **Start**. **From the agent summary:** Click the agent to open its summary. Click **Start**. The agent status changes to **Pending** while SeekrFlow provisions it. After a few minutes, the status changes to **Active**. ## Deactivate an agent **From the agents list:** Click the **more** menu (⋮) next to the agent. Click **Pause**. **From the agent summary:** Click the agent to open its summary. Click **Pause**. The agent status changes to **Pending**, then **Inactive**. Inactive agents do not serve requests. ## Edit an agent You can edit an agent's configuration at any time regardless of its status. **From the agents list:** Click the **more** menu (⋮) next to the agent. Click **Edit**. **From the agent summary:** Click the agent to open its summary. Click **Edit**. ## Delete an agent Agents must be inactive before they can be deleted. **From the agents list:** Click the **more** menu (⋮) next to the agent. Click **Delete**. Confirm the deletion. **From the agent summary:** Click the agent to open its summary. Click the trash can icon. Confirm the deletion. Deleted agents cannot be recovered. # Manage permissions Source: https://docs.seekr.com/flow/app/manage-permissions Set up your organization, invite members, and manage team access in SeekrFlow. For background on organizations, teams, and roles, see [Role-based access control](/flow/role-based-access-control). Organization settings are accessible from the user profile menu in the top right corner of the SeekrFlow interface. ## Your organization The **Organization** page shows your organization name, your role, the date the organization was created, and a summary of your members and teams. The **Role Definitions** section at the bottom describes what each organization and team role can do. Owners can edit the organization name by clicking the name field directly. ## Add and remove members The **People** page lists all members in your organization. To access it, click **View People** from the Organization page, or select **People** under **Organization** in the left navigation. ### Invite a member Only owners can invite new members. Click **+ Invite Member**. Enter the member's email address. Select an organization role — **Member** or **Owner**. Click **Send Invitation**. The invitation appears under the **Invitations** tab until the member accepts. You can cancel a pending invitation from that tab. ### Change a member's organization role Click the member's name to open their details. Click the role badge next to their name and select a new role. Confirm the change. ### Remove a member Click the member's name to open their details. Select **Remove from Organization** from the actions menu. Confirm the removal. Removing a member revokes their access to all teams and resources in the organization. ## Create and manage teams The **Teams** page lists all teams in your organization. To access it, click **View Teams** from the Organization page, or select **Teams** under **Organization** in the left navigation. ### Create a team Only owners can create teams. Click **+ Create Team**. Enter a team name (up to 100 characters). Click **Create Team**. The new team appears in the teams list. Click the team name to open its details and add members. ### Add a team member Only team admins can add members to a team. Organization owners with a Creator role on the team cannot add members. Open the team by clicking its name. Click **+ Add Team Member**. Enter the member's email address. Select a team role — **Creator** or **Admin**. Click **Add Team Member**. The member must already belong to the organization. To invite someone new, invite them to the organization first. ### Change a team member's role Open the team by clicking its name. Find the member in the **Team Members** list and click their role badge. Select a new role and confirm. ### Remove a team member Open the team by clicking its name. Find the member in the **Team Members** list and open the actions menu. Select **Remove from Team** and confirm. ### Delete a team Only owners can delete teams. Open the team by clicking its name. Click **Delete Team**. Confirm the deletion. Teams with active or running resources cannot be deleted until those resources are stopped or reassigned. ## Find a team ID The **Teams Settings** page lists every team you belong to along with its ID. You need a team's ID to scope SDK or API requests to a specific team. For how to use it, see [Work with teams](/flow/sdk/teams). ## Switch your active team If you belong to multiple teams, a team switcher appears in the breadcrumb bar at the top of the page. Click your current team name to open the switcher, then: * Select a different team to switch to it. All resource lists — agents, fine-tuning jobs, deployments, files, and vector databases — update to show only what belongs to the selected team. * Select **Team Settings** to manage the current team's members and roles. # Manage tools Source: https://docs.seekr.com/flow/app/manage-tools View, edit, clone, and delete tools in the SeekrFlow Tool Library. This guide covers managing tools after creation. ## View tools Navigate to **Agent Builder > Tool Library** to see all your tools. Each tool displays its name, status, date created, and last modified date. If you have no tools yet, click **[Create Tool](/flow/app/create-a-tool)** to get started. ## Tool statuses | Status | Description | | -------- | ------------------------------------------------- | | Active | Tool is deployed and available to assigned agents | | Inactive | Tool exists but has no active agent assignments | | Pending | Tool is transitioning between states | | Pausing | Tool is being deactivated | | Failed | Tool deployment or update failed | Tool status reflects the state of the agents it is assigned to. Available actions depend on the current status. ## View tool details Click a tool to open its summary panel. The panel shows: * **Name**, **ID**, and **Status** * **Tool Type** – File Search, Web Search, Agent as Tool, Code Interpreter, or Custom Tool * **Date Created** and **Last Modified** * **Author** * **Tool Description** * **Agents Used** – Number of agents currently using this tool * **Used In** – Table of assigned agents with their status, date created, and last modified date Only File Search and Web Search tools can be created in the UI. Tools of other types created via the API will also appear here. ## Edit a tool To edit a tool, use one of the following methods: **From the tools list:** Click **More options** (**⋮**) next to the tool. Select **Edit**. Update the tool configuration in the Tool Details modal. Click **Save Tool** to confirm. **From the tool summary:** Click the tool to open its summary panel. Click **Edit**. Update the tool configuration in the Tool Details modal. Click **Save Tool** to confirm. Editing a tool affects all agents currently using it. ## Clone a tool To clone a tool, use one of the following methods: **From the tools list:** Click **More options** (**⋮**) next to the tool. Select **Clone**. **From the tool summary:** Click the tool to open its summary panel. Click **Clone**. A copy of the tool appears in your Tool Library. ## Delete a tool To delete a tool, use one of the following methods: **From the tools list:** Click **More options** (**⋮**) next to the tool. Select **Delete**. Confirm the deletion. **From the tool summary:** Click the tool to open its summary panel. Click the trash can icon. Confirm the deletion. Deleted tools cannot be recovered. # Model Development Source: https://docs.seekr.com/flow/app/model-development Fine-tune, deploy, and browse base models in SeekrFlow. Model Development provides tools for training custom models on your data, deploying them for inference, and browsing the library of available base models. ## In this section * [Fine-Tuning](/flow/app/fine-tuning) – Create and manage fine-tuning jobs * [Deployments](/flow/app/deployments) – Deploy models and manage inference endpoints * [Model Library](/flow/app/model-library) – Browse available base models for fine-tuning and deployment # Model Library Source: https://docs.seekr.com/flow/app/model-library Browse and deploy available base models for fine-tuning and inference. The Model Library is a browsable catalog of base models available on SeekrFlow. Use it to explore what's available before starting a fine-tuning job, or to deploy a base model directly for inference. For the full list of supported base models and their specifications, see [Models](/flow/components/agents/models). ## Model cards Each model is shown as a card displaying: * **Provider** — The organization that published the model (e.g., Meta, Google, Mistral, DeepSeek). * **Model name** — The full model identifier. * **Tags** — Indicate availability and licensing: * **Open Source** — Available under an open-source license. * **Warning** — Has licensing terms that may restrict certain use cases. Review the license before using it in production. ## Deploy a base model To deploy a base model directly for inference, click **+ Create Deployment**. This opens the deployment wizard — see [Deployments](/flow/app/deployments) for a full walkthrough. # Playground Source: https://docs.seekr.com/flow/app/playground Test models and agents in SeekrFlow. Use the Playground to test models and chat with agents before integrating them into your applications. ## In this section * [Test a model](/flow/app/test-a-model) – Send prompts to models directly * [Chat with an agent](/flow/app/chat-with-an-agent) – Test agents and review their responses * [Understand a response](/flow/app/understand-a-response) – Use Source Trace to see which sources influenced a response # Storage Source: https://docs.seekr.com/flow/app/storage Upload and manage source files, and create vector stores for retrieval and grounding. Storage is where SeekrFlow manages all content used across the platform, including files for training data, vector stores, agents, and evaluations. ## In this section * [File Storage](/flow/app/file-storage) – Upload, organize, and manage source documents and system-generated outputs * [Vector Stores](/flow/app/vector-stores) – Create semantic indexes from your files for retrieval and context grounding # Test a model Source: https://docs.seekr.com/flow/app/test-a-model Send prompts directly to models in Model Chat. Model Chat lets you send prompts directly to models and compare responses side by side. ## Start a conversation Navigate to **Playground > Model Chat** in the sidebar. Select **Deployments** or **Base Models** to choose the type of model to test. Select up to two models using the checkboxes. Type a message and press **Send**. ## Next steps * [Chat with an agent](/flow/app/chat-with-an-agent) – Test agents in Agent Chat # Tool Library Source: https://docs.seekr.com/flow/app/tool-library Create and manage tools for your agents in the SeekrFlow user interface. Tools extend what agents can do. While models provide reasoning capabilities, tools allow agents to take actions—accessing external systems, querying knowledge stores, executing code, or performing web searches to accomplish tasks. Tool Library provides a no-code interface for creating and managing tools that extend agent capabilities. Tools you create here are available to assign when building agents in Agent Builder. For more information about tools, see [Tools](/flow/components/agents/tools). To create tools using the SDK, see [Tools](/flow/sdk/agents/tools). ## In this section * [Create a tool](/flow/app/create-a-tool) – Build a new tool * [Manage tools](/flow/app/manage-tools) – View, edit, clone, and delete tools # Understand a response Source: https://docs.seekr.com/flow/app/understand-a-response Use source trace to see which sources influenced an agent's response. Use source trace to see which documents and data influenced an agent's response, and which parts of the response each source contributed to. For more information, see [Context attribution](/flow/components/explainability/context-attribution). ## Open source trace After an agent responds in Agent Chat, click **Run Source Trace** at the bottom of the response. SeekrFlow opens the response in a full-screen view and begins finding sources. Loading takes between 5 and 15 seconds. ## Read the highlighted response Once sources load, the response is divided into segments. Each segment is highlighted to show how strongly it was influenced by sources. The **Sources** panel on the right lists sources sorted by influence score, highest first. To hide the highlights, toggle **Influence Highlights** off in the toolbar. ## Explore by segment Hover over a segment to emphasize it and dim the others. Click a segment to select it. The Sources panel updates to show only the sources for that segment. Click anywhere outside the response to deselect. ## Trace a specific portion To find sources for a specific part of the response: Select the text you want to trace. Click **Run Source Trace For This**. This runs source trace on the selected text only, regardless of the granularity setting. ## Adjust parameters Click the **Parameters** tab in the Sources panel to configure how the response is segmented before running the trace. After changing a parameter, **Run Source Trace** becomes active again. ## View source content Click a source in the Sources panel to view the sentence or chunk from that source that contributed to the response. Web search sources may show a short snippet or a longer passage depending on whether the agent fetched the full page. ## No sources returned If the Sources panel is empty, the response was not grounded in documents or tools. This is expected for responses based on general knowledge. ## Exit Click **Exit** in the breadcrumb to return to Agent Chat. The view scrolls back to the response you were viewing. Source trace results are not saved. # Vector Stores Source: https://docs.seekr.com/flow/app/vector-stores Create semantic indexes from your documents to power retrieval, agents, and context-grounded fine-tuning. Vector stores are semantic indexes built from your documents. They allow language models to retrieve contextually relevant information, powering workflows like agents, assistants, and context-grounded fine-tuning. Each chunk of your documents is converted into a vector embedding, making content searchable by semantic similarity rather than keywords. ## Create a vector store Navigate to **Data Engine > Storage**, then select the **Vector Stores** tab. Click **Create Vector Store**. Enter the vector store details: * **Name** (required, 100 characters max) * **Description** (optional, 500 characters max) * **Embedding Model** — select from available options Click **Create Vector Store**. The new store appears in the vector stores list with its name, file count, total size, and date modified. ## Vector store details Click any vector store to open its details view, which displays: * **ID** * **Model** – the embedding model used * **Size** * **File Count** * **Date Created** * **Last Modified** * **Description** – editable after creation * Files currently embedded in the store * Option to add more files ## Add files to a vector store Open the vector store details view. Click **Add Files**. In the modal, use **Select Files** to choose from existing files in File Storage, or switch to **Upload Files** to upload new files directly. Optionally expand **Advanced Embedding Options** to configure chunking behavior. Click **Add Files** to confirm. Supported file types: `.pdf`, `.docx`, `.ppt`, `.md`, `.json` Upload limits: 20 files at a time, maximum 150MB per file. `.jsonl` and `.parquet` files cannot be added to a vector store. ### Advanced Embedding Options Expand this section to configure how content is segmented before embedding: * **Chunk Size (Tokens)** — Maximum token count per chunk. Default: 800. * **Chunk Overlap (Tokens)** — Token overlap between adjacent chunks to reduce information loss at boundaries. Default: 400. ## File processing Once you click **Add Files**, SeekrFlow handles the rest automatically: 1. **Ingesting** — Converts compatible files to Markdown if needed. **Ingestion mode** Files added through the UI are always ingested using speed-optimized mode. To use accuracy-optimized ingestion, use the SDK instead. 2. **Chunking** — Breaks content into segments based on your settings. 3. **Embedding** — Transforms each chunk into a vector. 4. **Indexing** — Stores vectors into the semantic index. When processing completes, files appear in the details view with their name, processing status, and size. If a file fails to process, an error is shown with guidance for resolution. ## File status | Status | Description | | --------- | --------------------------------------- | | Queued | File is waiting to be processed | | Ingesting | File is being converted to Markdown | | Chunking | Content is being segmented | | Embedding | Chunks are being converted to vectors | | Complete | File is indexed and ready for retrieval | ## Manage vector stores From the details view you can add or remove files, monitor file processing status, and rebuild the store when content changes. ## Next steps * [AI-Ready Data](/flow/app/ai-ready-data) – Generate context-grounded training data using a vector store * [Create an agent](/flow/app/create-an-agent) – Attach a vector store to an agent for retrieval-augmented memory # Release notes 2024 Source: https://docs.seekr.com/flow/changelog/seekr-managed/2024 > Improvements & Bug Fixes ### Tooltip for Icon Buttons in Model Library We’ve improved the user experience in the Model Library. Icon buttons in base model cards now display a hover tooltip with descriptive text, ensuring users clearly understand the available actions. ### Faster Response Rendering in Sandbox The simulated typing animation for sandbox responses now matches the speed of token count updates. This enhancement delivers quicker rendering, offering a more seamless and accurate representation of response generation. ### Run Description Added to Run Summary The run summary now displays the description entered during the run creation wizard, enhancing clarity and alignment with the design specifications. ### Minor Bug Fixes and Stability Improvements This release includes several minor bug fixes and performance enhancements across SeekrFlow™ to ensure a smoother and more reliable user experience. November’s release introduces new features designed to give users greater control and efficiency over their AI workflows—from optimizing model outputs to managing large-scale deployments. For more details, read our full release blog. > New Features ### Sandbox Input Parameters We have added new input parameters to the Sandbox environment: Temperature, Top P, and Max Tokens. These options give more control over inference outputs, allowing users tailor responses for specific tasks and use cases. ### Enhanced Inference Engine for Faster Inference With the integration of vLLM, inference speeds have dramatically improved, making your AI workflows faster and more efficient. This integration ensures that even complex models deliver faster results, helping users achieve more in less time. We conducted performance testing to compare TGI and vLLM on Intel Gaudi2 accelerators. * **TGI**: tgi-gaudi v2.0.4 * **vLLM**: vllm-fork v0.5.3.post1-Gaudi-1.17.0 On average, the enhanced inference engine performed 32% faster when compared to TGI for the RAG experiments (full interaction traces, 10 concurrent requests) using Meta-Llama-3.1-8B-Instruct Significant latency improvements in load testing with 100 concurrent users: * **Meta-Llama-3-8B-Instruct**: \~45% faster * **Meta-Llama-3.1-8B-Instruct**: \~39% faster ### Enhanced OpenAI compatibility features Our inference engine now seamlessly integrates with OpenAI’s ecosystem, expanding workflow capabilities and enhancing usability. * **Log Probabilities**: New support for log\_probs and top\_logprobs, providing insights into model decision-making, aiding debugging, and improving output accuracy. * **Dynamic Tool Calling**: Custom functions can now be automatically invoked by the model based on context, streamlining business logic integration. ### Try it yourself! The example code below shows you how to leverage the OpenAI client and SeekrFlow's inference engine to create a custom unit conversion tool that can be configured dynamically. #### Create the client and make an API request ```python Python expandable theme={null} import os import openai # Set the API key os.environ["OPENAI_API_KEY"] = "Paste your API key here" # Create the OpenAI client and retrieve the API key. client = openai.OpenAI( base_url="https://flow.seekr.com/v1/inference", api_key=os.environ.get("OPENAI_API_KEY") ) # Send a request to the OpenAI API to leverage the specified Llama model as a unit conversion tool. response = client.chat.completions.create( model="meta-llama/Llama-3.1-8B-Instruct", stream=False, messages=[{ "role": "user", "content": "Convert from 5 kilometers to miles" }], max_tokens=100, tools=[{ "type": "function", "function": { "name": "convert_units", "description": "Convert between different units of measurement", "parameters": { "type": "object", "properties": { "value": {"type": "number"}, "from_unit": {"type": "string"}, "to_unit": {"type": "string"} }, "required": ["value", "from_unit", "to_unit"] } } }] ) ``` #### Register a function from JSONNext, define and register a Python function from JSON data. ```python Python theme={null} # Parse json and register def register_from_json(json_obj): code = f"def {json_obj['name']}({', '.join(json_obj['args'])}):\n{json_obj['docstring']}\n{json_obj['code']}" print(code) namespace = {} exec(code, namespace) return namespace[json_obj["name"]] ``` #### Run the unit conversion toolThis function executes the tool call, given an LLM response object. ```python Python theme={null} # Execute our tool def execute_tool_call(resp): tool_call = resp.choices[0].message.tool_calls[0] func_name = tool_call.function.name args = tool_call.function.arguments func = globals().get(func_name) if not func: raise ValueError(f"Function {func_name} not found") if isinstance(args, str): import json args = json.loads(args) return func(**args) execute_tool_call(response) ``` #### Sample output This is the output expected in response to the request made earlier to convert 5 kilometers to miles. ```python Python theme={null} 3.106855 ``` ### Federated Login with Intel Intel® Tiber™ AI Cloud users can now access SeekrFlow™ with a new federated login feature First-time users: Start by using your Intel® Tiber™ AI Cloud credentials, which will auto-populate the sign-up form for quick and easy access to SeekrFlow. Returning users: Simply log in with your Intel® Tiber™ AI Cloud credentials for direct access to SeekrFlow. This integration simplifies user management and access for those connected to Intel® Tiber™ AI Cloud. > Improvements & Bug Fixes ### Streaming in Sandbox We have enabled streaming for chat responses in the Sandbox, delivering results incrementally so users can utilize results without a delay. ### Clear and Restart Button Fix We have resolved an issue where the “Clear and Restart” button in Sandbox didn’t function. A dialog box now appears, confirming that chat history will be cleared, allowing you to start fresh. ### Dataset Directory Update Uploaded file improvements in the Create Run Modal * Successfully uploaded files immediately appear in the dataset directory. * Switching to the directory view auto-selects the newly uploaded file. * Radio buttons now remain active, ensuring smooth file selection. > UI/UX Enhancements We have made several updates to improve the user experience and provide clearer guidance across the platform * **Sandbox**: Updated language to better support the new model parameter settings for improved clarity. * **Deployment Dashboard**: Enhanced explanations of cost transparency features for better understanding of resource usage. * **Projects**: Cancellation dialogs now show detailed cost information related to token usage, offering users more visibility into their resource consumption. These updates aim to make SeekrFlow’s interface more intuitive and user-friendly, enhancing navigation and overall clarity. > UI/UX Enhancements ### Quickstart Card Reorganization We have reorganized the Quickstart cards to improve navigation and help users find essential features and tools faster, making it easier to get started and accelerate the time to deployment. ### New Icons and Tooltips New icons and tooltips have been introduced across the platform. These provide quick access to relevant documentation without interrupting your workflow, ensuring that users can reference helpful resources whenever needed. ### Enhanced User Guidance We have updated the user guidance system to provide clearer instructions throughout the process, with a focus on alignment and data creation. Users will now find an embedded documentation tab within the UI, offering step-by-step instructions and best practices for principle alignment and data creation. These updates are designed to support users of all technical backgrounds, helping them navigate the platform with confidence and accelerate their AI model deployment. ### The New SeekrFlow™ Self-Service Enterprise AI Platform SeekrFlow™ is now available as a complete, self-service platform that empowers enterprises to train, validate, deploy, and scale trusted AI applications with ease. This includes: * **Lifecycle Management**: Manage the entire AI lifecycle through a single API call, SDK, or no-code interface. * **Principle Alignment**: An intelligent agent that simplifies the process of aligning AI models to domain-specific knowledge, such as company policies, industry regulation,s or brand guidelines. This feature enhances the accuracy and relevance of base model responses by 3x and 6x respectively, at 90% reduced cost compared to traditional data preparation methods. * **Five-step Deployment**: Simplify and accelerate the deployment process with an intuitive, guided workflow. * **Model Validation Tools**: Ensure model accuracy with advanced validation features, including side-by-side comparisons and token-level confidence scoring. * **Real-time Monitoring**: Monitor model performance and production health to maintain reliability and optimize outcomes. * **Flexible Cloud and Hardware Deployment**: Deploy models seamlessly on all leading cloud providers and hardware platforms, offering the flexibility to scale based on your needs. For more details, read the full blog [here](https://www.seekr.com/the-new-seekrflow-self-service-enterprise-ai-platform/). # Release notes 2025 Source: https://docs.seekr.com/flow/changelog/seekr-managed/2025 ### LoRA fine-tuningFeature Seekr-managed instance SeekrFlow now supports low-rank adaptation (LoRA) support for parameter-efficient fine-tuning. LoRA trains small adapter layers while keeping the base model frozen, enabling faster training cycles and reduced computational costs compared to full fine-tuning. **Capabilities:** * Fine-tune models using LoRA with SFT and GRPO workflows * Lower GPU memory requirements enable fine-tuning of larger models * Reduced risk of catastrophic forgetting * Configure via `lora_config` parameter in `TrainingConfig` (includes `rank`, `alpha`, and advanced fields) ### User interface parity with Seekr-managed instanceImprovement Self-hosted instance Self-hosted instances now include all features and improvements released to Seekr-managed instances through September 2025. This release brings self-hosted deployments to feature parity with the managed interface, including SeekrFlow Explainability, Agent Observability Platform, Docstring Validation, AI Ready Data Engine quality enhancements, and SeekrFlow Helm Chart v2.0. ### Faster file ingestionImprovement Seekr-managed instance Significantly faster document processing across all file sizes and ingestion modes (speed and accuracy optimized). **Performance improvements:** * 5 MB PDFs: complete in under 35 seconds * Small text-based documents: complete in under 6 seconds Actual ingestion times vary based on file size and content. Both speed and accuracy modes now process documents substantially faster regardless of workload, ### Chunking strategies for document ingestionFeature Seekr-managed instance Multiple chunking strategies for vector database ingestion, enabling optimized document processing based on content type and use case. **Available strategies:** * **Manual chunking**: Use custom delimiters (`---DOCUMENT_BREAK---`) to define chunk boundaries, ideal for resume collections or document compilations where each document should remain intact. * **Semantic chunking**: Group content based on semantic similarity using embedding models, maintaining coherence for long-form content. * **Sliding window chunking**: Simple fixed-size chunks with configurable overlap, suitable for uniform processing without content-aware splitting. * **Markdown chunking** (existing): Split documents based on markdown heading hierarchy while preserving table structures. All strategies respect token limits and include fallback handling for sections exceeding maximum token counts. > New Feature ### SeekrFlow Explainability SeekrFlow now brings transparency to model outputs by surfacing the five most influential Q\&A pairs that shaped each response. Generated by the AI-Ready Data Engine, these pairs can be traced directly without relying on file downloads or custom scripts. This gives users immediate visibility into the training data behind their fine-tuned models, supporting validation, debugging, and trust in model behavior. The feature is available in the SDK through get\_influential\_finetuning\_data() and in Model Chat within the SeekrFlow UI. View documentation [here](/flow/components/explainability) ### Agent Observability Platform SeekrFlow now includes an observability platform that gives developers full visibility into agent execution. Through detailed traces, spans, and performance metrics, users can see how agents process inputs, make decisions, and produce outputs—step by step. **Key Capabilities** * Automatic trace and span collection for all agent operations. * Capture of tool calls, LLM inferences, and execution flows. * SDK access for querying and analyzing agent runs. This update removes the “black box” from agent behavior, enabling validation, auditability, and performance optimization. With complete observability, teams can deploy Seekr agents in production with confidence and transparency. ### Docstring Validation for Custom Functions This update enhances the performance and reliability of SeekrFlow Agent Custom Tools by introducing docstring validation, a system that automatically checks function documentation before deployment. **Key capabilities** * Validates Python function docstrings against the Google format during create() or update(). * Ensures all parameters, types, and return values are correctly defined. * Consolidates documentation into a single source of truth, removing duplicate or conflicting descriptions. Docstring validation improves both development clarity and runtime performance. Clear, validated function definitions help agents determine when to invoke tools, accurately map parameters, and reduce execution errors—resulting in faster, more predictable performance and a smoother user experience. View documentation [here](/flow/sdk/agents/custom-tools) ### SeekrFlow Now Available in AWS GovCloud (US) SeekrFlow™ is now available in AWS GovCloud (US), joining its existing AWS Marketplace listing to give federal agencies and regulated customers one-click, subscription-based access to agentic AI in a secure, sovereign cloud environment. This deployment enables organizations including the U.S. Department of War to run AI workflows that protect Controlled Unclassified Information (CUI) and other high-value assets while accelerating modernization and mission-critical outcomes. Federal customers can now procure SeekrFlow faster and deploy it for FedRAMP High and DoW SRG IL5 workloads, all while leveraging existing AWS Enterprise Discount Program (EDP) credits. This simplifies procurement, optimizes costs, and allows agencies to adopt AI with full confidence in compliance, data protection, and security. Learn more [here](https://www.seekr.com/blog/seekrflow-agentic-ai-platform-now-available-in-aws-govcloud-us/) > Improvements & Bug Fixes ### SeekrFlow Helm Chart v2.0 This release introduces major upgrades to the SeekrFlow Helm Chart, bringing unified MLOps deployment, expanded environment support, and stronger compliance for enterprise and government users. **Supported Environments** * AWS Commercial * AWS GovCloud **Key Capabilities** * Unified serving, ingestion, and training in one deployment. * Built-in tools for Web Search, File/Vector Search, and Code Execution. * vLLM-powered model serving for faster inference and better GPU efficiency. * FIPS-enabled containers, hardened security baselines, and upgraded secrets management. * Simplified configuration via refactored values.yaml and improved observability across all components. This update strengthens deployment flexibility and compliance posture especially for customers operating in regulated and government environments, while simplifying operations and improving performance across the entire MLOps stack. ### AI Ready Data Engine Quality Enhancements We’ve made several improvements to question-generation and evaluation to increase data diversity and overall fine-tuning quality. **Key enhancements** * Expanded question coverage by generating from summaries, extracted facts, and source text. * Introduced question evolution, producing multiple forms of similar questions for richer variation. * Implemented explicit instruction-based evaluation for each generated pair. * Shifted from a fixed number of questions per node to dynamic generation determined at runtime. These updates produce more accurate and contextually varied Q/A pairs, improving both data quality and model alignment for fine-tuning workflows. > New Feature ### GRPO Fine-Tuning We’ve introduced Group Relative Policy Optimization (GRPO) Fine-Tuning in SeekrFlow, a powerful reinforcement learning technique that unlocks advanced reasoning capabilities in Large Language Models (LLMs). GRPO fine-tuning transforms models from passive information retrievers into active problem-solvers, capable of handling complex, verifiable tasks with greater precision and reliability. This method is effective in domains where answers can be definitively validated, such as mathematics, coding, and other structured problem-solving scenarios. GRPO training follows a similar process to standard fine-tuning, with a few targeted modifications, and is now fully supported in SeekrFlow. Read the blog [here](https://www.seekr.com/blog/introducing-grpo-fine-tuning-in-seekrflow/) View Documentation [here](/flow/components/fine-tuning/grpo) ### Custom Tools for SeekrFlow AgentsSeekr Flow Agents now support Custom Tools, enabling developers to extend agent capabilities with purpose-built logic tailored to their specific workflows. Custom Tools are developer-defined Python functions that can be seamlessly integrated alongside built-in tools like Web Search or File Search. Agents dynamically reason over tool descriptions, their instructions, and user input to decide when to invoke them to automatically map context to parameters, execute the function, and return results. Key capabilities: * Custom business logic: Implement organization-specific workflows and operations. * Data transformation: Clean, format, and enrich text, numerical, or structured data. * External integrations: Connect agents to APIs, databases, Slack, Outlook, and other business systems. * Proprietary data access: Leverage internal knowledge stores and company-specific repositories. View documentation [here](/flow/sdk/agents/custom-tools) > Improvements & Bug Fixes ### Model Library Super-Size The SeekrFlow Model Library just got a major expansion—15 new models are now available for use. This update significantly broadens your model options, offering a mix of small, mid, and large-scale LLMs across multiple providers. Whether you’re experimenting with reasoning, vision tasks, or enterprise-scale workloads, SeekrFlow now gives you more flexibility to choose the right model for the job. #### New Models Added:- meta-llama/Llama-3.2-90B-Vision-Instruct * NousResearch/Yarn-Mistral-7B-128k * mistralai/Mistral-7B-Instruct-v0.2 * mistralai/Mistral-Small-24B-Instruct-2501 * google/gemma-2b * google/gemma-2-9b * google/gemma-3-27b-it * Qwen/Qwen3-8B-FP8 * Qwen/Qwen3-32B-FP8 * Qwen/Qwen3-30B-A3B-FP8 * Qwen/Qwen3-235B-A22B-FP8 * Qwen/Qwen2-72B * mistralai/Mamba-Codestral-7B-v0.1 * microsoft/Phi-3-mini-4k-instruct * meta-llama/Llama-4-Scout-17B-16E * meta-llama/Llama-4-Scout-17B-16E-Instruct #### Refreshed Models:- meta-llama/Llama-3.2-1B-Vision-Instruct * meta-llama/Llama-3.2-3B-Vision-Instruct Where to use them: * API / SDK: Call the new models directly for inference. * Playground > Model Chat: Pick any of the new additions and start chatting immediately. ### Content Moderation Models in SeekrFlowSeekr Flow now includes content moderation models to help teams build safety and scoring pipelines directly into their applications. #### Available Models: ##### Seekr ContentGuard * Purpose-built for podcast moderation, using the same scoring system that powered SeekrAlign. * Includes GARM category classification and the Seekr Civility Score™. * Ideal for scoring podcast transcripts, detecting attacks, labeling tone, and surfacing ad risk. Learn more [here](/flow/seekr-contentguard-sdk) ##### Meta Llama Guard 3 * General-purpose moderation model that classifies unsafe content across 22 MLCommons taxonomy categories. * Best for moderating LLM outputs, chat messages, or any user-generated text. * With these models, users can design their own safety and scoring apps or pipelines that can: Learn more [here](/flow/llama-guard-sdk) With these models, users can design their own safety and scoring apps or pipelines that can: * Detect unsafe or brand-unsafe content. * Score tone and civility. * Add guardrails for LLM agents and assistants. * Apply moderation filters at scale. This update expands SeekrFlow into media, safety, guardrails, and governance use cases—broadening how teams can ensure responsible, brand-safe, and transparent AI deployments. View documentation [here](/flow/components/content-moderation) ### Built-in Tools for SeekrFlow Agents (Now in the SeekrFlow UI) You can now configure agent tools directly from the SeekrFlow UI, making it easier to extend agent capabilities. #### Available Tools:- File Search: Let agents retrieve and reason over files ingested into SeekrFlow. * Web Search: Enable agents to pull in fresh information from the web to complement their knowledge base. This update gives you more control and flexibility in building agents straight from the browser. With built-in File Search and Web Search, teams can quickly prototype, evaluate, and operationalize agents that connect to both internal and external sources. ### AI-Ready Data Engine: New Ingestion & Chunking Methods This release introduces powerful new ingestion and chunking options, giving users more control over speed, accuracy, and structure when preparing data for AI workflows. Available in UI, API, and SDK. #### Ingestion Methods: ##### Accuracy-Optimized (API/SDK default) * Highest-fidelity output with exact hierarchy and table preservation. * Best for long technical docs, contracts, research papers, and compliance data where precision is critical. * May take more time to process very large files (100+ pages). #### Speed-Optimized (SaaS UI default) * Delivers fast results with strong accuracy—ideal for everyday files, batch runs, or time-sensitive workflows. * Handles large files efficiently while maintaining usability. View documentation [here](/flow/sdk/data-engine/file-ingestion#the-method-paramter) #### Chunking Methods: ##### Manual Window Chunking (API/SDK) * Fixed-size sliding window with overlap and support for ---DOCUMENT\_BREAK--- markers. * Predictable, user-controlled splits for more consistent chunking. * Ideal for resumes, multi-doc compilations, unstructured PDFs, narratives, or evaluation workflows. View documentation [here](/flow/sdk/data-engine/create-and-populate-a-vector-database) With these new options, you can adapt ingestion to the needs of each workflow: * Speed-Optimized mode processes massive batches of files, RFPs, or discovery documents in just minutes, perfect when turnaround time matters most. * Accuracy-Optimized mode preserves every detail in contracts, compliance records, or research papers, ensuring the cleanest structure and hierarchy extraction. * Manual Chunking gives you complete control over splitting less structured content, including resumes, multi-document compilations, and narratives. This ensures consistent chunks for vector databases and downstream workflows. ### Minor Bug Fixes & Stability Improvements This release includes a series of behind-the-scenes updates to improve overall platform performance, usability, and reliability. From small interface refinements to enhanced error handling and support resources, these updates ensure a smoother and more consistent experience across SeekrFlow. > New Feature ## Agent Structured Outputs You can now define structured response formats for SeekrFlow™ agents, available through the API and SDK. This capability allows developers to enforce specific schemas for agent outputs, ensuring integration-ready responses from the first generation. By eliminating the need for post-processing or custom parsers, structured outputs simplify development and enable more reliable downstream workflows View Documentation [here](/flow/sdk/agents/structured-outputs) > Improvements & Bug Fixes ### New SeekrFlow UI We’ve launched one of the biggest SeekrFlow updates to date: a redesigned UI that makes agent creation and experimentation more accessible, and intuitive. * Agents for Everyone: You can now create, configure, and chat with agents directly in the UI. * Guided forms simplify model, tool, and policy selection. * Built-in conversation scaffolding means no manual thread setup. * Test agents instantly in the new Agent Chat sandbox. #### New SeekrFlow Dashboard:: * Quick-Start tiles let you jump directly into creation: AI-Ready Data, Fine-Tune, Create an Agent, and Playground. * Tabbed Recent Work view for Fine-Tuning and Agents, complete with status badges. * Deployment snapshot panel showing current deployment counts and live token usage meters. #### UI Enhancements: * A complete visual reskin for a modern, polished look. * Reorganized left navigation aligned to real workflows: * Data Engine: New Storage section for managing files and vector stores * Development: Fine-Tuning, Agents, Deployments, and Model Library * Playground * Refreshed layout and graphics to improve clarity and usability. * Inline “Learn More” links for quick, contextual guidance. This update makes SeekrFlow more accessible to both technical and non-technical users, enabling fast agent prototyping and evaluation straight from the browser. The new dashboard supports faster onboarding, agent-first workflows, and one-screen deployment health checks. It also lays the foundation for future platform capabilities. ### Minor Bug Fixes & Stability Improvements This release includes a number of behind-the-scenes updates, bug fixes, performance tuning, and workflow stability improvements to ensure a smoother, more reliable experience across SeekrFlow. > New Feature ### SeekrFlow™ AgentsToday, we’re launching SeekrFlow™ Agents, a full-stack solution for building and deploying intelligent agents that operate autonomously, securely, and at scale. With SeekrFlow Agents, enterprises can deploy agents that are secure, explainable, and optimized for their specific tasks and industry. With SeekrFlow, you get the flexibility to run agents across cloud and on-premises—delivering the infrastructure and control needed to embed agentic AI into real-world workflows.​ Read the full blog: [here](https://www.seekr.com/blog/introducing-seekrflow-agents/)\ View documentation: [here](/flow/app/agent-builder) ### Seekr partners with Oracle Cloud InfrastructureSeekr has signed a multi-year agreement with Oracle Cloud Infrastructure (OCI) to accelerate AI deployments and support the development of next-gen models and agents. This collaboration brings together Seekr’s secure AI platform, OCI’s high-performance infrastructure, and AMD Instinct™ MI300X GPUs to enable faster model training, scalable deployment, and support for mission-critical environments. Learn more: [here](https://www.seekr.com/blog/seekr-selects-oracle-cloud-infrastructure/) ### Agent performance configurationsSeekrFlow Agents now offer three performance configurations, giving you control over the speed-latency tradeoff based on your use case requirements. Configuration selection available through API, SDK, and UI Choose from three agent configurations when creating or deploying agents: * Performance optimized: Highest quality responses with comprehensive reasoning (current default) * Speed optimized: Fastest response times for time-sensitive applications Learn more: [Agents](/flow/components/agents) ### Code interpreter tool for agentsSeekrFlow Agents can now execute Python code dynamically using the code interpreter tool, enabling agents to perform calculations, data analysis, and programmatic tasks on demand. * Execute Python code within agent workflows to handle computational tasks * Access to common Python packages for data processing and analysis * Agents automatically determine when to invoke Code Interpreter based on user queries * Available alongside File Search and Web Search tools when configuring agents * Full tool management through the UI, including status tracking and usage instructions * Code Interpreter expands agent capabilities beyond information retrieval, allowing them to perform quantitative analysis, generate visualizations, and solve mathematical problems programmatically. Learn more: [Code Interpreter](/flow/sdk/agents/custom-tools) > New Feature ### SeekrFlow™ Available in AWS Marketplace We’re excited to announce that SeekrFlow™, is now available on AWS Marketplace. This listing gives AWS customers a streamlined way to deploy SeekrFlow directly within their environments, accelerating AI adoption while maintaining full control over security, compliance, and procurement. Read the launch blog [here](https://www.seekr.com/blog/seekrflow-now-available-in-aws-marketplace/) > Improvements & Bug Fixes ### General Improvements and Workflow Stability We’ve made several updates to improve platform reliability and user experience. This includes enhanced model cards that now display model-specific information, and updated links to our Privacy Policy and Terms & Conditions to ensure greater transparency. These refinements, along with ongoing stability and performance enhancements, help ensure a smoother and more trustworthy workflow across SeekrFlow. > Improvements & Bug Fixes ### Multi-Factor Authentication (MFA) Seekr now supports MFA for all user sign-ins. After entering their credentials, users are guided to select and complete a second-factor verification via: * TOTP (Time-based one-time password) through authenticator apps * SMS one-time codes * Email one-time codes This adaptive login flow automatically directs users to their configured method (or lets them choose if multiple factors are set up), ensuring a seamless yet secure sign-in experience. ### In-App Help & Support AccessWe have made it easier for users to access help right when they need it. A new “Help” label now appears next to the question icon in the top navigation bar. ### Editable Project Titles and Descriptions We have introduced inline editing for project titles and descriptions on the Project Details page, making it faster and easier to manage key project information. * Titles can now be updated inline and are limited to 100 characters. * Descriptions support multiline editing and are capped at 1,000 characters. These updates provide a more flexible and user-friendly way to keep project details accurate and up to date. > New Feature ## Multi-file Ingestion Today, we’re introducing multi-file ingestion, a new feature within SeekrFlow™. This capability simplifies and accelerates the process of automatic generation of a fine-tuning dataset. With multi-file ingestion, you can now upload a set of files across multiple formats, all in one step. SeekrFlow automatically converts, merges, and structures the content into markdown (.md) that is AI-ready, eliminating the need for manual formatting or stitching files together. To learn more, read the [launch blog](https://www.seekr.com/multi-file-ingestion-in-seekrflow/). > Improvements & Bug Fixes ## General Improvements and Workflow Stability We have implemented several small bug fixes and performance enhancements to improve the data creation workflow, including updated instructional copy, clearer conversion progress indicators, refined exit warnings, and a more streamlined experience from upload to completion. > New Feature ### Vector databases for enhanced retrieval SeekrFlow introduces vector database capabilities that give you complete control over document ingestion, chunking, and semantic search for retrieval-augmented generation (RAG) workflows. * Create and manage vector databases with configurable embedding models, dimensions, and distance metrics. * Ingest documents using flexible chunking strategies—choose automatic chunking with smart defaults or define custom parameters for chunk size and overlap. * Search across ingested documents using hybrid retrieval that combines semantic and keyword-based search. * Fine-tune search results with ranking options and relevance thresholds to control response quality. * Ingest multiple documents at once by organizing files into collections. This release gives developers the infrastructure needed to build production RAG applications with precise control over how documents are processed and retrieved. For more information, see the [launch blog](https://www.seekr.com/blog/enhanced-retrieval-teaching-ai-to-structure-and-prioritize-retrieved-knowledge/) and [Vector Stores](/flow/app/vector-stores). ### AI Ready Data EngineWe have launched the Seekr AI-Ready Data Engine, a powerful new system within the SeekrFlow™ platform that transforms diverse enterprise data into a structured, AI-ready format—faster, more accurately, and at a lower cost. This intelligent, end-to-end pipeline eliminates manual bottlenecks, ensuring seamless integration and deployment of high-quality, trustworthy AI applications. To learn more, read the [launch blog](https://www.seekr.com/introducing-the-seekr-ai-ready-data-engine/). ### API Key Management Users can generate their own API keys directly from their profile. This enhancement streamlines access management and improves user autonomy and security, ensuring a seamless developer experience. ### How to create your API Key * Users can generate an API key by clicking the “+ Generate Key” button in their profile. * The system will securely generate and return a unique API key. * Once generated, users will be prompted to save their key before exiting. > Improvements & Bug Fixes ### Updated User Profile Page with Navigation The SeekrFlow user profile page has been redesigned with a new sub-navigation component, improving accessibility and ease of use. The page is now labeled "My Account" and includes two sections: * Profile: which serves as the default landing page * API Key: where users can generate and manage their API access. This update provides a more intuitive way to navigate account settings. ### Bug Fixes and Stability Improvements We have implemented several small bug fixes and performance enhancements to further optimize SeekrFlow. These updates improve the platform’s overall stability and ensure a smoother, more reliable experience for users. > UI/UX Enhancements ### Improved User Profile Experience Enhanced the User Profile experience with a new User Details section, including profile editing, password updates, sign-out functionality, and cookie settings management. > New Feature ### Training Loss Chart in Run Details We have added a dynamic training loss chart to the Run Details page, providing users with critical insights into model performance during fine-tuning: * **Y-Axis**: Displays loss values to indicate model performance trends. * **Upper X-Axis**: Shows the number of epochs selected during run creation. * **Lower X-Axis**: Represents "steps," calculated as:\ Total Steps = (Total Number of Samples ÷ number of instances \* Batch Size) × Number of Epochs This new feature enables users to track loss convergence and make informed adjustments, reducing the number of repeated fine-tuning cycles needed to optimize results. By minimizing fine-tuning runs, it saves time, compute resources, and associated costs. > Improvements & Bug Fixes ### Enhanced Data Ingestion Users can now upload ***Markdown, PDF, and Word*** files as valid file types for data ingestion during data creation. This update, available on API and SDK, makes working with diverse data formats easier, streamlining the ingestion process and reducing the need for file conversions. ### Expanded Base Model Library The base model library now includes the **Mistral-7B-Instruct-v0.2** model from Mistral AI. This model is available for fine-tuning, inference, and testing in the Sandbox, offering more options to tailor your AI solutions. ### Bug Fixes and Stability Improvements Small bug fixes and performance updates to make SeekrFlow™ smoother and more reliable for users. # Release notes 2026 Source: https://docs.seekr.com/flow/changelog/seekr-managed/2026 ## Fine-tuning jobs fill in hyperparameter defaults automatically Fine-tuning jobs compute default hyperparameters for you. Omit `batch_size` or `learning_rate` from a `TrainingConfig` and SeekrFlow derives each from the selected algorithm, model size, and dataset size. Set either value to override its default. `n_epochs` remains required. See [Create a fine-tuning job](/flow/sdk/fine-tuning/create-fine-tuning-job). ## Platform improvements and fixes This release includes the following improvements and fixes: * Intermittent ingestion failures caused by periodic restarts of the ingestion service have been eliminated. * The AI-ready data engine draws on more context when recursively summarizing long documents, improving summary quality. * Ingestion memory usage and processing speed have been optimized. ## Clone an existing data job Clone any existing data job into a new, editable job pre-populated from the original's configuration. The clone starts fresh as an editable job you can adjust before starting alignment, and you can give it a new name or reuse the original's. Cloning is useful for iterating on instructions or reusing a file set across related datasets. See [Clone a data job](/flow/sdk/data-engine/manage-data-jobs#clone-a-data-job). ## Trace agent instructions as a context attribution source Context attribution now traces influence from a new source type, agent instructions. When a statement in an agent's response is shaped by the agent's own system prompt rather than retrieved content, attribution results surface the specific prompt segment and its influence score. Sources of type `system_prompt` carry the core attribution fields: `source_type`, `id`, `text`, `attribution`, and `offset`. See [Context attribution](/flow/components/explainability/context-attribution) for the full list of source types, or the [SDK guide](/flow/sdk/explainability/context-attribution) for the response structure. ## View snippets and full page content for web search sources Context attribution represents web search results under a single source type that covers both search result snippets and full fetched page content. The source text reflects what the agent retrieved, so a web search source may surface a short snippet or a longer passage. See [Context attribution](/flow/components/explainability/context-attribution) for source types, the [SDK guide](/flow/sdk/explainability/context-attribution) for the response structure, or [Understand a response](/flow/app/understand-a-response) for the Sources panel. ## Trace agent responses to MCP tool outputs Context attribution now traces influence from MCP (Model Context Protocol) tool responses. When an agent calls an MCP tool during a response, such as querying a CRM or an issue tracker, the tool's response becomes an attributable source, so you can see which integrations shaped specific statements. This includes sub-agents the agent invokes as tools, which appear as MCP tool sources. See [Context attribution](/flow/components/explainability/context-attribution) for the full list of source types. ## Submit large file batches for ingestion in a single call Ingestion accepts large file batches in a single submission, including batches of 5,000 files or more. Submission time stays constant regardless of batch size. Large batches no longer need to be split into smaller ones to keep submissions responsive. See [Prepare and ingest files](/flow/sdk/data-engine/file-ingestion). ## Ingest plain-text files and rely on automatic file healing The AI-ready data engine accepts plain-text (`.txt`) files for ingestion, alongside Markdown, PDF, Word, and PowerPoint. It also corrects common formatting problems automatically: Markdown files with headers deeper than six levels are accepted instead of rejected, and files with missing or malformed elements are repaired where possible. If a file can't be repaired, the job stops and reports the specific issue to fix before resubmitting. See [Prepare and ingest files](/flow/sdk/data-engine/file-ingestion). ## Data jobs stop early when they can't produce useful data SeekrFlow validates each data job before it begins generating data and stops the job early when it can't produce useful results, avoiding token usage on a job that wouldn't succeed. A job is stopped when its instructions are empty, its instructions can't be interpreted as a data-generation task, its uploaded documents don't match the instructions, or no document content is relevant enough to the instructions. Each case sets a distinct `status_message` describing the cause and the adjustment to make before resubmitting. SeekrFlow also emails you when a job is stopped this way, with the job ID, source file, reason, and steps to resubmit. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). ## Summarize the metadata in a vector database A metadata snapshot summarizes the user-defined metadata across a vector database's chunks, capturing the most common keys, their most frequent values, and each key's inferred type. Generate a snapshot to see what metadata your ingested documents carry. The snapshot captures up to the 100 most common keys, with up to the 10 most common values each. It refreshes automatically after an ingestion job adds documents, and can be regenerated or retrieved on demand. See [Generate a metadata snapshot](/flow/sdk/data-engine/generate-metadata-snapshot). ## Guide dataset generation with data job instructions Data jobs accept an `instructions` field that describes the task your generated dataset should support. Alignment uses it to shape the examples it produces, such as the topics and the kinds of questions a fine-tuned model should be able to handle. Set instructions when you create a data job, or update them on an existing job. Data jobs no longer include a separate `description` field. For details, see [Create instruction fine-tuning data](/flow/sdk/data-engine/standard-instruction-finetuning) and [Manage data jobs](/flow/sdk/data-engine/manage-data-jobs). ## Track alignment job progress in real time The alignment job status endpoint returns richer progress data, so you can follow a running job from start to finish. Each response from `GET /v1/flow/alignment/{alignment_job_id}` surfaces the current processing step, progress through that step, overall completion, a projected completion time, estimated minutes remaining, and a human-readable status message. ## Platform improvements and fixes This release includes the following improvements and fixes: * Requesting data job outputs before a job completes now returns a clear error instead of partial results. * Stuck ingestion jobs restart automatically. * Model serving reliability and performance improvements. * General platform stability improvements. ## Context-grounded fine-tuning is deprecated SeekrFlow is deprecating context-grounded fine-tuning and will remove it on July 17, 2026. You can keep using it until then. For new projects, choose another [fine-tuning method](/flow/components/fine-tuning#fine-tuning-methods). ## Score reinforcement tuning outputs with an LLM judge Reinforcement tuning reward functions can now use an LLM grader (LLM-as-a-judge) to score candidate responses. The judge compares each response to the reference answer and rates how closely it matches in meaning and quality. This suits open-ended or subjective outputs where deterministic graders such as string check and text similarity are too rigid. The LLM grader takes no operation. It accepts optional generation parameters (temperature, top\_p, seed, and max\_completion\_tokens) that control how the judge produces its scores, and it combines with other graders through weights like the existing grader types. For details, see [reinforcement tuning](/flow/components/fine-tuning/grpo) and the [reinforcement tuning SDK guide](/flow/sdk/fine-tuning/grpo-fine-tuning). ## Add, filter, and edit custom chunk metadata You can attach user-defined metadata to the chunks in a vector database and use it to refine retrieval. Add a flat set of fields, such as year, document type, or confidentiality level, when you ingest files, then list or filter chunks by those fields using exact matches or range operators. Metadata on existing chunks can also be edited, targeted by chunk or by file. Filtering by metadata improves retrieval precision on large, mixed collections where time period, document type, or business unit matters. For details, see [Manage chunk metadata](/flow/sdk/data-engine/manage-chunk-metadata) and [Create and populate a vector database](/flow/sdk/data-engine/create-and-populate-a-vector-database). ## Trace agent responses back to their source documents Source tracing connects an agent response to the exact location in the document it came from. When a file is ingested into a vector database, provenance metadata is captured for every chunk, including its line range, character offsets, heading hierarchy, and source page. File search results carry this metadata, and a chunk endpoint returns the full provenance record, including the original file ID, so you can follow a response from model output back to the source document. This supports auditability, compliance, and chain-of-custody workflows. For details, see the [source tracing overview](/flow/components/explainability/source-tracing) and the [source tracing developer guide](/flow/sdk/explainability/source-tracing). ## Partially update agents and tools New PATCH endpoints for agents and tools update individual fields without requiring the full configuration. Only the fields included in the request are changed; omitted fields remain unchanged. Use the corresponding diff endpoints to preview changes before applying them. * Update an agent: [SDK](/flow/sdk/agents/create-agents#update-an-agent) | [API](/flow/reference/patch_v1_flow_agents__agent_id__patch) * Preview an agent update: [SDK](/flow/sdk/agents/create-agents#preview-an-agent-update) | [API](/flow/reference/diff_v1_flow_agents__agent_id__diff_patch) * Update a tool: [SDK](/flow/sdk/agents/tools#update-a-tool) | [API](/flow/reference/patch_tool_v1_flow_tools__tool_id__patch) * Preview a tool update: [SDK](/flow/sdk/agents/tools#preview-a-tool-update) | [API](/flow/reference/diff_tool_changes_v1_flow_tools__tool_id__diff_patch) ## Control agent reasoning with effort levels and temperature Agents support finer control over how they reason through a request. * `reasoning_effort` accepts `low`, `medium`, or `high`, with `medium` as the default. The `speed_optimized` and `performance_optimized` values remain supported as legacy options. * `temperature` controls the predictability of the agent's reasoning, accepting a value from `0` to `2` with a default of `0.6`. Lower values produce more consistent results, and higher values introduce more variation. See [Configure reasoning effort](/flow/sdk/agents/create-agents#configure-reasoning-effort) for details. ## Edit agents directly in the UI You can now edit an agent's configuration directly from the UI. Select an agent from the agents list and click **Edit** to update its name, instructions, model, or tools. For details, see [Manage agents](/flow/app/manage-agents). ## MCP connector support for agents Agents can now connect to external Model Context Protocol (MCP) servers using the MCP connector tool. SeekrFlow routes outbound requests through a secure internal gateway and handles authentication and token refresh automatically. To set up an MCP connector tool, create it via the API or SDK with your MCP server URL. Three authentication modes are supported: * Servers with dynamic client registration (DCR) * OAuth servers without DCR (bring your own `client_id` and `client_secret`) * Unauthenticated servers OAuth-based modes require a one-time authorization step before the tool becomes active. Once active, the tool can be linked to any agent. For more information, see [MCP connector](/flow/sdk/agents/mcp-connector). ## Role-based access control for team collaboration SeekrFlow now supports role-based access control (RBAC), opening up team-based development across the platform. Resources — including agents, fine-tuning jobs, deployments, files, and vector databases — are owned by teams and accessible to all members of that team based on their assigned role. Key concepts: * **Organization** – The top-level container. All users belong to one organization. * **Teams** – Where work happens. Resources are scoped to a team. * **Roles** – Organizations have Owner and Member roles; Teams have Admin and Creator roles. Users can belong to multiple teams and switch between them using the team switcher in the UI. Agent conversation history (threads) remains user-owned and is not shared with team members. **Existing users:** All users have been migrated into an organization, and existing resources now live in a private team scoped to you. Select users have been assigned the Owner role. To get started, create a Team for a shared workstream, add members, assign roles, and use the team switcher to move between contexts. See [Role-based access control](/flow/role-based-access-control) and [Managing permissions](/flow/app/manage-permissions) for details. ## Track file and vector database dependencies across your environment New usage endpoints surface file and vector database dependencies across tools, agents, and data jobs in your SeekrFlow environment. **File usage endpoints** return the downstream dependencies of a given file: * `GET /files/{file_id}/vector-dbs` – Vector databases that ingested this file. * `GET /files/{file_id}/data-jobs` – Data jobs that reference this file. * `GET /files/{file_id}/derived-files` – Derived files produced from this file. **Vector database usage endpoints** return what depends on a given database: * `GET /vectordb/{database_id}/tools` – File search tools that reference this database. * `GET /vectordb/{database_id}/data-jobs` – Data jobs with this database set as the vector database. With the `GET /tools/{tool_id}/agents` endpoint, you can trace the full dependency chain from a file or vector database to the agents that surface it. Use these endpoints to understand usage before deleting or migrating resources, or to audit data lineage across your workflows. For more information, see [File usage](/flow/components/data-engine/storage#file-usage). ## Manage the full AI-ready data pipeline through a single job ID The Data Jobs API and SDK introduce a unified way to manage the full AI-ready data pipeline — from file upload and ingestion through alignment — under a single job ID, replacing fragmented multi-call workflows. * Create and manage data jobs via REST endpoints (`/v1/flow/data-jobs`) and Python SDK helpers (`client.data_jobs.*`). * Attach files with automatic ingestion using accuracy- or speed-optimized modes. * Remove files or failed records before alignment to keep workflows clean. * Edit job metadata, system prompt, and vector database ID at any time. * Start, cancel, and monitor alignment with pre-flight validation and structured error responses. * Track per-file ingestion status, queue position, and suggested fixes through a single job record. * Supports three job types: principle files, context-grounded files, and context-grounded vector DB. ## Create and manage tools from Agent Builder The Tool Library is now accessible from the SeekrFlow web interface, giving you a dedicated workspace to create and manage tools without writing code. Navigate to Agent Builder > Tool Library in the sidebar. From the Tool Library you can: * **Create tools** – Build File Search and Web Search tools directly in Agent Builder, including tool instructions and, for File Search, source files and search parameters. * **View and manage tools** – See all your tools in one place with status indicators, creation dates, and last modified dates. * **Inspect tool details** – Click any tool to see its full configuration, model information, and which agents are using it. * **Edit, clone, and delete** – Manage tools from either the list view or the tool summary panel. ## Trace agent responses to their sources Each sentence or chunk of an agent's response is shaded to reflect how heavily it relied on retrieved context. Clicking any sentence surfaces its top contributing sources ranked by influence score. Attribution covers vector DB retrieval and web search. Controls for evidence depth, granularity, and influence filtering are user-configurable and persist per agent thread. Attribution can run automatically alongside a response at inference time, or be applied post-inference to any existing output. Attribution currently covers vector DB retrieval and web search tool results. Custom tools and sub-agents are not in scope for this release. ## Parallel tool execution for agents SeekrFlow agents now support parallel execution of tool plans, improving efficiency for runs that involve multiple independent tool calls. The planner can express execution dependencies between steps, so tool calls without dependencies are executed concurrently. **Capabilities:** * Planner-generated execution plans support dependency-aware step ordering * Independent tool calls can be executed in parallel rather than strictly sequentially * Executor automatically resolves execution order based on planner-defined dependencies This improves the efficiency of agent runs that require multiple tool invocations, particularly when steps can be performed independently. ## Preference tuning (DPO) Model alignment using direct preference optimization (DPO), training models from comparison data rather than ground truth or reward functions. Preference tuning trains models to increase the likelihood of generating preferred responses over rejected ones. **Capabilities:** * Upload preference datasets containing prompt, chosen response, and rejected response * Automatic schema validation on upload * Optional `beta` hyperparameter to control KL-divergence strength * Compatible with all base models supported by SeekrFlow * Training loss tracking identical to supervised fine-tuning Preference tuning supports alignment for subjective criteria like brand tone, compliance standards, and customer experience preferences where correctness is context-dependent. Preference datasets must be user-provided. The AI-ready data engine does not yet generate preference datasets. ## Reinforcement tuning reward functions Configurable reward functions for reinforcement tuning jobs, enabling users to control which behaviors get reinforced during training. Reward functions are built from graders—individual scoring operations that can be used alone or combined into weighted, linear rewards. **Capabilities:** * Grader types: math accuracy, string check, and text similarity * Reward composition: single grader or weighted linear combination of multiple graders * Optional format reward weight to control `` / `` formatting enforcement * Built-in weight validation and normalization This release also rebrands "GRPO" to "Reinforcement Tuning" in the API and SDK. Reward functions enable customers to explicitly reinforce task-specific objectives like correctness, policy adherence, or stylistic consistency, establishing the foundation for future evaluation platform capabilities. ## Vision-language fine-tuning Instruction fine-tuning for vision-language models (VLMs) that reason jointly over images and text. Users can now fine-tune multimodal models using datasets combining visual inputs and natural language through the same fine-tuning workflows used for text-only models. **Capabilities:** * Upload and validate vision-language datasets with messages-based schema and image support * Fine-tune supported VLMs: `Qwen2.5-VL-7B-Instruct` and `Llama-3.2-11B-Vision-Instruct` * Automatic schema validation and seamless job creation * Standard instruction tuning workflow with no separate multimodal configuration required This release supports instruction tuning only. Reinforcement learning and preference tuning are not yet supported for vision-language models. ## Tools library Centralized workspace for managing agent tools across your organization. The tool library serves as a single source of truth where users can create, update, delete, and duplicate tools independently of agent configuration. **Capabilities:** * Create and manage web search and file search tools with custom configurations. * View code interpreter and custom function tools (read-only). * Duplicate existing tools to create variations with modified configurations. * Automatic propagation of tool updates to all agents using that tool. * Select pre-created tools during agent creation or create new tools inline. * Query tools by type and status, and view which agents are using specific tools. Tool changes automatically redeploy linked active agents to reflect updates across your organization. ## Ingestion insights Real-time visibility into file ingestion status across Alignment and VectorDB endpoints. Every uploaded file receives its own persistent ingestion record that tracks progress through conversion, alignment, and vectorization. **Capabilities:** * Per-file status tracking (queued, running, completed, failed) with queue position and timestamps. * Plain-language error messages with suggested fixes. * Structured metadata through file\_records view showing which files are processing, completed, or blocked. * Consistent response schema across Alignment and VectorDB endpoints. This visibility layer enables faster self-service debugging and reduces support escalations during onboarding, proofs of concept, and production workflows. ## Multi-node fine-tuning Distributed training across multiple compute nodes for improved fine-tuning performance and scalability. Multi-node fine-tuning distributes training jobs across multiple physical nodes (each with 8 GPUs), enabling parallel execution rather than single-machine training. **Capabilities:** * Support for 1–4 nodes (up to 32 GPUs total) * Configure node count via n\_node parameter in InfrastructureConfig * Automatic distributed orchestration and synchronization * Immediate validation of supported n\_node / n\_accel combinations This enables reduced training time for larger datasets, better compute allocation matching dataset size and training needs, and establishes the foundation for future support of larger models. # Release notes 2025 Source: https://docs.seekr.com/flow/changelog/self-hosted/2025 ## Self-hosted reaches feature parity with Seekr-managed This release brings self-hosted SeekrFlow to feature parity with Seekr-managed deployments, adding explainability, agent, fine-tuning, and ingestion capabilities to self-hosted environments. **Explainability** * Context attribution traces model responses to the retrieved context that informed them. * Data attribution links inference outputs to contributing training data. Logfire-based tracing is not available in self-hosted deployments. **Agents** * Tool Library v2 with expanded tool management. * Multi-agent orchestration is now generally available for coordinating agents across tools and tasks. **Fine-tuning** * Vision-language fine-tuning for supported vision models. * Reinforcement-tuning reward functions for controlling which behaviors are reinforced during training. **Ingestion** * Ingestion insights surface job status and failure diagnostics for ingestion pipelines. **Platform** * vLLM upgrade (0.19.0) on ROCm for improved inference on AMD GPUs. * Chainguard-based container images for a hardened, minimal-CVE deployment footprint. ## Initial self-hosted release of SeekrFlow First self-hosted release of SeekrFlow, bringing the platform to customer-managed environments with fine-tuning, inference, agent, and ingestion capabilities. **Agents** * Docstring validation for improved agent runtime performance. **Fine-tuning** * Reinforcement tuning (GRPO). **Ingestion** * Faster ingestion with pipeline performance improvements. **AI-ready data** * Quality improvements to principle alignment. **Inference** * vLLM upgrade (0.11.1). * Expanded selection of supported models. **Authentication** * Authentication support for custom solutions. # Release notes 2026 Source: https://docs.seekr.com/flow/changelog/self-hosted/2026 ## Serve inference through AWS Bedrock and Azure AI Foundry Cloud service provider inference adds support for Azure AI Foundry, alongside AWS Bedrock. ## AWS Bedrock support extended to ingestion pipelines SeekrFlow ingestion pipelines now support AWS Bedrock for embedding generation and PDF-to-Markdown conversion. * Embedding generation for vector databases and RAG workflows can now run on AWS Bedrock. * PDF-to-Markdown conversion uses Bedrock-compatible vision models, supporting AI-ready data jobs for synthetic dataset generation and downstream fine-tuning. * Using a `bedrock:`-prefixed model automatically routes embedding requests to AWS Bedrock. * Vector databases created with Bedrock models use Titan embeddings for indexing and retrieval. ## Self-hosted platform update This update expands platform availability and adds new capabilities across agents, orchestration, and deployment environments. **New platform support** SeekrFlow now supports Oracle Cloud Infrastructure (OCI). Organizations can deploy SeekrFlow on OCI environments running NVIDIA GPUs, expanding deployment options for customers with Oracle cloud infrastructure requirements. OCI support currently includes: * SeekrFlow UI * SeekrFlow API **Agents** * Tool Library support for agents * Multi-Agentic Orchestration (Beta) — agents can coordinate across multiple tools and tasks **Platform** * OCI deployment support via Helm * vLLM upgrade improving inference performance on NVIDIA GPUs ## Self-hosted platform update Updates for self-hosted SeekrFlow deployments on AWS, AWS GovCloud, and Appliance environments. **Agents and inference:** * AWS Bedrock inference support for agents with cloud service provider-hosted inference * Full agent execution including tools, streaming, and promotion/demotion workflows * Multi-LoRA inference with hot loading * `vLLM` upgrade for improved performance and stability * CSP inference routing to Bedrock endpoints based on region and model availability **Fine-tuning:** * LoRA support for reinforcement (GRPO) and instruction fine-tuning (NVIDIA-based) **Explainability:** * Inference-time data attribution **UI and documentation:** * Dark mode support * Documentation updates covering new inference, agent, and fine-tuning capabilities ## AWS Bedrock inference for agents AWS Bedrock inference support for SeekrFlow Agents, providing an alternative to Seekr-hosted GPU inference. Agents can now use `Claude 4.5` via AWS Bedrock for all intra-agent inference (planner, executor, evaluator, summarizer). **Capabilities:** * Full end-to-end agent execution including Agent Chat in the UI, streaming and non-streaming runs, and multi-tool execution * Bedrock models appear in existing agent model-selection UI * Configure at deploy time via Helm (EKS-only) * Deployments select either Bedrock inference or Seekr-hosted GPU inference **Current limitations:** * Agents only (Model Chat is disabled when Bedrock is enabled) * File search and vector-backed retrieval not yet supported for Bedrock agents * Reasoning and speed optimization parameters are ignored to ensure consistent execution # Components Source: https://docs.seekr.com/flow/components Detailed overview of SeekrFlow's key components and architecture. This section provides conceptual information about SeekrFlow's core components and how they work together to enable end-to-end AI development. ## Understanding components SeekrFlow components are the building blocks of the platform. Each component serves a specific purpose in the AI development lifecycle, from preparing data to deploying production models. Understanding how these components work—both individually and together—helps you design effective AI solutions. ## Core components Configurable AI systems that reason through problems and execute tasks autonomously. Agents combine models and tools to handle everything from simple workflows to complex, open-ended objectives. **When to use:** Building AI systems that need to make decisions, use tools, and take actions to accomplish goals. Transforms raw content into structured, AI-ready datasets for training and retrieval. Includes file storage, vector databases, and automated data preparation workflows. **When to use:** Preparing your data before fine-tuning models or creating retrieval systems for agents. Automates the creation of training datasets to adapt pre-trained models to specific domains or use cases. Supports both instruction fine-tuning and context-grounded fine-tuning. **When to use:** Customizing model behavior for domain-specific knowledge or specialized tasks. Launch, monitor, and manage model endpoints for real-time inference. Provides deployment automation and production monitoring dashboards. **When to use:** Making trained or fine-tuned models available for production use. Understand model outputs by tracing responses to the sources and training data that influenced them. Surfaces which retrieved context or training examples contributed to specific model responses. **When to use:** Debugging model outputs, auditing decisions, or building trust in AI systems. Evaluate text safety and brand risk with specialized moderation models including Seekr ContentGuard and Meta Llama Guard. **When to use:** Assessing content safety, brand suitability, or policy compliance. Monitor agent performance by capturing a record of every run, including timing, model usage, token consumption, and errors. **When to use:** Monitoring agent health, investigating failed runs, or understanding usage and costs. ## How components work together A typical AI development workflow connects multiple components: 1. **Data engine** – Upload and prepare your source data 2. **Fine-tuning** – Train models with your prepared data (optional) 3. **Deployments** – Deploy trained models for inference 4. **Agents** – Build AI systems using deployed models and tools 5. **Explainability** – Understand and validate model outputs 6. **Content moderation** – Ensure outputs meet safety standards 7. **Observability** – Monitor agent performance and investigate runs Not every workflow uses all components. Simple use cases might only use agents with base models, while complex enterprise applications might leverage the full platform. # Agents Source: https://docs.seekr.com/flow/components/agents Configurable AI systems that reason through problems and execute tasks autonomously. An agent is an AI system that reasons through problems and executes tasks autonomously. Agents are configured by specifying models, tools, instructions, and reasoning approach—providing everything needed to accomplish tasks from simple workflows to complex, open-ended objectives. Create and manage agents through the SeekrFlow web interface. Create and manage agents programmatically with the Python SDK. ## Agent primitives Agents are built from two core primitives: A model serves as the agent's cognitive engine, providing the reasoning capabilities needed to understand tasks, determine the best course of action, and generate responses. SeekrFlow supports both base models and fine-tuned models. Tools are modular components that extend an agent's capabilities beyond built-in reasoning. With tools, agents can take actions, access external systems, or query knowledge stores. ## Agent configuration When creating an agent, you configure several key properties: | Property | Description | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | Identifier for the agent | | **Instructions** | System prompt that guides how the agent operates and generates its response (also called developer message) | | **Model** | Which model to use for generating responses (can be a base model or fine-tuned model) | | **Tools** *(optional)* | Which tools the agent can access | | **Reasoning effort** *(optional)* | Controls how much reasoning the agent uses. Default is `medium`. | | **Temperature** *(optional)* | Controls the predictability of the agent's reasoning. Lower values produce more consistent results, and higher values introduce more variation. Default is `0.6`. | ## Reasoning effort Reasoning effort controls how much reasoning the agent uses when working through a request. The default is `medium`. | Level | Description | | ---------- | ------------------------------------------------------------------------------------------------------------ | | **Low** | Prioritizes speed. Best for simple, latency-sensitive tasks with a small tool set. | | **Medium** | Balances speed and thoroughness. A good starting point for most use cases. | | **High** | Prioritizes thoroughness. Best for complex workflows with many tools where accuracy matters more than speed. | ## Agent status Each agent has a status that indicates its deployment state: | Status | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | **Active** | Ready to serve requests | | **Pending** | Transitioning between states. Either recently promoted and moving to active, or recently demoted and moving to inactive. | | **Updating** | An update is in progress. Returns to active once changes take effect. | | **Inactive** | Not currently deployed, requires activation before serving requests | | **Failed** | Deployment failed. The agent cannot serve requests. To recover, address the issue and promote the agent manually. | ## Multi-agent workflows Agents can delegate subtasks to other agents using the agent-as-tool pattern. A supervisor agent remains in control throughout a run, invoking sub-agents as callable tools to handle specialized tasks and then integrating their results into a unified response. This enables composable, multi-agent systems where each agent focuses on a specific capability. For implementation details, see [Agent as tool](/flow/sdk/agents/agent-as-tool). # Models Source: https://docs.seekr.com/flow/components/agents/models Models that serve as the cognitive engine for agents. A model serves as an agent's cognitive engine, providing the reasoning capabilities needed to understand tasks, determine the best course of action, and generate responses. Every agent requires a model to function. ## Model types SeekrFlow supports two types of models for agents: ### Base models Base models are pre-trained models available on the SeekrFlow platform. These models provide general-purpose reasoning capabilities and can handle a wide range of tasks without additional training. SeekrFlow supports various base models from leading providers: #### Meta Llama models | Model | Size | Best for | | ------------------------------ | ----------------- | ---------------------------------------------------- | | Llama 3.1 8B Instruct | 8B | Instruction-following, general assistant tasks | | Llama 3.1 70B Instruct | 70B | Complex reasoning, high-accuracy tasks | | Llama 3.3 70B Instruct | 70B | Latest generation complex reasoning | | Llama 3.2 1B/3B Instruct | 1-3B | Lightweight tasks, resource-constrained environments | | Llama 3.2 90B Vision Instruct | 90B | Multimodal image reasoning and visual Q\&A | | Llama 4 Scout 17B-16E Instruct | 109B (17B active) | Next-generation multimodal understanding | #### Qwen models | Model | Size | Best for | | ------------------------ | ----- | ---------------------------------------------- | | Qwen 2.5 3B Instruct | 3B | Multilingual instruction-following | | Qwen 3 8B/32B FP8 | 8-32B | Efficient multilingual reasoning | | Qwen 2.5 32B Instruct | 32B | Advanced multilingual instruction-following | | Qwen 2 72B | 72B | Advanced natural language tasks | | Qwen 2.5 72B Instruct | 72B | Large-scale multilingual instruction-following | | Qwen 2.5 VL 32B Instruct | 32B | Vision and language understanding | #### Mistral AI models | Model | Size | Best for | | ----------------------------- | ---- | -------------------------------------- | | Mistral 7B Instruct v0.2/v0.3 | 7B | Fast responses, chat applications | | Mistral Small 24B Instruct | 24B | Low-latency multilingual conversations | | Mamba Codestral 7B | 7B | Code generation and programming tasks | #### DeepSeek models | Model | Size | Best for | | ---------------------------- | ---- | -------------------------------------- | | DeepSeek R1 Distill Qwen 7B | 7B | Reasoning-focused conversational tasks | | DeepSeek R1 Distill Qwen 32B | 32B | Advanced reasoning at scale | #### Google Gemma models | Model | Size | Best for | | -------------- | ---- | ------------------------------------- | | Gemma 2B | 2B | Lightweight general tasks | | Gemma 2 9B | 9B | Balanced performance and efficiency | | Gemma 3 27B IT | 27B | Multilingual, multimodal capabilities | #### Other models | Model | Size | Best for | | -------------------------------- | ------- | ----------------------------------------------- | | Microsoft Phi-3 Mini 4k Instruct | 3.8B | On-device and resource-constrained environments | | TinyLlama 1.1B Chat | 1.1B | Ultra-lightweight chat applications | | OpenAI GPT-OSS 20B/120B | 20-120B | Reasoning and agentic tasks | For the complete list of available base models with detailed specifications, see the [Models API reference](/flow/reference/ml_models_v1_flow_models_get). ### Fine-tuned models Fine-tuned models are custom-trained models adapted to specific domains or use cases. These models are created through SeekrFlow's fine-tuning component, which embeds specialized knowledge and behaviors directly into model parameters. ## Selecting a model When configuring an agent, you specify which model to use. Consider these factors when selecting a model: * **Task complexity** – More complex reasoning tasks may benefit from larger or specialized models. * **Response requirements** – Balance between speed and accuracy based on your use case. * **Domain specificity** – Fine-tuned models perform better for specialized domains with unique terminology or requirements. * **Cost and performance** – Larger models provide enhanced capabilities but with higher computational costs. ## Model configuration Models are specified during agent creation and can be updated by modifying the agent configuration. The model works in conjunction with other agent components like instructions and tools to determine overall agent behavior. # Tools Source: https://docs.seekr.com/flow/components/agents/tools Tools extend what agents can do. While models provide reasoning capabilities, tools allow agents to take actions—accessing external systems, querying knowledge stores, executing code, or performing web searches to accomplish tasks. Create and manage tools through the SeekrFlow web interface. Create and manage tools programmatically with the Python SDK. ## How tools work When an agent receives a task, it evaluates which tools (if any) are needed and invokes them autonomously based on its instructions and the input. Each tool includes a description that helps the agent understand when and how to use it. Agents can use multiple tools within a single task to accomplish complex objectives. ## Tool configuration In the UI, tools are configured when creating or updating an agent. The agent has access only to the tools explicitly provided during configuration. The selection of which specific tools to invoke for any given task is determined by the agent based on its instructions and the task requirements. ## Tool library The tool library is a centralized workspace where you create and manage tools independently of agents. Instead of defining tools inline during agent creation, you create tools in the library and then link them to agents by tool ID. This approach lets you: * **Reuse tools** across multiple agents without duplicating configuration. * **Update a tool once** and have the change propagate to all agents using it. * **Manage tools centrally** — create, retrieve, list, update, duplicate, and delete tools from a single workspace. * **View linked agents** to see which agents use a given tool before making changes. ## Available tools SeekrFlow provides several tools for agents: | Tool | Description | Best for | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | [FileSearch](/flow/sdk/agents/filesearch-tool) | Semantic search and retrieval across vector databases. Results include source tracing fields (`chunk_id`, `page`, `lines`, `section`) for full provenance tracing back to the original uploaded file. | RAG applications, internal documentation search, knowledge base queries | | [WebSearch](/flow/sdk/agents/websearch-tool) | Real-time information retrieval from web sources | Research tasks, fact-checking, trend analysis, current events | | [Custom Tools](/flow/sdk/agents/custom-tools) | Developer-defined Python functions for specialized business logic, with built-in code execution for data analysis, calculations, and visualizations | External system integrations, proprietary data access, data analysis, specialized workflows | | [Agent as Tool](/flow/sdk/agents/agent-as-tool) | Delegate subtasks to another agent and return the result to the supervisor | Multi-agent workflows, task decomposition, specialized sub-agents | | [MCP connector](/flow/sdk/agents/mcp-connector) | Connect to external MCP providers through a secure gateway with OAuth-based authentication | Third-party service integrations, external data sources, cross-platform workflows | # Content moderation Source: https://docs.seekr.com/flow/components/content-moderation Evaluate text safety and brand risk with specialized moderation models. Content moderation provides access to specialized models for evaluating text safety and brand risk. These models classify content across various safety categories, supporting use cases from general-purpose text moderation to domain-specific brand safety assessment. ## Available models SeekrFlow provides multiple content moderation models for different content types and contexts: ### Seekr ContentGuard ContentGuard is a purpose-built model for podcast transcript analysis. It evaluates diarized audio chunks for brand safety risk and civility scores. **Classification types:** * GARM brand safety (13 categories) * Civility and hostility scoring **Best for:** Podcast content moderation, brand safety assessment for spoken audio content ### Meta Llama Guard 3 Llama Guard 3 is a general-purpose text moderation model supporting all content types. It classifies text using the MLCommons 22-category taxonomy. **Classification types:** * Safe/unsafe binary classification * MLCommons taxonomy (22 categories) **Best for:** LLM output filtering, agent guardrails, general text moderation ## Use cases Content moderation supports several workflows: **LLM guardrails** – Filter agent outputs and user inputs for safety violations **Brand safety** – Assess content suitability for brand association and advertising **Compliance** – Screen content for regulatory requirements and platform policies **User protection** – Detect harmful content in user-generated text ## Model selection Choose models based on content type and classification needs: | Content type | Recommended model | | -------------------- | ------------------ | | Podcast transcripts | Seekr ContentGuard | | LLM outputs | Meta Llama Guard 3 | | User-generated text | Meta Llama Guard 3 | | Brand safety scoring | Seekr ContentGuard | ## Integration Content moderation models are deployed as endpoints and accessed through the SeekrFlow API. Models accept text input and return classification results with category labels and confidence scores. # Data engine Source: https://docs.seekr.com/flow/components/data-engine Transform raw content into structured, AI-ready datasets for training and retrieval. The data engine transforms raw content into structured, AI-ready data. It manages the complete data lifecycle from file ingestion through preparation for training and retrieval workflows. ## Core capabilities The data engine provides two primary functions: Storage manages raw content through file ingestion and vector database creation, with ingestion insights that surface real-time processing status and diagnostics. Vector databases transform these files into searchable knowledge bases through chunking and embedding, with support for user-defined chunk metadata. AI-ready data generates and transforms datasets, converting raw content into training-ready formats. These jobs produce structured outputs optimized for model fine-tuning and alignment, including standard instruction datasets and context-grounded datasets. ## Data workflow The typical data engine workflow: Upload raw content files to storage. Create vector stores for retrieval applications. Generate AI-ready datasets from selected files. Use outputs for fine-tuning, agent knowledge bases, or evaluations. ## Integration points Data engine outputs integrate across SeekrFlow: * **Fine-tuning** – AI-ready datasets feed model training pipelines * **Agents** – Vector stores power FileSearch tool for knowledge retrieval * **Evaluations** – Structured datasets support model testing and validation # AI-ready data Source: https://docs.seekr.com/flow/components/data-engine/ai-ready-data Generate structured training datasets from raw content for model fine-tuning. AI-ready data generates and transforms datasets, converting raw content into training-ready formats. These jobs produce structured outputs optimized for model fine-tuning and alignment. ## How it works The AI-ready data pipeline transforms uploaded files into structured training datasets: **File selection** – Choose source files from storage to use as training material **Dataset type selection** – Specify the type of dataset to generate based on fine-tuning method **Generation** – The system processes files and creates structured question-and-answer pairs or training examples **Output** – Generated datasets are saved in formats compatible with fine-tuning workflows ## Integration with fine-tuning AI-ready datasets feed directly into fine-tuning workflows: * **Instruction fine-tuning** – Standard instruction datasets train models on task-specific examples * **Context-grounded fine-tuning** – Context-grounded datasets train models to use retrieval effectively * **Dataset quality** – Higher quality source content and generation produces better fine-tuned models The data engine automates the transition from raw files to training-ready datasets, reducing manual dataset preparation effort. ## Datasets for fine-tuning AI-ready data supports multiple dataset formats aligned to fine-tuning methods: ### Instruction fine-tuning Standard instruction datasets consist of traditional question-and-answer pairs aligned to task-specific instructions. Each example demonstrates how the model should respond to particular queries or prompts. **Structure:** * **Input** – The question, prompt, or instruction * **Output** – The expected response or completion **Use cases:** * Teaching domain-specific knowledge * Customizing response style and tone * Training task-specific behaviors These datasets are used with instruction fine-tuning to embed knowledge directly into model parameters. ### Context-grounded fine-tuning Context-grounded datasets consist of question-and-answer pairs that reference source documents. Each example includes the query, relevant context from source files, and the correct response grounded in that context. **Structure:** * **Query** – The question or prompt * **Context** – Relevant excerpts from source documents * **Response** – Answer derived from the provided context **Use cases:** * Training models to use external knowledge bases effectively * Teaching retrieval-aware response generation * Building models that cite sources and stay grounded in provided information These datasets are used with context-grounded fine-tuning to train models for retrieval-augmented generation workflows. ## Generation parameters Dataset generation can be configured with parameters that control output characteristics: * **Number of examples** – How many training pairs to generate from source content * **Diversity settings** – Controls for question variety and coverage across source material * **Quality filters** – Criteria for ensuring generated examples meet minimum standards ## Dataset quality Generated datasets are optimized for training effectiveness: * **Relevance** – Questions and answers are derived from actual source content * **Consistency** – Output format matches fine-tuning requirements * **Coverage** – Examples span the breadth of source material * **Validation** – Generated datasets can be reviewed before use in training ## Dataset management AI-ready datasets are managed alongside other data engine outputs: * **Status tracking** – Monitor generation job progress * **Review** – Inspect generated examples before fine-tuning * **Versioning** – Maintain multiple dataset versions from the same sources * **Export** – Download datasets in standard formats # Storage Source: https://docs.seekr.com/flow/components/data-engine/storage Upload files and create vector databases for training and retrieval workflows. Storage manages raw content through file ingestion and vector database creation. Files are uploaded, processed, and organized for downstream use. Vector databases transform these files into searchable knowledge bases through document chunking and embedding generation. ## File storage File storage manages the upload, processing, and organization of raw content. The system ingests documents in multiple formats, extracts text and structure, and maintains files throughout their lifecycle as source material for downstream workflows. ### How it works The file storage system handles the complete ingestion pipeline: **Upload** – Files are uploaded through the UI, API, or SDK **Processing** – The system extracts text content and document structure **Storage** – Processed files are stored with metadata and status tracking **Access** – Files remain available for vector database creation and dataset generation When files are ingested into a vector database, provenance metadata is captured automatically for every chunk: line numbers, character offsets, heading hierarchy, and source page number. This enables full lineage tracing from a model output back to the exact location in the original uploaded file. ### Supported formats File storage accepts multiple document formats: * PDF * DOCX * JSON * Markdown * TXT The system automatically detects file types and applies appropriate processing for content extraction. ### File metadata Each uploaded file maintains metadata throughout its lifecycle: * **File ID** – Unique identifier for the file * **Filename** – Original file name * **Status** – Processing state (queued, running, completed, failed) * **Size** – File size in bytes * **Upload timestamp** – When the file was added to storage * **Content type** – Specified file type ### File organization Files can be organized and managed through: * **Listing** – Retrieve all files or filter by status and metadata * **Retrieval** – Access individual files by ID * **Deletion** – Remove files no longer needed ### File usage Files maintain tracked relationships to the resources that depend on them. These relationships support dependency awareness and data lineage across the platform: * **Vector databases** – Which vector databases have ingested this file * **Data jobs** – Which data jobs reference this file as source content * **Derived files** – Which files were produced from this file during processing (for example, alignment outputs) Use file usage to understand downstream impact before deleting a file, or to trace how source content flows through the platform. ### Ingestion insights > Available through the API and SDK. Ingestion insights provide real-time visibility into what happens after files are uploaded for processing. Each ingestion job exposes structured metadata that tracks progress and surfaces diagnostics when issues occur. Every ingestion job includes: * **Job state** – The current stage of processing: queued, running, completed, or failed * **Timestamps** – When each state transition occurred * **Per-file tracking** – Individual status records for each file in the job * **Error diagnostics** – When a file fails, a specific error code, plain-language message, and suggested fix are provided Ingestion insights apply to both alignment ingestion and vector database ingestion, with a consistent response structure across both. For implementation details, error codes, and code examples, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). ## Vector databases Vector databases (also called vector stores) store document embeddings for semantic search and retrieval. They transform raw files into searchable knowledge bases by chunking documents and generating embeddings for each segment, allowing agents to find relevant information based on meaning rather than keyword matching. ### How it works The vector database creation process: **File selection** – Choose which files to include in the vector database. **Chunking** – Documents are split into segments based on configurable parameters. **Embedding generation** – Each chunk is converted into a vector representation using specialized embedding models. **Storage** – Embeddings and their associated text are stored for retrieval. **Search** – Queries are embedded and compared against stored vectors to find semantically similar content. ### Chunking strategy Document chunking determines how files are segmented before embedding. Proper chunking ensures that retrieved segments contain complete, coherent information relevant to queries. SeekrFlow supports multiple chunking methods to optimize retrieval for different document types and use cases: **Sliding window chunking** Creates fixed-size segments with configurable token counts and overlap between adjacent chunks. This method provides consistent chunk sizes and ensures context continuity across boundaries. * **Chunk size** – Number of tokens per segment (default: 512) * **Overlap** – Tokens shared between adjacent chunks (default: 50) **Best for:** General-purpose retrieval when documents lack clear structural boundaries. **Markdown chunking** Splits documents at markdown structural elements (headers, sections, lists). This method preserves logical document organization and keeps related content together. **Best for:** Technical documentation, structured reports, and content with clear hierarchical organization. **Semantic chunking** Analyzes content meaning to identify natural topic boundaries and groups semantically related information into chunks. This method creates variable-size segments based on conceptual coherence rather than fixed token counts. **Best for:** Long-form content, narrative documents, and materials where maintaining topical coherence is critical for retrieval quality. ### Embedding models Vector databases use specialized embedding models to convert text into vector representations. These models are trained to encode semantic meaning, allowing similarity comparisons between queries and document chunks. The embedding dimension and model choice affect: * **Retrieval accuracy** – How well the system identifies relevant content * **Storage requirements** – Vector database size based on embedding dimensions * **Search speed** – Query performance relative to database size and embedding complexity ### Semantic search Vector databases power semantic search capabilities: * **Meaning-based retrieval** – Find content based on conceptual similarity rather than exact keyword matches * **Ranked results** – Return chunks ordered by relevance to the query * **Context preservation** – Retrieve coherent segments that maintain document structure * **Multi-document search** – Query across all files attached to the vector store ### User-defined metadata Beyond the provenance metadata captured automatically during ingestion, you can attach your own structured business fields to chunks, such as `year`, `doc_type`, or `department`. Attach metadata when you ingest files, then list and filter chunks by those fields or edit the metadata in place afterward. For metadata rules, filter operators, and code examples, see [Manage chunk metadata](/flow/sdk/data-engine/manage-chunk-metadata). ### Vector store management Vector databases can be managed through: * **Creation** – Build new vector stores from selected files * **File attachment** – Add additional files to existing vector stores * **Status monitoring** – Track processing progress for vector database creation * **Integration** – Connect vector stores to agent FileSearch tools ### Vector database usage Vector databases maintain tracked relationships to the resources that depend on them: * **Tools** – Which FILE\_SEARCH tools are configured to query this vector database * **Data jobs** – Which data jobs reference this vector database Use vector database usage to check whether a vector store is actively in use before deleting it, or to trace which agents are backed by a given knowledge base. ### Use cases Vector databases support several key workflows: **Retrieval-augmented generation (RAG)** Agents use vector databases to find relevant context before generating responses. The FileSearch tool queries vector stores to retrieve document segments that inform the agent's output. **Knowledge base search** Internal documentation, policies, and reference materials become searchable by meaning. Users can ask questions in natural language and receive relevant information from document collections. **Semantic discovery** Find related content across large document sets without knowing exact keywords. Vector databases surface conceptually similar information that traditional search might miss. ## Integration with other components Storage integrates across SeekrFlow: * **Agents** – FileSearch tool queries vector databases for knowledge retrieval * **Fine-tuning** – Files serve as source content for training dataset generation * **Context-grounded fine-tuning** – Vector databases provide retrieval infrastructure for training models to use external knowledge * **Evaluations** – Test agent performance on knowledge retrieval tasks using vector stores # Deployments Source: https://docs.seekr.com/flow/components/deployments Launch, monitor, and manage model endpoints for real-time inference. Deployments create and manage model endpoints for real-time inference. A deployment hosts a model (base or fine-tuned) on dedicated compute infrastructure, making it available for API requests, agent usage, or application integration. Create and manage deployments through the SeekrFlow web interface. Create and manage deployments programmatically with the Python SDK. ## How deployments work Deployments provision model endpoints with specified compute resources. Once active, deployed models serve inference requests through the SeekrFlow API. Deployments can be paused to stop serving traffic or deleted to free resources. ## Deployment configuration When creating a deployment, you configure: * **Model selection** – Choose a base model or fine-tuned model checkpoint * **Compute resources** – Specify instance count and hardware allocation * **Endpoint details** – Define deployment name and description for identification ## Deployment status Each deployment has a status indicating its current state: | Status | Description | | -------- | ------------------------------------------------- | | Pending | Deployment requested, provisioning infrastructure | | Active | Serving inference traffic | | Inactive | Paused, not serving requests | | Failed | Error during startup or runtime | ## Using deployed models Active deployments are accessed through two methods: * **Agent integration** – Reference deployed models in agent configurations to give agents access to specific model capabilities * **API endpoints** – Make direct inference calls via deployment endpoints to integrate models into custom applications or workflows ## Deployment management Deployments support lifecycle operations: * **Pause** – Stop serving traffic while preserving the endpoint * **Resume** – Reactivate an inactive deployment * **Delete** – Remove the deployment and free allocated resources ## Monitoring Track deployment performance through: * Token usage metrics (input and output) * Active hours and uptime * Event timeline showing deployment lifecycle events # Explainability Source: https://docs.seekr.com/flow/components/explainability Understand model outputs by tracing responses to the sources and training data that influenced them. Explainability traces model responses back to their origins—whether retrieved context in an agentic workflow or training examples from fine-tuning. This allows you to see which inputs influenced specific outputs. Context attribution is available in Agent Chat, the API, and the SDK. Training data attribution is available in the API and SDK only. ## Use cases **Debugging** – Identify which inputs drove unexpected or incorrect outputs. This helps locate problematic data sources or training examples. **Auditing** – Document how AI systems reach decisions. Explainability provides traceable links between outputs and source materials for compliance and verification. **Dataset refinement** – Analyze influential inputs to identify gaps or issues in your retrieval sources or training data. ## Attribution capabilities SeekrFlow provides two attribution capabilities for different workflows: Identifies which retrieved sources influenced an agent's response. Traces statements back to vector database content, web search results, tool outputs, and conversation context. **When to use:** Agents with RAG, web search, or tools. Identifies which training examples influenced a fine-tuned model's response. Traces outputs back to specific question-answer pairs from the training dataset. **When to use:** Fine-tuned models. Identifies the exact location in the source document that a retrieved chunk came from. Traces responses back to the specific file, page, and lines the agent retrieved. **When to use:** Agents with RAG where document-level proof of origin is required. ## Choose the right capability | Workflow | Attribution type | What it traces | | ------------------------------------- | ------------------------- | -------------------------------------------------------------- | | Agents with RAG, web search, or tools | context attribution | Retrieved sources that influenced each statement | | Fine-tuned models | training data attribution | Training examples that shaped model behavior | | Agents with RAG | source tracing | Exact location in the source document for each retrieved chunk | If you use a fine-tuned model within an agent that also retrieves context, both capabilities can apply—context attribution for retrieval influence, training data attribution for fine-tuning influence. # Context attribution Source: https://docs.seekr.com/flow/components/explainability/context-attribution Identify which retrieved sources influenced an agent's response. Context attribution identifies which retrieved sources influenced each statement in an agent's response. It traces outputs back to vector database content, web search results, tool outputs, agent instructions, and conversation context. Run source trace on agent responses in Agent Chat. Retrieve attribution results programmatically using the Python SDK or REST API. ## How context attribution works Context attribution identifies which sources shaped an agent's response and to what degree. It works by testing how the response changes when different sources are removed. Sources that cause the biggest changes receive higher influence scores. The process works at statement-level granularity, so each sentence in the response is analyzed independently against the available sources. ## Source types Context attribution can trace influence from multiple source types: | Source type | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | Vector database | Content retrieved from your knowledge bases | | Web search | Results from web search tool calls, including search result snippets and full fetched page content | | Tool outputs | Responses from other tools the agent called | | MCP tool responses | Responses from MCP (Model Context Protocol) tool calls, such as issue trackers or CRMs, and from sub-agents the agent invoked as tools | | Agent instructions | Segments of the agent's system prompt, including instructions, persona definitions, and behavioral constraints | ## Influence scores Each source receives an influence score indicating how strongly it affected a given statement. Higher scores mean the model relied more heavily on that source when generating the statement. Influence is measured by observing how the model's output changes when a source is removed. Sources that cause significant changes when removed receive higher influence scores. ## When to use context attribution Context attribution is useful when you need to: * **Verify grounding** — Confirm that agent responses are based on retrieved sources rather than prior model knowledge * **Debug retrieval** — Identify when irrelevant or incorrect sources are influencing outputs * **Audit responses** — Document which sources contributed to specific statements for compliance requirements * **Improve retrieval quality** — Analyze patterns in influential sources to refine your knowledge base or retrieval configuration ## Relationship to source tracing Context attribution and source tracing are complementary but distinct. Context attribution measures the *degree of influence* each source had on a response. Source tracing identifies the exact file, page, and lines every retrieved chunk came from. For chunk-level lineage, see [Source tracing](/flow/sdk/explainability/source-tracing). ## Limitations Context attribution identifies correlation between sources and outputs, but does not guarantee causal relationships in all cases. Statements with low influence scores across all sources may indicate the model relied on its prior knowledge rather than retrieved context. # Source tracing Source: https://docs.seekr.com/flow/components/explainability/source-tracing Trace retrieved chunks to their exact location in the original source document. Trace retrieved chunks to their source document programmatically. ## How source tracing works When a file is ingested into a vector database, the system records the exact location of every chunk within the source document, including its position within the heading structure and, for page-based formats, its source page. When an agent retrieves a chunk using file search, this location information travels with the result, giving you a direct path from the agent's response back to the original file. ## When to use source tracing * **Auditability** – Verify that agent responses came directly from your uploaded documents * **Compliance** – Produce document-level proof of origin for regulated environments * **Chain of custody** – Follow a response from model output to the exact location in the source file ## Relationship to context attribution Context attribution measures the degree of influence each source had on a response. Source tracing identifies where in the source document a retrieved chunk came from. They are complementary: attribution tells you what shaped the response, source tracing proves exactly where in the document it came from. # Training data attribution Source: https://docs.seekr.com/flow/components/explainability/training-data-attribution Identify which training examples influenced a fine-tuned model's response. Training data attribution surfaces the training data that influenced fine-tuned model outputs. By tracing model responses back to specific question-answer pairs from the training dataset, it helps debug model behavior and audit responses. Retrieve influential fine-tuning examples programmatically using the Python SDK or REST API. ## How training data attribution works When a fine-tuned model generates a response, training data attribution identifies the most influential training examples that shaped that output. Each influential example receives an influence level (high, medium, or low) indicating its contribution to the model's response. ## Requirements Training data attribution is available for: * Fine-tuned models created through SeekrFlow * Models trained after September 22, 2025 * Deployed models with active endpoints ## Influence levels Training examples are ranked by their influence on model outputs: | Level | Description | | ------ | --------------------------------------------------- | | High | Training example strongly shaped the model response | | Medium | Training example had moderate impact on output | | Low | Training example contributed minimally to response | Irrelevant training examples are filtered out and not returned. ## When to use training data attribution **Debugging model behavior** – Identify which training examples drive unexpected or incorrect responses **Auditing outputs** – Trace model decisions back to source training data for compliance and verification **Dataset refinement** – Discover patterns in influential training examples to improve fine-tuning datasets ## Traceability Training data attribution responses include file identifiers linking back to source documents. This connects model outputs to original training materials, supporting debugging and dataset updates. # Fine-tuning Source: https://docs.seekr.com/flow/components/fine-tuning Adapt pre-trained models to specific domains through automated dataset creation and training. Fine-tuning adapts pre-trained models to specific domains or tasks through specialized training. SeekrFlow automates dataset creation, manages training workflows, and deploys fine-tuned models as custom endpoints. Create and manage fine-tuning jobs through the SeekrFlow web interface. Create and manage fine-tuning jobs programmatically with the Python SDK. ## How fine-tuning works The fine-tuning process adjusts model parameters by training on structured question-and-answer pairs. Models learn from examples that demonstrate desired behaviors, domain knowledge, and specific output patterns. The training produces specialized models with deeper expertise while retaining general capabilities from the base model. ## When to use fine-tuning Fine-tuning provides value when: * Working with proprietary or sensitive information not in base model training data. * Requiring specific output formats, styles, or tones. * Optimizing for tasks more easily demonstrated than described. * Improving accuracy on domain-specific terminology or concepts. * Reducing costs by using smaller specialized models. ## Fine-tuning methods SeekrFlow supports multiple fine-tuning approaches: | Method | Description | Best for | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | [Instruction fine-tuning](/flow/components/fine-tuning/instruction-fine-tuning) | Standard approach that trains models on question-and-answer pairs aligned to task-specific instructions. Embeds domain knowledge directly into model parameters. | Embedding proprietary knowledge, customizing behavior and tone, optimizing for demonstrated tasks | | [Context-grounded fine-tuning](/flow/components/fine-tuning/context-grounded-fine-tuning) | **Deprecated (sunset July 17, 2026).** Training approach that teaches models to access and retrieve information from external knowledge bases during inference. Maintains accuracy with frequently changing information. | Dynamic information that requires real-time updates, maintaining current data without retraining | | [Reinforcement tuning (GRPO)](/flow/components/fine-tuning/grpo) | Teaches the model to judge its own outputs using a reward function that scores generated responses against reference answers, rather than directly imitating target responses. | Improving response quality, aligning outputs with brand voice, reducing unwanted behaviors | | [Preference tuning (DPO)](/flow/components/fine-tuning/preference-tuning) | Learns directly from comparisons between preferred and dispreferred responses, without requiring reference answers or reward functions. | Aligning outputs with subjective quality criteria, organizational standards, human feedback | ## Method comparison | | Best for | Knowledge location | Update mechanism | Retrieval required | Training data | Training cost | Iteration speed | Artifact size | | ------------------------ | ------------------------------ | ----------------------- | --------------------- | ------------------ | --------------------------------- | ------------- | --------------- | ------------------ | | **Instruction** | Static domain knowledge | Model parameters | Retrain model | No | QA pairs | High (full) | Slow | Large (full model) | | **Context-grounded** | Dynamic information | External knowledge base | Update knowledge base | Yes | QA pairs + knowledge base | High (full) | Slow | Large (full model) | | **Reinforcement tuning** | Quality alignment (verifiable) | Model parameters | Retrain model | No | Prompts + reference answers | High (full) | Slow | Large (full model) | | **Preference tuning** | Quality alignment (subjective) | Model parameters | Retrain model | No | Preferred/rejected response pairs | High (full) | Slow | Large (full model) | ## Recommended approach Most fine-tuning projects should: * Start with LoRA + instruction fine-tuning as the default approach. * Use reinforcement tuning or preference tuning when quality alignment is needed. * Consider full fine-tuning only after LoRA experiments show it's necessary. These recommendations balance training efficiency with model quality while minimizing upfront investment. ## Low-rank adaptation (LoRA) [Low-rank adaptation (LoRA)](/flow/components/fine-tuning/lora) is a parameter-efficient optimization technique that can be applied to any of the fine-tuning methods above. Rather than updating all model weights during training, LoRA trains small adapter modules, enabling faster training with lower compute costs while preserving base model knowledge. LoRA can be used with instruction fine-tuning, context-grounded fine-tuning, reinforcement tuning, or preference tuning to reduce resource requirements and speed up iteration cycles. ## Vision language tuning [Vision language tuning](/flow/components/fine-tuning/vision-language-tuning) extends fine-tuning to models that process both images and text. The training workflow is the same as text-only fine-tuning — the difference is in the input data and model selection. Currently, SeekrFlow supports instruction fine-tuning of vision-language models with the same SDK primitives as text-only training. ## Dataset preparation Fine-tuning requires structured training datasets with question-and-answer pairs. SeekrFlow's data engine automates the creation of training-ready datasets from raw source files, generating examples that demonstrate desired model behaviors and domain knowledge. Learn more: [AI-ready data](/flow/components/data-engine/ai-ready-data) ## Model deployment Fine-tuned models are deployed as custom model endpoints. Once active, fine-tuned models can be used in agents, inference workflows, or any application requiring specialized model behavior. # Context-grounded fine-tuning Source: https://docs.seekr.com/flow/components/fine-tuning/context-grounded-fine-tuning Train models to access and retrieve information from external knowledge bases during inference. SeekrFlow is deprecating context-grounded fine-tuning (also called retrieval-augmented fine-tuning, or RAFT) and will remove it on July 17, 2026. You can keep using it until then. For new projects, choose another [fine-tuning method](/flow/components/fine-tuning#fine-tuning-methods). Context-grounded fine-tuning trains models to effectively use external knowledge bases during inference. Rather than embedding knowledge into model parameters, this approach teaches models to retrieve, evaluate, and synthesize information from provided context. ## How it works The training process teaches models three key capabilities: 1. **Relevance assessment**: Distinguishing between relevant and irrelevant retrieved documents 2. **Information extraction**: Identifying and extracting pertinent information from relevant context 3. **Grounded synthesis**: Generating responses that accurately reflect the provided context while avoiding hallucination Models learn these skills through training examples that pair queries with retrieved context and correct responses. The training emphasizes staying faithful to provided information rather than relying on parametric knowledge. ## When to use context-grounded fine-tuning Context-grounded fine-tuning provides value when: * Working with dynamic information that requires real-time updates without model retraining * Maintaining current data accuracy across large, frequently changing knowledge bases * Building systems where information sources need regular updates or replacements * Requiring explicit source attribution for generated responses * Combining retrieval-augmented generation (RAG) with specialized retrieval behaviors ## Training requirements Effective context-grounded fine-tuning requires: * **Retrieval integration**: Access to the retrieval system and knowledge base used during training and inference * **Representative context**: Training examples with realistic retrieved context, including both relevant and irrelevant documents * **Grounding emphasis**: Examples that demonstrate proper use of provided context and appropriate responses when context is insufficient * **Consistency**: Alignment between training retrieval patterns and production retrieval behavior ## Comparison with other methods Unlike instruction fine-tuning, context-grounded fine-tuning doesn't embed domain knowledge into parameters. This makes it ideal for dynamic information but requires retrieval infrastructure at inference time. Context-grounded fine-tuning can be combined with LoRA for parameter-efficient training of retrieval behaviors. The adapter learns retrieval-specific patterns while the base model provides general language capabilities. This approach works well with RAG systems by teaching models to better utilize retrieved context. The fine-tuning optimizes how models process and synthesize retrieved information. ## Model deployment Context-grounded models are deployed with retrieval systems that provide relevant context at inference time. The model endpoint receives both the query and retrieved context, generating responses grounded in the provided information. # Reinforcement tuning (GRPO) Source: https://docs.seekr.com/flow/components/fine-tuning/grpo Uses reward functions to reinforce models toward higher-quality responses. Reinforcement tuning trains models to generate higher-quality responses by scoring candidate outputs and reinforcing preferred behaviors. SeekrFlow implements reinforcement tuning using group relative policy optimization (GRPO). For implementation details including dataset format and code examples, see the [Reinforcement tuning SDK guide](/flow/sdk/fine-tuning/grpo-fine-tuning). **UI support** Reinforcement tuning is available in the UI with mathematical accuracy as a reward function. User-defined reward functions are not currently supported in the UI but are available through the API and SDK. ## How it works Reinforcement tuning operates through a reinforcement learning process: **Generation**: The model generates multiple candidate responses to each prompt. **Evaluation**: A reward function scores each candidate based on quality criteria. **Optimization**: Training gradients push the model toward generating higher-scoring responses. Reward functions use one or more [graders](#available-graders) to score outputs on specific qualities like numerical accuracy, keyword matching, text similarity, or LLM-judged quality. The model learns to maximize expected reward across diverse prompts. ## When to use reinforcement tuning Reinforcement tuning provides value when: * Improving overall response quality beyond what demonstration data captures * Aligning model outputs with subjective preferences or style guidelines * Reducing unwanted behaviors (verbosity, hedging, unsafe content) * Optimizing for measurable quality metrics (accuracy, user satisfaction) * Teaching models to balance multiple competing objectives ## Training requirements Effective reinforcement tuning requires: * **Reward function**: Clear criteria for evaluating response quality through one or more graders * **Diverse prompts**: Training examples covering the range of scenarios where quality preferences apply * **Reference answers**: Answers against which the model can score its generated outputs * **Base model capability**: Strong starting model that can generate reasonable candidates before preference optimization Download a sample dataset to see the expected format, or review the [Reinforcement tuning SDK guide](/flow/sdk/fine-tuning/grpo-fine-tuning) for the full schema. ## Reward functions A reward function scores model outputs during training to reinforce desired behaviors. In SeekrFlow, reward functions are built from one or more **graders** — individual scoring operations that each evaluate a specific quality of the output. ### Available graders | Grader | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Numerical accuracy** | Evaluates whether the model output is numerically correct. Useful for financial auditing, math, and other tasks with definite numerical answers. | | **String check** | Evaluates whether the model output contains or matches a specific phrase. Useful for enforcing keyword usage or required terminology. | | **Text similarity** | Evaluates how lexically similar the model output is to the reference answer. Useful for enforcing tone, style, or compliant language. | | **LLM (LLM-as-a-judge)** | Uses an LLM to score how well the output matches the reference answer in meaning and quality. Useful for open-ended or subjective responses where exact or lexical matching is too rigid. | ### Combining graders You can combine multiple graders into a single reward function by assigning weight percentages to each. This creates a hybrid reward signal tailored to your use case. For example, you might weight numerical accuracy at 80% and text similarity at 20% to reward both the mathematical correctness and formatting of the model's answers. For implementation details and code examples, see the [Reinforcement tuning SDK guide](/flow/sdk/fine-tuning/grpo-fine-tuning). ## Comparison with other methods Reinforcement tuning learns quality patterns through reinforcement of high-scoring outputs. Unlike instruction fine-tuning, it doesn't require explicit demonstrations of correct responses. Reinforcement tuning typically follows instruction fine-tuning in training pipelines — the instruction phase teaches domain knowledge, while reinforcement tuning refines response quality and alignment. Reinforcement tuning can be combined with LoRA for efficient training. The adapter learns preference patterns while the base model provides general capabilities, reducing compute requirements without sacrificing quality improvements. ## Model deployment Reinforcement-tuned models are deployed as standard model endpoints. The reinforced model behaviors are embedded in model parameters, so no special inference infrastructure is required. The model generates responses that reflect the learned quality preferences. # Instruction fine-tuning Source: https://docs.seekr.com/flow/components/fine-tuning/instruction-fine-tuning Train models on question-and-answer pairs to embed domain knowledge directly into model parameters. Instruction fine-tuning trains models on question-and-answer pairs that demonstrate desired behaviors and domain knowledge. The training embeds specialized knowledge directly into model parameters, producing models with deeper expertise in specific domains while retaining general capabilities. ## How it works The process trains models on datasets of input-output pairs aligned to task-specific instructions. Each training example shows the model how to respond to particular types of queries. Through repeated exposure to these examples, the model learns patterns, terminology, reasoning approaches, and response styles specific to the target domain. The trained model internalizes this knowledge into its parameters. At inference time, the model generates responses based on this embedded knowledge without requiring external data sources or retrieval systems. ## When to use instruction fine-tuning Instruction fine-tuning provides value when: * Embedding proprietary or confidential knowledge not available in base model training data * Customizing model behavior, tone, or communication style to match organizational standards * Teaching domain-specific terminology, concepts, or reasoning patterns * Optimizing performance on tasks more easily demonstrated through examples than described through prompts * Creating specialized models that consistently apply learned knowledge without retrieval overhead ## Training requirements Effective instruction fine-tuning requires: * **Dataset quality**: High-quality question-and-answer pairs that accurately represent desired behaviors. Consistency matters more than volume. * **Coverage**: Training examples that span the range of queries and scenarios the model will encounter in production. * **Clarity**: Examples with clear, unambiguous demonstrations of correct responses. * **Representative distribution**: Training data that reflects the actual distribution of use cases. ## Comparison with other methods Instruction fine-tuning embeds knowledge directly into model parameters rather than teaching retrieval behaviors. Unlike context-grounded fine-tuning, this makes it ideal for static knowledge but less suitable for frequently changing information. Instruction fine-tuning works by training models to replicate demonstrated answers. Reinforcement tuning (GRPO) takes a different approach, teaching models to evaluate output quality through reward functions. Preference tuning (DPO) learns from comparative judgments between responses without requiring reference answers. Use instruction fine-tuning when you can provide direct examples of desired outputs. Instruction fine-tuning can be combined with LoRA for more efficient training. Full parameter fine-tuning provides maximum flexibility but requires more compute and produces larger artifacts. LoRA enables faster, more cost-effective training by updating only small adapter modules. ## Model deployment Fine-tuned models are deployed as custom model endpoints. Once active, they can be used in agents, inference workflows, or any application requiring the specialized knowledge or behavior. # Low-rank adaptation (LoRA) Source: https://docs.seekr.com/flow/components/fine-tuning/lora Parameter-efficient fine-tuning method that trains small adapter modules instead of all model weights. Low-rank adaptation (LoRA) is a parameter-efficient fine-tuning method that trains small adapter modules rather than updating all model weights. This approach enables faster training with significantly lower compute costs while preserving base model knowledge. ## How it works LoRA inserts small trainable adapter matrices into model layers while keeping the base model weights frozen. During training, only these adapter parameters are updated. The adapters learn task-specific patterns as low-rank decompositions of weight updates. At inference time, the adapter combines with the base model to compute predictions. Multiple LoRA adapters can be trained from the same base model and swapped dynamically based on the task. The method is controlled by two key parameters: * **Rank**: Determines adapter capacity and the complexity of patterns it can learn. Higher rank supports more complex adaptations but increases training cost. * **Alpha**: Controls how strongly learned patterns influence base model behavior. Higher alpha makes the adapter's influence more pronounced. ## When to use LoRA LoRA provides value when: * Adding new behaviors to a model while preserving underlying knowledge * Requiring faster training and iteration cycles than full fine-tuning * Operating under compute or cost constraints that prohibit full fine-tuning * Maintaining multiple specialized adapters from a single base model * Experimenting with different adaptations before committing to full fine-tuning * Needing smaller model artifacts for easier storage and deployment ## Training characteristics LoRA offers distinct training advantages: * **Speed**: Trains significantly faster than full fine-tuning by updating fewer parameters * **Memory efficiency**: Enables larger batch sizes on the same hardware by keeping base model frozen * **Artifact size**: Produces small adapter files (typically megabytes) rather than full model weights (gigabytes) * **Flexibility**: Supports creating multiple adapters from one base model for different tasks The method works best with consistent, high-quality datasets. LoRA adapters can be more sensitive to noisy or contradictory training data than full fine-tuning. ## Configuration guidance Choosing rank and alpha depends on the task: **For simple adaptations** (style, formatting, tone): * Start with rank 8–16, alpha 16–32 * Lower ranks often sufficient for surface-level changes **For domain adaptation** (specialized terminology, structured outputs): * Start with rank 16–32, alpha 32–64 * Medium ranks handle domain-specific patterns **For complex multi-constraint tasks** (correctness, format, policy, reasoning): * Start with rank 32–64, alpha 64–128 * Higher ranks support multiple simultaneous requirements Most tasks work well with rank 16 and alpha 32 as starting defaults. Adjust based on whether the model learns the desired behavior too weakly (increase alpha) or too rigidly (decrease alpha or rank). ## Comparison with other methods Unlike full instruction fine-tuning, LoRA updates only adapter parameters rather than all weights. This provides faster training and smaller artifacts but may have less capacity for deep knowledge rewrites. LoRA can combine with any fine-tuning method (instruction, context-grounded, reinforcement tuning, preference tuning). The choice of method determines what the model learns; LoRA determines how efficiently those parameters are updated. For most use cases, LoRA offers the best balance of training speed, cost, and model quality. Consider full fine-tuning only when LoRA cannot achieve the desired behavior after parameter tuning. ## Model deployment LoRA models are deployed as base model plus adapter. The deployment system loads the frozen base model and applies the appropriate adapter for each request. This architecture enables efficient serving of multiple specialized models from a shared base. # Preference tuning (DPO) Source: https://docs.seekr.com/flow/components/fine-tuning/preference-tuning Align model outputs with human preferences by learning directly from response comparisons. Preference tuning aligns model behavior by learning from comparisons between responses rather than from explicit correct answers. SeekrFlow implements preference tuning using direct preference optimization (DPO), which trains models to increase the likelihood of generating preferred responses over dispreferred ones. For implementation details including dataset schema and code examples, see the [Preference tuning SDK guide](/flow/sdk/fine-tuning/preference-tuning). ## How it works Preference tuning operates on paired response data. Each training example contains a prompt, a preferred (chosen) response, and a dispreferred (rejected) response. The model learns to distinguish what makes one response better than another and adjusts its generation patterns accordingly. DPO optimizes directly against preference pairs without requiring a separate reward model. This makes it simpler and more stable than traditional RLHF approaches while achieving comparable alignment quality. A key parameter, **beta**, controls the strength of the KL-divergence penalty — how far the tuned model is allowed to deviate from the original base model. Lower beta values allow more deviation, while higher values keep the model closer to its original behavior. ## When to use preference tuning Preference tuning provides value when: * Aligning model outputs with organizational standards such as tone, compliance requirements, or customer experience guidelines * Improving response quality in scenarios where preferences are clear but a single "correct" answer does not exist * Leveraging existing human feedback or editorial judgment as training signal * Refining model behavior without needing explicit reference answers or reward functions ## How it differs from other methods Preference tuning fills a distinct role in the fine-tuning workflow: * **Instruction fine-tuning** teaches models to replicate demonstrated responses. It requires explicit examples of correct outputs. * **Reinforcement tuning (GRPO)** optimizes against a reward function that scores generated responses against reference answers. It requires definite, verifiable answers. * **Preference tuning (DPO)** learns from comparative judgments — which response is better — without requiring gold answers or reward functions. This makes it effective for subjective quality criteria that are difficult to express as rules or metrics. ## Training requirements Effective preference tuning requires: * **Preference dataset**: Paired examples with a prompt, a chosen response, and a rejected response. SeekrFlow's data engine does not currently generate preference datasets, so datasets must be prepared externally. * **Consistent preference signal**: Clear, consistent criteria for what makes one response preferred over another. Noisy or contradictory preferences reduce training effectiveness. * **Base model capability**: A model that already generates reasonable responses. Preference tuning refines quality rather than teaching foundational knowledge. ## Dataset format Each training example contains three components: * **Prompt**: System and user messages that define the context. * **Chosen**: The preferred assistant response. * **Rejected**: The dispreferred assistant response. Datasets must be in JSONL or Parquet format and uploaded with the `preference-fine-tune` file purpose. SeekrFlow validates the schema on upload and rejects datasets that do not conform to the expected structure. ## Model compatibility Preference tuning works with all base models available in SeekrFlow. No model-specific restrictions apply beyond the standard fine-tuning requirements. ## Model deployment Preference-tuned models are deployed as standard model endpoints. The learned preferences are embedded in model parameters, so no special inference infrastructure is required. # Vision language tuning Source: https://docs.seekr.com/flow/components/fine-tuning/vision-language-tuning Fine-tune vision-language models that reason across both images and text. Vision language tuning fine-tunes models that process both images and text. These vision-language models (VLMs) reason across visual and textual inputs, enabling use cases such as image understanding, visual question answering, and multimodal assistants. For implementation details including dataset schema and code examples, see the [Vision language tuning SDK guide](/flow/sdk/fine-tuning/vision-language-tuning). ## How it differs from text-only fine-tuning Vision language tuning applies fine-tuning to models that process both images and text. The training workflow is the same as text-only fine-tuning — the difference is in the input data and model selection. Currently, SeekrFlow supports instruction fine-tuning of vision-language models using the same SDK primitives as text-only training. The key differences: * Training data must include image inputs alongside text. * The base model must be a vision-language model. * SeekrFlow enforces compatibility between dataset type and model type. Mismatched pairings (a vision dataset with a text-only model, or a text-only dataset with a VLM) are rejected at job creation. ## Supported models SeekrFlow supports fine-tuning the following vision-language models: * `meta-llama/Llama-3.2-11B-Vision-Instruct` * `Qwen/Qwen2.5-VL-7B-Instruct` ## When to use vision language tuning Vision language tuning provides value when: * Building systems that need to interpret images alongside text queries. * Training models to identify, classify, or describe visual content with domain-specific accuracy. * Creating multimodal assistants that answer questions grounded in image data. * Adapting general-purpose VLMs to recognize domain-specific visual patterns, products, or artifacts. ## Training and infrastructure Vision language fine-tuning supports the same infrastructure configurations as text-only fine-tuning, including multi-node setups. Training configuration parameters (epochs, batch size, learning rate, checkpoints) behave identically. Compute requirements are generally higher than text-only fine-tuning due to the additional processing of image inputs. # Observability Source: https://docs.seekr.com/flow/components/observability Monitor agent performance and investigate runs with span-level visibility. Observability gives you visibility into how your agents are performing by capturing a record of every run. Each record includes when the run happened, which model was used, how many tokens were consumed, and whether any errors occurred. ## What you can see Each agent run generates spans that capture: * **Timing** – When a run started and ended * **Model usage** – Which model handled the request * **Token consumption** – Input and output token counts * **Errors** – Whether an exception occurred and what type it was ## When to use **Monitor agent health** – Track whether runs are completing successfully and identify patterns in failures. **Investigate a failed run** – Retrieve spans for a specific run to see where it went wrong. **Understand usage and costs** – Review token consumption across runs to inform capacity planning and cost management. For implementation details, see [Observability SDK guide](/flow/sdk/observability). # Connect to MCP Server Source: https://docs.seekr.com/flow/mcp Connect your AI assistant to the SeekrFlow OpenAPI spec to generate working, authenticated code on demand. The SeekrFlow MCP server implements the Model Context Protocol (MCP) to give your AI assistant direct access to the SeekrFlow OpenAPI spec. When connected, your assistant can read endpoint definitions, parameters, request and response schemas, and authentication requirements — then use that information to generate working, authenticated code without you having to look anything up manually. For example, ask *"How do I upload a file to the AI-Ready Data Engine?"* and your assistant will: Retrieve the SeekrFlow OpenAPI spec. Locate the correct `/flow/files` endpoint definition. Read the required parameters, request body schema, and authentication requirements. Generate working code with proper authentication and request structure. Include response handling based on the defined response schemas. **Supported tools:** * VSCode * Cursor * Windsurf * Other AI assistants that support remote MCP servers ## Authentication No authentication is required to connect to the SeekrFlow MCP server. When your AI assistant generates code that makes SeekrFlow API calls, those calls require your SeekrFlow API key in the `Authorization` header. Set your API key as an environment variable so it's available in generated code: ```bash Linux / macOS theme={null} export SEEKR_API_KEY=your_api_key ``` ```bash Windows theme={null} set SEEKR_API_KEY=your_api_key ``` For instructions on getting your API key, see [Getting started with your API](/flow/reference/getting-started-with-your-api#get-your-api-key). ## Connect your tools SeekrFlow hosts a remote MCP server at `https://docs.seekr.com/mcp`. Configure your AI development tools to connect to this server using the steps below. ### VSCode Open the Command Palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Windows/Linux). Select **MCP: Add Server...**. Select **HTTP (HTTP or Server-Sent Events)**. Enter `https://docs.seekr.com/mcp` for the server URL. Enter `seekr-api` (or any unique identifier) for the server name. Or add the following to your VSCode MCP configuration: ```json JSON theme={null} { "mcpServers": { "seekr-api": { "type": "http", "url": "https://docs.seekr.com/mcp" } } } ``` ### Cursor Open `~/.cursor/mcp.json`. If the file doesn't exist, create it with `touch ~/.cursor/mcp.json`. Add the following configuration: ```json JSON theme={null} { "mcpServers": { "seekr-api": { "type": "http", "url": "https://docs.seekr.com/mcp" } } } ``` Restart Cursor to load the MCP connection. ### Windsurf Open `~/.codeium/windsurf/mcp_config.json`. If the file doesn't exist, create it with `touch ~/.codeium/windsurf/mcp_config.json`. Add the following configuration: ```json JSON theme={null} { "mcpServers": { "seekr-api": { "type": "http", "url": "https://docs.seekr.com/mcp" } } } ``` Restart Windsurf to load the MCP connection. ### Other AI assistants Any AI assistant that supports remote MCP servers can connect to SeekrFlow using `https://docs.seekr.com/mcp`. Refer to your tool's documentation for instructions on adding a remote MCP server. ## Troubleshooting ### Connection issues * **Restart your editor**: MCP connections sometimes need a restart after configuration changes. * **Verify the server URL**: Confirm you are using `https://docs.seekr.com/mcp`. ### File issues * **Cursor**: Make sure `~/.cursor/mcp.json` exists and is valid JSON * **Windsurf**: Check `~/.codeium/windsurf/mcp_config.json` exists and contains valid JSON. * **JSON syntax**: Verify all quotes and brackets are correct ### Get help * **Test your API key** by making a direct SeekrFlow API call to confirm it is active. * Contact SeekrFlow support or see [Getting started](/flow/reference/getting-started-with-your-api) to verify your account setup. # Build something with SeekrFlow Source: https://docs.seekr.com/flow/recipes End-to-end, copy-pasteable walkthroughs. Pick one by what you want to build.

Retrieval and Q\&A

Upload a document, index it in a vector store, and give an agent a FileSearch tool to answer from it. Index your documents and answer questions with confidence ratings and cited sources. Answer questions about a topic and score how much to trust each reply.

Tools and function calling

Give an agent a tool that runs your Python function and calls an external API.

Multi-agent

Wrap a limerick writer and a haiku writer as tools and let a supervisor agent judge the results. # New hire onboarding agent with citations Source: https://docs.seekr.com/flow/recipes/new-hire-onboarding-agent-with-citations Build a FileSearch agent that answers onboarding questions from your own documents, with confidence ratings and cited sources. This recipe builds a document question-answering agent with SeekrFlow's Agent framework and the FileSearch tool. You index a set of documents into a vector database, attach that database to an agent through a FileSearch tool, and prompt the agent to answer only from what it retrieves, rate its confidence, and cite its sources. The example uses a new hire onboarding scenario, but the pattern works for any document set. Gather 3 to 5 high-quality documents relevant to your use case before you start. ## What you'll build An agent that: 1. Indexes your documents into a vector database. 2. Searches across those documents to answer questions. 3. Rates its confidence and explains the rating. 4. Cites the specific sources behind each answer. ## Prerequisites * A SeekrFlow API key, set as the `SEEKR_API_KEY` environment variable * Documents in PDF, DOCX, or Markdown format * Python 3.8 or later * The SeekrFlow SDK: `pip install seekrai` This recipe creates billable resources. When you are done, remove them with the [cleanup step](#clean-up). ## Build it Create `onboarding_agent.py` and start with the imports, configuration, and client. The paths in `FILE_PATHS` should point at your own documents. ```python onboarding_agent.py theme={null} import os import re import time from seekrai import SeekrFlow from seekrai.types import CreateAgentRequest, FileSearch, FileSearchEnv API_KEY = os.environ["SEEKR_API_KEY"] API_URL = "https://flow.seekr.com/v1/" MODEL_ID = "meta-llama/Llama-3.1-8B-Instruct" EMBEDDING_MODEL = "intfloat/e5-mistral-7b-instruct" FILE_PATHS = [ "company-guidebook.pdf", "company-holidays.pdf", "company-payroll-schedule.pdf", ] client = SeekrFlow(api_key=API_KEY, base_url=API_URL) ``` Create an empty vector database. Documents you ingest are embedded with the model you name here and stored for retrieval. ```python onboarding_agent.py theme={null} vector_db = client.vector_database.create( name="BennyBotDB", model=EMBEDDING_MODEL, description="Employee guidelines and benefits for onboarding QA.", ) database_id = vector_db.id print(f"Created vector database: {vector_db.name} ({database_id})") ``` Upload each document to SeekrFlow's AI-Ready Data Engine with `purpose="alignment"` and collect the file IDs. ```python onboarding_agent.py theme={null} file_ids = [] for file_path in FILE_PATHS: print(f"Uploading {file_path}...") upload_response = client.files.upload(file_path, purpose="alignment") file_ids.append(upload_response.id) print(f" Uploaded: {upload_response.id}") ``` Start an ingestion job to chunk, embed, and store the uploaded files, then poll until it completes. Accuracy-optimized ingestion can take a few minutes. ```python onboarding_agent.py theme={null} ingestion_job = client.vector_database.create_ingestion_job( database_id=database_id, files=file_ids, method="accuracy-optimized", chunking_method="markdown", token_count=512, overlap_tokens=50, ) job_id = ingestion_job.id print(f"Created ingestion job: {job_id}") deadline = time.time() + 600 while time.time() < deadline: job = client.vector_database.retrieve_ingestion_job(database_id, job_id) print(f"Ingestion status: {job.status}") if job.status == "completed": print("Vector database ready.") break if job.status == "failed": raise RuntimeError(f"Ingestion failed: {job.error_message}") time.sleep(5) else: raise TimeoutError("Ingestion did not complete in time.") ``` Create an agent and attach a FileSearch tool pointed at your vector database. The instructions tell it to answer only from search results, rate its confidence, and cite sources. Then poll until the agent is `Active`. ```python onboarding_agent.py theme={null} instructions = """You are an expert onboarding assistant that answers only from document search results. For each question: 1. Search the documents with the file_search tool. 2. Use information from multiple sources when available. 3. When you find relevant information, rate your confidence from 1 (guess) to 10 (certain). 4. After your answer, on a new line starting with "Confidence: [X/10]", briefly explain the rating. 5. Cite your sources, including specific document names. If the answer is not in the search results, say you could not find it and do not give a confidence score.""" agent = client.agents.create( CreateAgentRequest( name="BennyBot", instructions=instructions, model_id=MODEL_ID, tools=[ FileSearch( tool_env=FileSearchEnv( file_search_index=database_id, document_tool_desc="Search onboarding documents to answer employee questions accurately.", top_k=6, score_threshold=0.5, ) ) ], ) ) agent_id = agent.id print(f"Agent created: {agent_id}") deadline = time.time() + 300 while time.time() < deadline: status = client.agents.retrieve(agent_id=agent_id).status.value print(f"Agent status: {status}") if status == "Active": print("Agent is active.") break if status == "Failed": raise RuntimeError("Agent failed to deploy.") time.sleep(10) else: raise TimeoutError("Agent did not become active in time.") ``` Create a thread, send a question, wait for the run to finish, and read the agent's reply. The `parse_response` helper splits the answer, the confidence rating, and any cited sources out of the reply. ```python onboarding_agent.py theme={null} def parse_response(response: str) -> dict: """Split an agent reply into answer, confidence, explanation, and sources.""" if not response: return {"answer": "No response received.", "confidence": "0/10", "explanation": "", "sources": []} answer, confidence, explanation, sources = response, "Not provided", "", [] if "Confidence:" in response: answer, _, confidence_part = response.partition("Confidence:") answer = answer.strip() confidence_part = confidence_part.strip() rating_match = re.search(r"(\d+)(/10)?", confidence_part) if rating_match: confidence = f"{rating_match.group(1)}/10" explanation = re.sub(r"^\d+(/10)?", "", confidence_part).strip() for pattern in (r"Source[s]?:(.+?)(?=\n\n|\Z)", r"According to (.+?)(?=\n\n|\Z)"): match = re.search(pattern, response, re.IGNORECASE | re.DOTALL) if match: sources += [s.strip() for s in re.split(r",|\n", match.group(1)) if s.strip()] return {"answer": answer, "confidence": confidence, "explanation": explanation, "sources": sources} thread = client.agents.threads.create() client.agents.threads.create_message( thread_id=thread.id, role="user", content="How many paid holidays do employees get?" ) run_response = client.agents.runs.run(agent_id=agent_id, thread_id=thread.id, stream=False) deadline = time.time() + 300 while time.time() < deadline: run = client.agents.runs.retrieve(run_response.run_id, thread.id) if run.status.value == "completed": break if run.status.value in ("failed", "canceled"): raise RuntimeError(f"Run ended with status: {run.status.value}") time.sleep(2) else: raise TimeoutError("Run did not complete in time.") messages = client.agents.threads.list_messages(thread.id, limit=10, order="desc") reply = next((m.content for m in messages if m.role == "assistant"), None) result = parse_response(reply if isinstance(reply, str) else str(reply)) print("\n" + "=" * 50) print(f"Answer: {result['answer']}\n") print(f"Confidence: {result['confidence']}") if result["explanation"]: print(f"Explanation: {result['explanation']}") if result["sources"]: print("\nSources:") for i, source in enumerate(result["sources"], 1): print(f"{i}. {source}") ``` Run the finished script: ```bash theme={null} python onboarding_agent.py ``` The agent searches your documents, answers from what it retrieves, and appends a confidence rating and its sources.

Clean up resources (optional)

Remove the resources this recipe created when you are done. ```python onboarding_agent.py theme={null} client.agents.demote(agent_id) client.agents.delete(agent_id) client.vector_database.delete(database_id) for file_id in file_ids: client.files.delete(file_id) print("Deleted the agent, vector database, and files.") ``` ## Next steps * **Tune retrieval.** Adjust `top_k` and `score_threshold` on the FileSearch tool to trade recall against precision for your document set. * **Swap in your own documents.** Point `FILE_PATHS` at any PDF, DOCX, or Markdown files to build an assistant for a different domain. * **Add metadata.** Attach metadata at ingestion so you can filter retrieval by fields like document type or date. # Poetry contest with a supervisor agent Source: https://docs.seekr.com/flow/recipes/poetry-contest-with-supervisor-agent Build a supervisor agent that wraps a limerick writer and a haiku writer as tools, sends a prompt to both, and picks a winner. SeekrFlow lets you expose one agent to another as a tool. This recipe uses that pattern to build a small multi-agent system: a supervisor agent coordinates two specialist sub-agents, a limerick writer and a haiku writer. The supervisor sends the user's prompt to each sub-agent, collects both poems, and declares a winner. The pattern is the useful part. Once a sub-agent is a tool, the supervisor decides when to call it the same way it would call any other tool, so you can compose focused agents into a larger workflow instead of building one agent that tries to do everything. ## What you'll build A supervisor agent that: 1. Wraps a Limerick Agent and a Haiku Agent as `agent_as_tool` tools. 2. Sends the user's prompt to both sub-agents. 3. Presents both poems, clearly labeled. 4. Picks a favorite and explains why. ## Prerequisites * A SeekrFlow API key, set as the `SEEKR_API_KEY` environment variable * Python 3.8 or later * The SeekrFlow SDK: `pip install seekrai` This recipe creates billable resources. When you are done, remove them with the [cleanup step](#clean-up). ## Build it Create `agents_as_tools.py` and start with the imports, configuration, and client. ```python agents_as_tools.py theme={null} import os import time from seekrai import SeekrFlow from seekrai.types.tools import CreateAgentAsTool, AgentAsToolConfig from seekrai.types.agents.agent import CreateAgentRequest API_KEY = os.environ["SEEKR_API_KEY"] API_URL = "https://flow.seekr.com/v1/" MODEL_ID = "meta-llama/Llama-3.1-70B-Instruct" TEST_PROMPT = "My cat refuses to get off my keyboard while I'm trying to work." client = SeekrFlow(api_key=API_KEY, base_url=API_URL) ``` This recipe uses `meta-llama/Llama-3.1-70B-Instruct`. The supervisor has to call both sub-agent tools and then reason over their output, so a capable instruct model with reliable tool calling matters more here than in a single-tool agent. Any instruct model that supports tool calling works, such as `meta-llama/Llama-3.3-70B-Instruct`. These helpers wait for asynchronous operations and make the script safe to run more than once. `run_agent` polls a run to completion, `promote_and_wait` polls an agent until it is `Active`, and the `get_or_create` helpers reuse existing resources instead of creating duplicates. ```python agents_as_tools.py theme={null} def run_agent(agent_id: str, prompt: str, timeout: int = 300) -> str: """Start a run, poll until complete, then return the assistant's reply.""" thread = client.agents.threads.create() client.agents.threads.create_message(thread_id=thread.id, role="user", content=prompt) run_response = client.agents.runs.run(agent_id=agent_id, thread_id=thread.id, stream=False) deadline = time.time() + timeout while time.time() < deadline: run = client.agents.runs.retrieve(run_response.run_id, thread.id) if run.status.value == "completed": break if run.status.value in ("failed", "canceled"): raise RuntimeError(f"Run ended with status: {run.status.value}") time.sleep(3) else: raise TimeoutError(f"Run did not complete within {timeout}s.") messages = client.agents.threads.list_messages(thread.id, limit=10, order="desc") for msg in messages: if msg.role == "assistant": return msg.content if isinstance(msg.content, str) else str(msg.content) return "(no assistant message found)" def promote_and_wait(agent_id: str, timeout: int = 120) -> None: """Promote an agent and poll until it's Active.""" client.agents.promote(agent_id) deadline = time.time() + timeout while time.time() < deadline: agent = client.agents.retrieve(agent_id) if agent.status.value == "Active": return if agent.status.value == "Failed": raise RuntimeError(f"Agent {agent_id} failed to deploy.") time.sleep(3) raise TimeoutError(f"Agent did not become Active within {timeout}s.") def get_or_create_agent(request: CreateAgentRequest): """Return an existing agent with the same name, or create a new one.""" existing = next((a for a in client.agents.list_agents() if a.name == request.name), None) if existing: print(f" Found existing '{existing.name}': {existing.id!r}") return existing agent = client.agents.create(request) print(f" Created '{agent.name}': {agent.id!r}") return agent def get_or_create_tool(request: CreateAgentAsTool): """Return an existing agent_as_tool with the same name, or create a new one.""" existing = next((t for t in client.tools.list().data if t.name == request.name), None) if existing: print(f" Found existing tool '{existing.name}': {existing.id!r}") return existing tool = client.tools.create(request) print(f" Created tool '{tool.name}': {tool.id!r}") return tool def ensure_active(agent) -> None: """Promote the agent only if it isn't already Active.""" if agent.status.value == "Active": print(f" '{agent.name}' is already Active.") return print(f" Promoting '{agent.name}'...") promote_and_wait(agent.id) print(f" '{agent.name}' is Active.") ``` Create the two specialist agents. Each has narrow instructions that keep it focused on a single job. ```python agents_as_tools.py theme={null} limerick_agent = get_or_create_agent(CreateAgentRequest( name="Limerick Agent", instructions=( "You are the Limerick Agent. Whatever prompt the user sends you, " "respond ONLY with a creative limerick about it. " "Do not add any other commentary." ), model_id=MODEL_ID, )) haiku_agent = get_or_create_agent(CreateAgentRequest( name="Haiku Agent", instructions=( "You are the Haiku Agent. Whatever prompt the user sends you, " "respond ONLY with a haiku (5-7-5 syllables) about it. " "Do not add any other commentary." ), model_id=MODEL_ID, )) ``` A sub-agent must be `Active` before it can be wrapped as a tool, so promote both now. ```python agents_as_tools.py theme={null} ensure_active(limerick_agent) ensure_active(haiku_agent) ``` Create an `agent_as_tool` tool for each sub-agent. The `description` is what the supervisor sees when it decides which tool to call, and the `config` points at the sub-agent by ID. ```python agents_as_tools.py theme={null} limerick_tool = get_or_create_tool(CreateAgentAsTool( name="limerick_agent", description="Sends a prompt to the Limerick Agent and returns a limerick.", config=AgentAsToolConfig(agent_id=limerick_agent.id), )) haiku_tool = get_or_create_tool(CreateAgentAsTool( name="haiku_agent", description="Sends a prompt to the Haiku Agent and returns a haiku.", config=AgentAsToolConfig(agent_id=haiku_agent.id), )) ``` Create the supervisor agent and attach both tools. Its instructions tell it to call each tool and then compare the results. ```python agents_as_tools.py theme={null} supervisor = get_or_create_agent(CreateAgentRequest( name="Supervisor Agent", instructions=( "You are a supervisor. When the user gives you a prompt:\n" "1. Send it verbatim to the 'limerick_agent' tool and note its output.\n" "2. Send it verbatim to the 'haiku_agent' tool and note its output.\n" "3. Present BOTH outputs to the user, clearly labelled.\n" "4. Declare which one you personally like more, and briefly explain why." ), tool_ids=[limerick_tool.id, haiku_tool.id], model_id=MODEL_ID, )) ensure_active(supervisor) ``` Send a prompt to the supervisor and print its reply. The supervisor calls both sub-agents, then returns both poems with its verdict. ```python agents_as_tools.py theme={null} response = run_agent(supervisor.id, TEST_PROMPT) print("Supervisor says:\n") print(response) ``` Run the finished script: ```bash theme={null} python agents_as_tools.py ``` You should see a limerick and a haiku about the prompt, followed by the supervisor's pick.

Clean up resources (optional)

Promoted agents and their tools stay in your account until you remove them. When you are done, add this helper and call it to tear down everything the recipe created. ```python agents_as_tools.py theme={null} def cleanup(*agent_ids, tool_ids=()): for agent_id in agent_ids: try: client.agents.demote(agent_id) client.agents.delete(agent_id) print(f" Deleted agent {agent_id!r}") except Exception as e: print(f" Warning: could not delete agent {agent_id!r}: {e}") for tool_id in tool_ids: try: client.tools.delete(tool_id) print(f" Deleted tool {tool_id!r}") except Exception as e: print(f" Warning: could not delete tool {tool_id!r}: {e}") cleanup( supervisor.id, limerick_agent.id, haiku_agent.id, tool_ids=(limerick_tool.id, haiku_tool.id), ) ``` ## Next steps * **Add more specialists.** Wrap additional sub-agents (a sonnet writer, a translator) as tools and attach them to the supervisor. * **Route instead of fan out.** Change the supervisor's instructions so it picks the single best sub-agent for a prompt rather than calling all of them. * **Nest deeper.** A sub-agent can have tools of its own, including other agents, so you can build multi-level workflows. # Question-answering bot with confidence scoring Source: https://docs.seekr.com/flow/recipes/simple-question-answering-bot-with-confidence-scoring Build a Q&A bot with SeekrFlow that returns a confidence score alongside each answer. This recipe builds a question-answering bot with SeekrFlow that pairs every answer with a confidence score, a signal for how much to trust the reply. It calls a chat model directly through SeekrFlow's serverless inference and parses the rating out of the response, with no extra frameworks. ## What you'll build A Q\&A bot that: 1. Answers questions about any topic. 2. Returns a confidence score with each answer. 3. Flags low-confidence answers for follow-up. ## Prerequisites * A SeekrFlow API key, set as the `SEEKR_API_KEY` environment variable * Python 3.8 or later * The SeekrFlow SDK: `pip install seekrai` Each question you ask is billed as serverless inference, charged by the token. ## Build it Create `qa_bot.py` with the imports, configuration, and client. ```python qa_bot.py theme={null} import os import re from seekrai import SeekrFlow API_KEY = os.environ["SEEKR_API_KEY"] API_URL = "https://flow.seekr.com/v1/" MODEL_ID = "meta-llama/Meta-Llama-3-8B-Instruct" client = SeekrFlow(api_key=API_KEY, base_url=API_URL) ``` Write a prompt that asks the model for an answer followed by a confidence rating on its own line. Parsing depends on that `Confidence:` marker. Keep it in the instructions. ```python qa_bot.py theme={null} TEMPLATE = """Question: {question} Answer the question above. Then, on a new line starting with 'Confidence:', rate your confidence from 1 (complete guess) to 10 (absolutely certain), and briefly explain the rating. """ ``` Write a helper that splits the answer from the confidence rating and its explanation. ```python qa_bot.py theme={null} def parse_response(response: str) -> dict: """Extract the answer, confidence score, and explanation from a reply.""" answer, confidence, explanation = response, "Not provided", "" if "Confidence:" in response: answer, _, confidence_part = response.partition("Confidence:") answer = answer.strip() confidence_part = confidence_part.strip() rating_match = re.search(r"(\d+)(/10)?", confidence_part) if rating_match: confidence = f"{rating_match.group(1)}/10" explanation = re.sub(r"^\d+(/10)?", "", confidence_part).strip() return {"answer": answer, "confidence": confidence, "explanation": explanation} ``` Wrap the model call and parser in a function that prints the answer, its confidence, and a follow-up hint when confidence is low. A low temperature keeps answers more deterministic. ```python qa_bot.py theme={null} def ask_question(question: str) -> dict: """Send a question to the model and print the parsed result.""" response = client.chat.completions.create( model=MODEL_ID, messages=[{"role": "user", "content": TEMPLATE.format(question=question)}], temperature=0.3, ) parsed = parse_response(response.choices[0].message.content) print(f"Question: {question}\n") print(f"Answer: {parsed['answer']}\n") print(f"Confidence: {parsed['confidence']}") if parsed["explanation"]: print(f"Explanation: {parsed['explanation']}") if parsed["confidence"] in ("1/10", "2/10", "3/10"): print("\nLow confidence. Consider rephrasing or asking for more specifics.") return parsed ``` Run a few questions of varying difficulty to see the confidence score change. ```python qa_bot.py theme={null} questions = [ "What is the capital of France?", "How do quantum computers work?", "When was the book 'Trilby' by George du Maurier published?", ] for q in questions: ask_question(q) print("-" * 50) ``` Run the finished script: ```bash theme={null} python qa_bot.py ``` Easy, well-known questions should come back with high confidence; obscure ones should score lower and trigger the follow-up hint. ## Next steps * **Keep context across turns.** Hold a running `messages` list and include prior turns in each call to answer follow-up questions in context. * **Tune the threshold.** Adjust which confidence scores trigger the follow-up hint to match how cautious you want the bot to be. * **Ground the answers.** Combine this with the [New hire onboarding agent with citations](/flow/recipes/new-hire-onboarding-agent-with-citations) so answers come from your own documents. # Simple RAG agent Source: https://docs.seekr.com/flow/recipes/simple-rag-agent Learn the SeekrFlow building blocks: upload a file, index it in a vector store, and give an agent a FileSearch tool to answer from it. This recipe walks through the fundamental parts of the SeekrFlow SDK by building a retrieval-augmented generation (RAG) agent end to end: upload a document, index it in a vector database, wrap that database in a FileSearch tool, attach the tool to an agent, promote the agent, and ask it a question. The example writes its own sample document, so you can run the whole thing without preparing any files first. Once it works, swap in your own documents. ## What you'll build An agent that: 1. Indexes a document into a vector database. 2. Searches that database through a FileSearch tool. 3. Answers questions grounded in what it retrieves. ## Prerequisites * A SeekrFlow API key, set as the `SEEKR_API_KEY` environment variable * Python 3.8 or later * The SeekrFlow SDK: `pip install seekrai` This recipe creates billable resources. When you are done, remove them with the [cleanup step](#clean-up). ## Build it Create `rag_agent.py` with the imports, configuration, and client. `RUN_ID` adds a short unique suffix to the resource names so repeat runs don't collide. ```python rag_agent.py theme={null} import os import time import tempfile import uuid from pathlib import Path from seekrai import SeekrFlow from seekrai.types import FilePurpose from seekrai.types.tools import CreateFileSearch, FileSearchConfig from seekrai.types.agents.agent import CreateAgentRequest API_KEY = os.environ["SEEKR_API_KEY"] API_URL = "https://flow.seekr.com/v1/" MODEL_ID = "meta-llama/Llama-3.3-70B-Instruct" EMBED_MODEL = "intfloat/e5-mistral-7b-instruct" RUN_ID = uuid.uuid4().hex[:8] client = SeekrFlow(api_key=API_KEY, base_url=API_URL) ``` Write a short Markdown document to a temporary file and upload it with `purpose=FilePurpose.Alignment`, which marks it for data-engine ingestion. ```python rag_agent.py theme={null} document = """\ # Seekr Technologies — Quick Facts Seekr Technologies is an AI company focused on developing trustworthy AI systems. Key facts: - Headquarters: Reston, Virginia, USA - Product: SeekrFlow, a platform for building and deploying AI agents - Mission: responsible AI that people can trust - SeekrFlow supports multi-agent orchestration, RAG, and custom Python tools """ with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False, prefix="seekr_facts_") as f: f.write(document) tmp_path = Path(f.name) file_obj = client.files.upload(tmp_path, purpose=FilePurpose.Alignment) print(f"Uploaded: {file_obj.id} ({file_obj.filename})") ``` To index several documents, upload them with `client.files.bulk_upload`, collect the returned IDs, and include them all in a single `create_ingestion_job` call. ```python theme={null} paths = ["guidebook.pdf", "policies.md", "faq.docx"] uploaded = client.files.bulk_upload(paths, purpose=FilePurpose.Alignment) file_ids = [f.id for f in uploaded] # Then ingest them together: # client.vector_database.create_ingestion_job(database_id=db.id, files=file_ids) ``` Create a vector database. Documents you ingest are embedded with the model you name here and stored for retrieval. ```python rag_agent.py theme={null} db = client.vector_database.create( name=f"RAG Demo DB {RUN_ID}", model=EMBED_MODEL, description="Demo vector database for the RAG agent walkthrough.", ) print(f"Created vector database: {db.id}") ``` Start an ingestion job to chunk, embed, and store the file, then poll until it completes. ```python rag_agent.py theme={null} job = client.vector_database.create_ingestion_job(database_id=db.id, files=[file_obj.id]) print(f"Ingestion job: {job.id} ({job.status})") deadline = time.time() + 300 while time.time() < deadline: job = client.vector_database.retrieve_ingestion_job(db.id, job.id) print(f" status: {job.status}") if job.status == "completed": break if job.status in ("failed", "error"): raise RuntimeError(f"Ingestion failed: {job.error_message}") time.sleep(5) else: raise TimeoutError("Ingestion did not complete within 300s.") print("Ingestion complete.") ``` Wrap the vector database in a FileSearch tool. The `file_search_index` points the tool at your database, and the `description` tells the agent when to use it. ```python rag_agent.py theme={null} tool = client.tools.create( CreateFileSearch( name=f"seekr_facts_search_{RUN_ID}", description="Search the Seekr Technologies knowledge base for facts about the company.", config=FileSearchConfig(file_search_index=db.id), ) ) print(f"Created tool: {tool.id}") ``` Create an agent, attach the tool by ID, and instruct it to answer from what the tool retrieves. ```python rag_agent.py theme={null} agent = client.agents.create( CreateAgentRequest( name=f"RAG Demo Agent {RUN_ID}", instructions=( "You are a helpful assistant with access to a knowledge base about Seekr Technologies. " "When the user asks a question, search the knowledge base using your tool and answer " "based on what you find." ), model_id=MODEL_ID, tool_ids=[tool.id], ) ) print(f"Created agent: {agent.id}") ``` Promote the agent to deploy it, then wait for it to become `Active`. ```python rag_agent.py theme={null} client.agents.promote(agent.id) deadline = time.time() + 120 while time.time() < deadline: agent = client.agents.retrieve(agent.id) print(f" status: {agent.status.value}") if agent.status.value == "Active": break if agent.status.value == "Failed": raise RuntimeError("Agent failed to deploy.") time.sleep(3) else: raise TimeoutError("Agent did not become Active within 120s.") print("Agent is Active.") ``` Create a thread, send a question, wait for the run to finish, and print the agent's reply. ```python rag_agent.py theme={null} thread = client.agents.threads.create() client.agents.threads.create_message( thread_id=thread.id, role="user", content="Where is Seekr Technologies headquartered and what do they make?", ) run_response = client.agents.runs.run(agent_id=agent.id, thread_id=thread.id, stream=False) deadline = time.time() + 300 while time.time() < deadline: run = client.agents.runs.retrieve(run_response.run_id, thread.id) if run.status.value == "completed": break if run.status.value in ("failed", "canceled"): raise RuntimeError(f"Run ended with status: {run.status.value}") time.sleep(3) else: raise TimeoutError("Run did not complete within 300s.") messages = client.agents.threads.list_messages(thread.id, limit=10, order="desc") answer = next((m.content for m in messages if m.role == "assistant"), "(no assistant message found)") print("\nAgent answer:\n") print(answer if isinstance(answer, str) else str(answer)) ``` Run the finished script: ```bash theme={null} python rag_agent.py ``` The agent searches the indexed document and answers that Seekr Technologies is headquartered in Reston, Virginia, and builds SeekrFlow.

Clean up resources (optional)

This shuts down the agent and removes the tool, vector database, and file the recipe created. ```python rag_agent.py theme={null} client.agents.demote(agent.id) client.agents.delete(agent.id) client.tools.delete(tool.id) client.vector_database.delete(db.id) client.files.delete(file_obj.id) print("Deleted the agent, tool, vector database, and file.") ``` ## Next steps * **Use your own documents.** Replace the inline document with real files (PDF, DOCX, or Markdown) to build a knowledge base for your own domain. * **Add citations and confidence.** See [New hire onboarding agent with citations](/flow/recipes/new-hire-onboarding-agent-with-citations) for a version that rates its confidence and cites sources. * **Tune retrieval.** Set `top_k` and `score_threshold` on `FileSearchConfig` to control how much context the tool returns. # Weather agent with a custom Python tool Source: https://docs.seekr.com/flow/recipes/weather-agent-custom-python-tool Build a SeekrFlow agent that calls your own Python function as a tool, where the function fetches live data from an external API. This recipe shows the smallest useful pattern for extending an agent with your own code: you write a plain Python function, register it as a custom function, wrap it in a `run_python` tool, and attach that tool to an agent. When the agent decides it needs live data, SeekrFlow runs your function and feeds the result back into the conversation. The example function calls a public weather API ([wttr.in](https://wttr.in)) and returns the forecast for a single ZIP code, so you can see the full round trip from agent to your code to a third-party service and back. ## What you'll build An agent that: 1. Exposes a custom Python function as a `run_python` tool. 2. Calls the tool whenever the user asks about the weather. 3. Runs your function, which requests live data from an external API. 4. Reports back exactly what the API returned. ## Prerequisites * A SeekrFlow API key, set as the `SEEKR_API_KEY` environment variable * Python 3.8 or later * The SeekrFlow SDK: `pip install seekrai` This recipe creates billable resources. When you are done, remove them with the [cleanup step](#clean-up). ## Build it Save the following as `weather_fn.py`. This is an ordinary Python function with no SeekrFlow dependencies. The docstring matters: SeekrFlow uses it to tell the agent what the tool does and when to call it, so write it the way you would write a tool description. ```python weather_fn.py theme={null} import urllib.request import urllib.error def get_current_weather() -> str: """Get the current weather for ZIP code 22207 (Arlington, VA). Fetches live weather data from a public API. Always call this tool when the user asks about the weather or wants a weather report. Returns: str: Raw weather data from the API, or an error message. """ url = "https://wttr.in/22207?0" try: req = urllib.request.Request(url, headers={"User-Agent": "curl/7.64.1"}) with urllib.request.urlopen(req, timeout=10) as resp: status = resp.status body = resp.read().decode() return f"[HTTP {status}] {body}" except urllib.error.HTTPError as e: return f"[HTTPError {e.code}] {e.reason}: {e.read().decode()}" except urllib.error.URLError as e: return f"[URLError] {e.reason}" except Exception as e: return f"[Error] {type(e).__name__}: {e}" ``` The function catches its own errors and returns them as a string instead of raising. That way a failed API call comes back to the agent as readable text it can relay, rather than crashing the run. Create a second file, `weather_agent.py`, for the agent itself. Start with the imports, configuration, and client. Keep `weather_fn.py` in the same directory, since you will upload it by path in a later step. ```python weather_agent.py theme={null} import os import time from seekrai import SeekrFlow from seekrai.types.tools import CreateRunPython, RunPythonConfig from seekrai.types.agents.agent import CreateAgentRequest API_KEY = os.environ["SEEKR_API_KEY"] API_URL = "https://flow.seekr.com/v1/" MODEL_ID = "meta-llama/Llama-3.1-70B-Instruct" FUNCTION_FILE = "weather_fn.py" AGENT_NAME = "Weather Agent" TOOL_NAME = "weather_tool" FUNCTION_NAME = "get_current_weather" client = SeekrFlow(api_key=API_KEY, base_url=API_URL) ``` This recipe uses `meta-llama/Llama-3.1-70B-Instruct`. A larger instruct model follows the "always call the tool" instruction reliably and handles the tool-calling handshake well. Any instruct model that supports tool calling works here, so you can substitute a smaller or newer model such as `meta-llama/Llama-3.3-70B-Instruct` to trade some quality for speed and cost. These helpers wait for asynchronous operations to finish: one polls a run until it completes, and one polls the agent until it is `Active` after promotion. Add them to `weather_agent.py`. ```python weather_agent.py theme={null} def run_agent(agent_id: str, prompt: str, timeout: int = 300) -> str: thread = client.agents.threads.create() client.agents.threads.create_message(thread_id=thread.id, role="user", content=prompt) run_response = client.agents.runs.run(agent_id=agent_id, thread_id=thread.id, stream=False) deadline = time.time() + timeout while time.time() < deadline: run = client.agents.runs.retrieve(run_response.run_id, thread.id) if run.status.value == "completed": break if run.status.value in ("failed", "canceled"): raise RuntimeError(f"Run ended with status: {run.status.value}") time.sleep(3) else: raise TimeoutError(f"Run did not complete within {timeout}s.") messages = client.agents.threads.list_messages(thread.id, limit=10, order="desc") for msg in messages: if msg.role == "assistant": return msg.content if isinstance(msg.content, str) else str(msg.content) return "(no assistant message found)" def promote_and_wait(agent_id: str, timeout: int = 120) -> None: client.agents.promote(agent_id) deadline = time.time() + timeout while time.time() < deadline: agent = client.agents.retrieve(agent_id) if agent.status.value == "Active": return if agent.status.value == "Failed": raise RuntimeError(f"Agent {agent_id} failed to deploy.") time.sleep(3) raise TimeoutError(f"Agent did not become Active within {timeout}s.") ``` Upload `weather_fn.py` so SeekrFlow can run it. The returned function ID connects your code to the tool in the next step. ```python weather_agent.py theme={null} fn = client.agents.custom_functions.create(file_path=FUNCTION_FILE) print(f"Function registered: {fn.id!r}") ``` Wrap the registered function in a `run_python` tool. The `description` is what the agent sees when it decides whether to call the tool, so make it specific. ```python weather_agent.py theme={null} tool = client.tools.create( CreateRunPython( name=TOOL_NAME, description="Fetches the current weather for ZIP code 22207 (Arlington, VA) from a live API.", config=RunPythonConfig(function_ids=[fn.id]), ) ) print(f"Tool created: {tool.id!r}") ``` Create the agent, attach the tool by ID, and give it instructions that tell it to always call the tool for weather questions. ```python weather_agent.py theme={null} agent = client.agents.create( CreateAgentRequest( name=AGENT_NAME, instructions=( "You are a weather assistant. Whenever the user asks about the weather, " "you MUST call the 'weather_tool' first and then report exactly what it returned." ), model_id=MODEL_ID, tool_ids=[tool.id], ) ) print(f"Agent created: {agent.id!r}") ``` Promote the agent to deploy it, then wait for it to become `Active`. ```python weather_agent.py theme={null} promote_and_wait(agent.id) print(f"'{AGENT_NAME}' is Active.") ``` Send a prompt and print the agent's reply. Because the instructions require it, the agent calls your function, which requests live data from wttr.in, and then reports the result. ```python weather_agent.py theme={null} response = run_agent(agent.id, "What's the weather like right now?") print("\nAgent says:\n") print(response) ``` Run the finished script: ```bash theme={null} python weather_agent.py ``` You should see the agent report the current Arlington, VA forecast, sourced live from the weather API through your function.

Clean up resources (optional)

Promoted agents and their tools stay in your account until you remove them. When you are done experimenting, tear down the resources this recipe created. This deletes every agent, tool, and function that matches the names set at the top of `weather_agent.py`, so run it only against a scratch account. ```python weather_agent.py theme={null} for a in [a for a in client.agents.list_agents() if a.name == AGENT_NAME]: try: client.agents.demote(a.id) except Exception: pass client.agents.delete(a.id) print(f"Deleted agent: {a.id!r}") for t in [t for t in client.tools.list().data if t.name == TOOL_NAME]: client.tools.delete(t.id) print(f"Deleted tool: {t.id!r}") for f in [f for f in client.agents.custom_functions.list_functions() if f.name == FUNCTION_NAME]: client.agents.custom_functions.delete(f.id) print(f"Deleted function: {f.id!r}") ``` ## Next steps * **Accept parameters.** The function takes no arguments, so it always reports the same ZIP code. Add a `zip_code: str` parameter and describe it in the docstring so the agent can supply the location from the user's question. * **Call your own API.** Swap the wttr.in request for a call to an internal service to give the agent access to your own live data. * **Add more tools.** Attach several functions to one agent and let it choose which to call based on the question. # Add files to data job Source: https://docs.seekr.com/flow/reference/add_files_to_data_job_v1_flow_data_jobs__data_job_id__add_files_post post /v1/flow/data-jobs/{data_job_id}/add-files Add files to an existing data job. Attach one or more uploaded file IDs to a data job. For non-Markdown files (PDF, DOCX, PPT), ingestion starts automatically — no separate ingestion call is needed. Markdown files bypass ingestion and are alignment-ready immediately. The job status moves to `file_processing` while ingestion runs, then transitions to `needs_review` or `ready_to_start` once complete. For status states and per-file tracking, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). # Delete alignment job Source: https://docs.seekr.com/flow/reference/alignment_delete_v1_flow_alignment__alignment_job_id__delete delete /v1/flow/alignment/{alignment_job_id} Permanently delete an alignment job. The alignment endpoints are deprecated. Use the data jobs endpoints instead. # Generate training pairs Source: https://docs.seekr.com/flow/reference/alignment_generate_v1_flow_alignment_generate_post post /v1/flow/alignment/generate Generate instruction fine-tuning pairs from your data for use in alignment jobs. The alignment endpoints are deprecated. Use the data jobs endpoints instead. # Get alignment job Source: https://docs.seekr.com/flow/reference/alignment_get_v1_flow_alignment__alignment_job_id__get get /v1/flow/alignment/{alignment_job_id} Retrieve the status and details of a specific alignment job. The alignment endpoints are deprecated. Use the data jobs endpoints instead. # List alignment jobs Source: https://docs.seekr.com/flow/reference/alignment_list_v1_flow_alignment_get get /v1/flow/alignment Retrieve a list of all alignment jobs in your organization. The alignment endpoints are deprecated. Use the data jobs endpoints instead. # Get alignment metadata Source: https://docs.seekr.com/flow/reference/alignment_outputs_v1_flow_alignment__alignment_job_id__outputs_get get /v1/flow/alignment/{alignment_job_id}/outputs Retrieve the output file metadata for a completed alignment job. The alignment endpoints are deprecated. Use the data jobs endpoints instead. # Attach to run stream Source: https://docs.seekr.com/flow/reference/attach_to_run_v1_threads__thread_id__runs__run_id__attach_get get /v1/threads/{thread_id}/runs/{run_id}/attach Attach to a run for SSE streaming output. # Bulk upload files Source: https://docs.seekr.com/flow/reference/bulk_file_upload_v1_flow_bulk_files_put put /v1/flow/bulk_files Upload multiple files in a single request. # Cancel alignment job Source: https://docs.seekr.com/flow/reference/cancel_alignment_job_v1_flow_alignment__alignment_job_id__cancel_post post /v1/flow/alignment/{alignment_job_id}/cancel Cancel an alignment job that is queued or in progress. The alignment endpoints are deprecated. Use the data jobs endpoints instead. # Cancel data job Source: https://docs.seekr.com/flow/reference/cancel_data_job_v1_flow_data_jobs__data_job_id__cancel_post post /v1/flow/data-jobs/{data_job_id}/cancel Cancel the alignment job associated with a data job. Cancels the alignment job associated with the specified data job. The job status transitions to `canceled`. Use this to stop a job that is currently running. For job management operations, see [Manage data jobs](/flow/sdk/data-engine/manage-data-jobs). # Cancel fine-tuning job Source: https://docs.seekr.com/flow/reference/cancel_fine_tune_v1_flow_fine_tunes__fine_tune_id__cancel_put put /v1/flow/fine-tunes/{fine_tune_id}/cancel Cancel a fine-tuning job that is queued or in progress. # Cancel run Source: https://docs.seekr.com/flow/reference/cancel_run_v1_threads__thread_id__runs__run_id__cancel_post post /v1/threads/{thread_id}/runs/{run_id}/cancel Cancel an in-progress agent run. # Clone data job Source: https://docs.seekr.com/flow/reference/clone_data_job_v1_flow_data_jobs__data_job_id__clone_post post /v1/flow/data-jobs/{data_job_id}/clone Create a new, editable data job pre-populated from an existing one. # Create message Source: https://docs.seekr.com/flow/reference/create_message_endpoint_v1_threads__thread_id__messages_post post /v1/threads/{thread_id}/messages Create a new message in a thread. # Create thread Source: https://docs.seekr.com/flow/reference/create_thread_endpoint_v1_threads_post post /v1/threads Create a new thread. # Create tool Source: https://docs.seekr.com/flow/reference/create_tool_v1_flow_tools_post post /v1/flow/tools Create a new tool that agents can use to extend their capabilities. Create a tool to extend an agent's capabilities. Supported tool types include file search, web search, code interpreter, custom tools, agent as tool, and MCP connector. For an overview of all tool types and how they work, see [Tools](/flow/sdk/agents/tools). ## MCP connector To create an MCP connector tool, set `type` to `mcp_connector` and provide the server URL in `config.URL`. Optionally include `config.CLIENT_ID` and `config.CLIENT_SECRET` if your MCP server requires OAuth without dynamic client registration. If an OAuth flow is required, the tool is created with a status of `pending_authorization`. Open the `AUTHORIZATION_URL` from the response in a browser and complete the flow. Once authorized, the tool status changes to `active` and it can be linked to an agent. If you don't complete the flow within one hour, the OAuth window expires and the tool moves to `failed` status. To use it again, delete it and create a new one. For servers that require no authentication, the tool is created with `active` status and can be linked to an agent immediately. For a full walkthrough including SDK examples, see [MCP connector](/flow/sdk/agents/mcp-connector). ## Agent as tool To create an agent-as-tool, set `type` to `agent_as_tool` and provide the sub-agent's ID in `config.agent_id`. The sub-agent must already exist before creating the tool. Each agent can only have one agent-as-tool. If an agent-as-tool already exists for the provided `agent_id`, the request returns an error. ### Errors * `"Tool already exists: "` — A tool with this name already exists. Tool names must be unique per user. * `"Tool already exists for given agent: "` — An agent-as-tool already exists for this agent. Each agent can only have one. For a full walkthrough including SDK examples and constraints, see [Agent as tool](/flow/sdk/agents/agent-as-tool). # Create agent v1 Source: https://docs.seekr.com/flow/reference/create_v1_flow_agents_create_post post /v1/flow/agents/create Create a new agent with a model, instructions, and optional tools. This endpoint is deprecated. Use `POST /v2/flow/agents/create` instead. Create an agent configuration that defines the model, instructions, reasoning effort, and tools the agent can use. The `tool_ids` parameter accepts IDs for any tool type, including agent-as-tools. When including agent-as-tools, the sub-agents and their tool wrappers must already exist before creating the supervisor agent. For details on building multi-agent workflows, see [Agent as tool](/flow/sdk/agents/agent-as-tool). # Create agent Source: https://docs.seekr.com/flow/reference/create_v2_flow_agents_create_post post /v2/flow/agents/create Create a new agent with a model, instructions, and optional tools. Create an agent configuration that defines the model, instructions, reasoning effort, and tools the agent can use. The `tool_ids` parameter accepts IDs for any tool type, including agent-as-tools. When including agent-as-tools, the sub-agents and their tool wrappers must already exist before creating the supervisor agent. For details on building multi-agent workflows, see [Agent as tool](/flow/sdk/agents/agent-as-tool). # Create vector database ingestion job Source: https://docs.seekr.com/flow/reference/create_vector_database_ingestion_job_v1_flow_vectordb__database_id__ingestion_post post /v1/flow/vectordb/{database_id}/ingestion Start a new ingestion job to add files to a vector database. Submit file IDs and chunking configuration to start a vector database ingestion job. The system converts files, generates embeddings, and indexes them in the specified database. The response includes a `file_records` array with per-file tracking. Each record contains the file's status, timestamps for each state transition, and error diagnostics if a failure occurs. Ingestion also captures source tracing metadata for every chunk — line numbers, character offsets, heading hierarchy, and source page number — stored alongside the embedding. This enables full provenance tracing from model output back to the original uploaded file via the chunk endpoint. For job states, error codes, and SDK examples, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). To get started with vector databases, see [Create and populate a vector database](https://docs.seekr.com/docs/create-and-populate-a-vector-database-sdk). # Create vector database Source: https://docs.seekr.com/flow/reference/create_vector_database_route_v1_flow_vectordb_post post /v1/flow/vectordb Create a new vector database for use with file search tools. # Data jobs Source: https://docs.seekr.com/flow/reference/data-jobs Data jobs are the primary workflow for generating AI-ready training datasets. Each job bundles file ingestion, Markdown review, prompt generation, and alignment configuration into a single tracked operation. For SDK walkthroughs, see [Create instruction fine-tuning data](/flow/sdk/data-engine/standard-instruction-finetuning), [Create context-grounded fine-tuning data](/flow/sdk/data-engine/context-grounded-fine-tuning-data), and [Manage data jobs](/flow/sdk/data-engine/manage-data-jobs). # Delete data job Source: https://docs.seekr.com/flow/reference/delete_data_job_v1_flow_data_jobs__data_job_id__delete delete /v1/flow/data-jobs/{data_job_id} Permanently delete a data job and its associated alignment job. # Delete file Source: https://docs.seekr.com/flow/reference/delete_file_v1_flow_files__file_id__delete delete /v1/flow/files/{file_id} Permanently delete a file from your organization. # Delete fine-tuning job Source: https://docs.seekr.com/flow/reference/delete_fine_tune_v1_flow_fine_tunes__fine_tune_id__delete delete /v1/flow/fine-tunes/{fine_tune_id} Delete a fine-tuning job and its associated artifacts. # Delete message Source: https://docs.seekr.com/flow/reference/delete_message_endpoint_v1_threads__thread_id__messages__message_id__delete delete /v1/threads/{thread_id}/messages/{message_id} Delete a message by ID. # Delete project Source: https://docs.seekr.com/flow/reference/delete_project_v1_flow_projects__project_id__delete delete /v1/flow/projects/{project_id} Delete a project and disassociate it from its fine-tuning jobs. # Delete function Source: https://docs.seekr.com/flow/reference/delete_python_function_endpoint_v1_functions__function_id__delete delete /v1/functions/{function_id} Delete a Python function by its ID for the user. # Delete thread Source: https://docs.seekr.com/flow/reference/delete_thread_endpoint_v1_threads__thread_id__delete delete /v1/threads/{thread_id} Delete a thread by ID. # Delete tool Source: https://docs.seekr.com/flow/reference/delete_tool_v1_flow_tools__tool_id__delete delete /v1/flow/tools/{tool_id} Delete a tool if it's not referenced by active agents. Permanently delete a tool. A tool cannot be deleted while it is linked to an active agent. Remove the tool from the agent's `tool_ids` first, or demote the agent. ## Agent as tool Deleting an agent-as-tool removes the tool only. The underlying sub-agent is not affected and remains in its current state. # Delete agent v1 Source: https://docs.seekr.com/flow/reference/delete_v1_flow_agents__agent_id__delete delete /v1/flow/agents/{agent_id} Permanently delete an agent by ID. This endpoint is deprecated. Use `DELETE /v2/flow/agents/{agent_id}` instead. Permanently remove an agent from the platform. If the agent is currently active, it is demoted first. For demote-only, use the demote endpoint. Deleting a supervisor does not affect its sub-agents or their agent-as-tool wrappers. A sub-agent cannot be deleted while it is still linked to a supervisor. Unlink it and delete its associated agent-as-tool first. # Delete agent Source: https://docs.seekr.com/flow/reference/delete_v2_flow_agents__agent_id__delete delete /v2/flow/agents/{agent_id} Permanently delete an agent by ID. Permanently remove an agent from the platform. If the agent is currently active, it is demoted first. For demote-only, use the demote endpoint. Deleting a supervisor does not affect its sub-agents or their agent-as-tool wrappers. A sub-agent cannot be deleted while it is still linked to a supervisor. Unlink it and delete its associated agent-as-tool first. # Delete file in vector database Source: https://docs.seekr.com/flow/reference/delete_vector_database_file_v1_flow_vectordb__database_id__files__file_id__delete delete /v1/flow/vectordb/{database_id}/files/{file_id} Remove a file from a vector database. # Delete vector database Source: https://docs.seekr.com/flow/reference/delete_vector_database_route_v1_flow_vectordb__database_id__delete delete /v1/flow/vectordb/{database_id} Permanently delete a vector database and its contents. # Demote agent v1 Source: https://docs.seekr.com/flow/reference/demote_v1_flow_agents__agent_id__demote_put put /v1/flow/agents/{agent_id}/demote Demote an agent to inactive status. This endpoint is deprecated. Use `PUT /v2/flow/agents/{agent_id}/demote` instead. Move an agent to an inactive state. The agent's configuration is retained but it will not handle inference requests. When demoting an agent that has other agents linked as tools, the linked agents are not automatically demoted — each must be demoted individually if needed. An agent that is linked as a tool to another agent cannot be demoted while that relationship is active. Demote the parent agent first, or unlink the agent-as-tool. # Demote deployment Source: https://docs.seekr.com/flow/reference/demote_v1_flow_deployments__deployment_id__demote_put put /v1/flow/deployments/{deployment_id}/demote Move a deployment from production to staging status. # Demote agent Source: https://docs.seekr.com/flow/reference/demote_v2_flow_agents__agent_id__demote_put put /v2/flow/agents/{agent_id}/demote Demote an agent to inactive status. Move an agent to an inactive state. The agent's configuration is retained but it will not handle inference requests. When demoting an agent that has other agents linked as tools, the linked agents are not automatically demoted. Demote each one individually if needed. An agent that is linked as a tool to another agent cannot be demoted while that relationship is active. Demote the parent agent first, or unlink the agent-as-tool. # Create deployment Source: https://docs.seekr.com/flow/reference/deploy_v1_flow_deployments_post post /v1/flow/deployments Deploy a fine-tuned model to a serving endpoint. # Get deployment Source: https://docs.seekr.com/flow/reference/deployment_by_id_v1_flow_deployments__deployment_id__get get /v1/flow/deployments/{deployment_id} Retrieve the configuration and status of a specific deployment. # Preview tool update Source: https://docs.seekr.com/flow/reference/diff_tool_changes_v1_flow_tools__tool_id__diff_patch patch /v1/flow/tools/{tool_id}/diff Preview the changes a patch request would make to a tool without applying them. Returns a before-and-after diff of the affected fields. Tool type cannot be changed after creation. If you include the `type` field in your request, it must match the existing tool type. # Preview agent update v1 Source: https://docs.seekr.com/flow/reference/diff_v1_flow_agents__agent_id__diff_patch patch /v1/flow/agents/{agent_id}/diff Preview the changes a patch request would make to an agent without applying them. Returns a before-and-after diff of the affected fields. This endpoint is deprecated. Use `PATCH /v2/flow/agents/{agent_id}/diff` instead. # Preview agent update Source: https://docs.seekr.com/flow/reference/diff_v2_flow_agents__agent_id__diff_patch patch /v2/flow/agents/{agent_id}/diff Preview the changes a patch request would make to an agent without applying them. Returns a before-and-after diff of the affected fields. # Download fine-tune Source: https://docs.seekr.com/flow/reference/download_fine_tune_v1_flow_fine_tunes__fine_tune_id__download_get get /v1/flow/fine-tunes/{fine_tune_id}/download Download the artifacts for a completed fine-tuning job. # Clone tool Source: https://docs.seekr.com/flow/reference/duplicate_tool_v1_flow_tools__tool_id__duplicate_post post /v1/flow/tools/{tool_id}/duplicate Duplicate an existing tool with a new name. Create a copy of an existing tool. The duplicated tool gets a new ID and can optionally be given a new name. Agent-as-tool type tools cannot be duplicated. Attempting to duplicate an agent-as-tool returns an error. # Error handling Source: https://docs.seekr.com/flow/reference/error-handling Learn about HTTP status codes and error response formats returned by the Seekr API. ## Status codes The Seekr API follows standard HTTP status codes with each response. | HTTP Status Code | Status | Description | | ---------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Success | Successful request! Check the body for appropriate response. | | 204 | Success (No content) | The request was successful and completed, but there is no content to return. Commonly used for successful DELETE operations. | | 400 | Bad Request | Something was incorrect in the request being made. Examples: missing required parameters for a method, malformed request data or bad format. See the message field for specific reason | | 401 | Unauthorized | The request either had no Authorization header included, was wrongly formatted or the Seekr API key passed is not valid. Please contact us. | | 403 | Forbidden | The Seekr API key passed as valid but does not have permission to access the method it was calling. | | 404 | Not Found | Incorrect URL that does not exist. Check the URL for the individual method you are trying to access. | | 422 | Unprocessable Entity | The request was valid but contains semantic errors. This occurs when request validation fails—for example, missing required parameters, incorrect data types, or values that don't meet validation requirements. The response includes detailed validation error messages. | | 500 | Internal Server Error | Oops, that wasn't supposed to happen. Something unexpected went wrong on the Seekr API end. This automatically triggers alerts that engineers respond to. | | 503 | Service Unavailable | Service is temporarily unavailable. This is highly uncommon and would be preceded by a notice of scheduled maintenance. | ## Additional error information Along with the specific the status code, the response will contain additional information about the error with the request. A sample error response will look like this: ```json JSON theme={null} { "error": "Bad Request", "feedVersion": "1.0.0", "message": "The URL is malformed", "requestUrl": "https://services-api.seekr.com/api/v1/news/?url=https%3A%2F%2Fnews.com%2Farticle", "status": 400 } ``` The `message` field will contain useful and specific information about the error to aid the developer in resolving the problem. # Get file contents Source: https://docs.seekr.com/flow/reference/file_download_content_v1_flow_files__file_id__content_get get /v1/flow/files/{file_id}/content Download the raw content of a file by ID. # Get file details Source: https://docs.seekr.com/flow/reference/file_download_v1_flow_files__file_id__get get /v1/flow/files/{file_id} Retrieve metadata and details for a specific file. # Get file token count Source: https://docs.seekr.com/flow/reference/file_token_counts_v1_flow_files_token_counts_get get /v1/flow/files/token-counts Get the token count for one or more files. # Upload file Source: https://docs.seekr.com/flow/reference/file_upload_v1_flow_files_put put /v1/flow/files Upload a file to your organization for use in fine-tuning, alignment, or vector databases. ## Purpose values and file formats Each `purpose` value requires a specific JSONL schema. Each line of the file must be a valid JSON object matching the format for the chosen purpose. ### `fine-tune` and `alignment` Each line requires a `messages` array of `{"role", "content"}` objects. Valid roles are `system`, `user`, and `assistant`. ```json theme={null} {"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "The capital of France is Paris."}]} ``` ### `preference-fine-tune` Each line requires three fields — `messages`, `chosen`, and `rejected` — each an array of `{"role", "content"}` objects. ```json theme={null} {"messages": [{"role": "user", "content": "What is the capital of France?"}], "chosen": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Paris."}], "rejected": [{"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "Lyon."}]} ``` ### `pre-train` Each line requires a single `text` field containing raw training text. ```json theme={null} {"text": "Raw training text goes here."} ``` # Validate file metadata Source: https://docs.seekr.com/flow/reference/file_validate_metadata_v1_flow_files_validate_metadata_post post /v1/flow/files/validate_metadata Validate file metadata before uploading. # Create fine-tuning job Source: https://docs.seekr.com/flow/reference/fine_tune_v1_flow_fine_tune_post post /v1/flow/fine-tune Create a new fine-tuning job using the specified base model and training files. Create a fine-tuning job by specifying a `TrainingConfig` and `InfrastructureConfig`. The `TrainingConfig` accepts an optional `lora_config` parameter for parameter-efficient training using low-rank adaptation. For guidance on configuring LoRA, see [Low-rank adaptation](/flow/sdk/fine-tuning/lora). For the full fine-tuning workflow, see [Create a fine-tuning job](/flow/sdk/fine-tuning/create-fine-tuning-job). # Generate system prompt Source: https://docs.seekr.com/flow/reference/generate_system_prompt_v1_flow_data_jobs_gen_system_prompt_post post /v1/flow/data-jobs/gen_system_prompt Generate a system prompt based on a use case description and optional source documents. Generate a system prompt from user-provided instructions. This endpoint is not tied to a specific data job and can be called before or after job creation. The generated prompt can then be set on a `principle_files` job via `PATCH /v1/flow/data-jobs/{id}`. For usage in context, see [Create instruction fine-tuning data](/flow/sdk/data-engine/standard-instruction-finetuning). # Generate metadata snapshot Source: https://docs.seekr.com/flow/reference/generate_vector_database_metadata_snapshot_v1_flow_vectordb__database_id__metadata_post post /v1/flow/vectordb/{database_id}/metadata Generate or refresh the metadata snapshot for a vector database by sampling its chunks and ranking the most common metadata keys and values. Sample the vector database's chunks and store a fresh metadata snapshot. The snapshot records the most common metadata keys, the most frequent values for each key, and each key's inferred type, capturing up to the 100 most common keys with up to 10 values each from as many as 10,000 chunks. Generating a snapshot replaces the previous one for the vector database rather than adding to it. SeekrFlow also regenerates the snapshot automatically after an ingestion job adds documents. For SDK examples, see [Generate a metadata snapshot](/flow/sdk/data-engine/generate-metadata-snapshot). # Get agent v1 Source: https://docs.seekr.com/flow/reference/get_agent_by_id_v1_flow_agents__agent_id__get get /v1/flow/agents/{agent_id} Retrieve an agent's configuration by ID. This endpoint is deprecated. Use `GET /v2/flow/agents/{agent_id}` instead. # Get agent Source: https://docs.seekr.com/flow/reference/get_agent_by_id_v2_flow_agents__agent_id__get get /v2/flow/agents/{agent_id} Retrieve an agent's configuration by ID. # List linked agents Source: https://docs.seekr.com/flow/reference/get_agents_for_tool_v1_flow_tools__tool_id__agents_get get /v1/flow/tools/{tool_id}/agents Returns the agents that are linked to a given tool. Retrieve all agents that are currently using a specific tool. Use this to check dependencies before updating or deleting a tool. # Get context attribution from run Source: https://docs.seekr.com/flow/reference/get_context_attribution_from_run_v1_explainability_context_attributor_from_run_post post /v1/explainability/context-attributor-from-run Compute context attribution scores for the response generated during a specific agent run. Extracts context, query, and response from an existing agent run, then computes attribution scores across the retrieved sources. **Required fields** * `thread_id` — ID of the thread to analyze **Optional fields** * `run_id` — The run to analyze. If not provided, uses the latest completed run. * `highlight` — A specific portion of the response to attribute * `granularity` — How to partition the context: `sentence` or `chunk` * `top_k` — Number of top sources to return per segment * `num_ablations` — Number of ablation experiments to run (32–256). Auto-computed if not set. * `return_diagnostics` — If `true`, includes internal diagnostic information in the response. Defaults to `false`. # Get context attribution Source: https://docs.seekr.com/flow/reference/get_context_attribution_v1_explainability_context_attributor_post post /v1/explainability/context-attributor Compute context attribution scores for a model response given a set of source documents. Determines which parts of the provided context contributed to the model's response. Attribution can be returned for a specific highlight within the response, or broken into segments across the full response. **Required fields** * `context` — The context text provided to the model * `query` — The user's query or question * `response` — The model's response to attribute **Optional fields** * `highlight` — A specific portion of the response to attribute. If omitted, returns attributions for all response segments. * `granularity` — How to partition the context: `sentence` or `paragraph` * `top_k` — Number of top sources to return per segment * `num_ablations` — Number of ablation experiments to run (32–256). Auto-computed if not set. * `return_diagnostics` — If `true`, includes internal diagnostic information in the response. Defaults to `false`. # Get data job Source: https://docs.seekr.com/flow/reference/get_data_job_v1_flow_data_jobs__data_job_id__get get /v1/flow/data-jobs/{data_job_id} Retrieve details for a specific data job. Returns the full details of a data job, including its status, nested ingestion jobs, per-file records, timeline events, and alignment status. This is the primary endpoint for monitoring a job throughout its lifecycle. For a field-by-field reference on status states, file records, and timeline events, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). # List vector database data jobs Source: https://docs.seekr.com/flow/reference/get_data_jobs_for_vector_database_v1_flow_vectordb__database_id__data_jobs_get get /v1/flow/vectordb/{database_id}/data-jobs Returns the IDs of data jobs that reference a given vector database. Call this to see which data jobs reference a vector database. This is useful for understanding its processing history or checking dependencies before deletion. # List data jobs Source: https://docs.seekr.com/flow/reference/get_data_jobs_v1_flow_data_jobs_get get /v1/flow/data-jobs Retrieve a list of all data jobs. Returns a paginated list of all data jobs. For filter and sort parameters, see [Manage data jobs](/flow/sdk/data-engine/manage-data-jobs). # Get deployment event Source: https://docs.seekr.com/flow/reference/get_deployment_events_by_id_v1_flow_events_deployments__deployment_id__get get /v1/flow/events/deployments/{deployment_id} Retrieve the event history for a specific deployment. # Get deployment metrics Source: https://docs.seekr.com/flow/reference/get_deployment_metrics_v1_flow_metrics_deployments_get get /v1/flow/metrics/deployments Retrieve performance metrics for active deployments. # List deployments Source: https://docs.seekr.com/flow/reference/get_deployments_v1_flow_deployments_get get /v1/flow/deployments Retrieve a list of all deployments in your organization. # List file data jobs Source: https://docs.seekr.com/flow/reference/get_file_data_jobs_v1_flow_files__file_id__data_jobs_get get /v1/flow/files/{file_id}/data-jobs Returns the IDs of data jobs that reference a given file. Call this to see which data jobs have referenced a file. This is useful for auditing a file's processing history or checking dependencies before deletion. # List derived files Source: https://docs.seekr.com/flow/reference/get_file_derived_files_v1_flow_files__file_id__derived_files_get get /v1/flow/files/{file_id}/derived-files Returns the IDs of files derived from a given file, such as alignment outputs. Call this to find files produced from a given file, such as alignment outputs. This is useful for tracing what downstream files exist before deleting a source file. # Get file event Source: https://docs.seekr.com/flow/reference/get_file_events_by_id_v1_flow_events_files__file_id__get get /v1/flow/events/files/{file_id} Retrieve the event history for a specific file. # List file vector databases Source: https://docs.seekr.com/flow/reference/get_file_vector_dbs_v1_flow_files__file_id__vector_dbs_get get /v1/flow/files/{file_id}/vector-dbs Returns the IDs of vector databases that contain a given file. Call this to see which vector databases ingested a file. From there, use [List vector database tools](/flow/reference/get_tools_for_vector_database_v1_flow_vectordb__database_id__tools_get) to find tools using those databases, then [List tools for an agent](/flow/reference/get_agents_for_tool_v1_flow_tools__tool_id__agents_get) to reach agents — giving you the full dependency chain before deletion. # Get fine-tuning job Source: https://docs.seekr.com/flow/reference/get_fine_tune_v1_flow_fine_tunes__fine_tune_id__get get /v1/flow/fine-tunes/{fine_tune_id} Retrieve the status and configuration of a specific fine-tuning job. # Get fine-tuning event Source: https://docs.seekr.com/flow/reference/get_finetune_events_by_id_v1_flow_events_finetunes__finetune_id__get get /v1/flow/events/finetunes/{finetune_id} Retrieve the event history for a specific fine-tuning job. # Get health Source: https://docs.seekr.com/flow/reference/get_health_external_v1_flow_health_get get /v1/flow/health Check the health and availability of the SeekrFlow API. # Get influential training data Source: https://docs.seekr.com/flow/reference/get_influential_training_data_route_v1_flow_explain_models__model_id__influential_finetuning_data_get get /v1/flow/explain/models/{model_id}/influential-finetuning-data Retrieve influential QA pair training data for a specific model. # Get message Source: https://docs.seekr.com/flow/reference/get_message_endpoint_v1_threads__thread_id__messages__message_id__get get /v1/threads/{thread_id}/messages/{message_id} Get a message by ID. Retrieve a single message by ID. For assistant messages where file search was used, the content includes source tracing fields per retrieved chunk: `chunk_id`, `page`, `lines`, and `section`. Use `chunk_id` to call the chunk endpoint for full Markdown provenance and the `file_id` of the source document. # Get project Source: https://docs.seekr.com/flow/reference/get_project_by_id_v1_flow_projects__project_id__get get /v1/flow/projects/{project_id} Retrieve the details of a specific project. # List projects Source: https://docs.seekr.com/flow/reference/get_projects_v1_flow_projects_get get /v1/flow/projects Retrieve a list of all projects in your organization. # Get function Source: https://docs.seekr.com/flow/reference/get_python_function_endpoint_v1_functions__function_id__get get /v1/functions/{function_id} Retrieve a Python function by its ID for the user. # Get run Source: https://docs.seekr.com/flow/reference/get_run_endpoint_v1_threads__thread_id__runs__run_id__get get /v1/threads/{thread_id}/runs/{run_id} Get a run by ID. # Get thread Source: https://docs.seekr.com/flow/reference/get_thread_endpoint_v1_threads__thread_id__get get /v1/threads/{thread_id} Get a thread by ID. # Get tool Source: https://docs.seekr.com/flow/reference/get_tool_v1_flow_tools__tool_id__get get /v1/flow/tools/{tool_id} Get a specific tool by ID. Retrieve the full configuration and metadata for a specific tool, including its type, description, config, and status. # List vector database tools Source: https://docs.seekr.com/flow/reference/get_tools_for_vector_database_v1_flow_vectordb__database_id__tools_get get /v1/flow/vectordb/{database_id}/tools Returns the IDs of file search tools that reference a given vector database. Call this to find file search tools that use a given vector database. From there, use [List tools for an agent](/flow/reference/get_agents_for_tool_v1_flow_tools__tool_id__agents_get) to find agents depending on those tools — giving you the full downstream dependency chain before deletion. # Get vector database chunk Source: https://docs.seekr.com/flow/reference/get_vector_database_chunk_v1_flow_vectordb__database_id__chunk__chunk_id__get get /v1/flow/vectordb/{database_id}/chunk/{chunk_id} Retrieve provenance details for a chunk in a vector database. Returns the text content of the specified chunk along with its location within the source file and a reference to the original uploaded file. Location data includes line numbers, character offsets, page number, and the heading hierarchy at the point where the chunk appears. The `file_id` in the response identifies the source document and can be used with the file download endpoint to retrieve it. The `chunk_id` required to call this endpoint is available in the assistant message content after a run that used the file search tool. Each chunk in the message includes `chunk_id` alongside `page`, `lines`, and `section`, giving you a complete lineage chain from model output to the original source file. `page_number` is `null` for native Markdown and JSON files, which have no page structure. # Get vector database ingestion job status Source: https://docs.seekr.com/flow/reference/get_vector_database_ingestion_job_v1_flow_vectordb__database_id__ingestion__job_id__get get /v1/flow/vectordb/{database_id}/ingestion/{job_id} Retrieve the status of a specific vector database ingestion job. Retrieve the full details of a vector database ingestion job, including its status, output files, and `file_records` array. Each file record includes the file's processing state, timestamps for each state transition, queue position, and error diagnostics when failures occur. Once completed, source tracing metadata (line numbers, character offsets, heading hierarchy, and source page number) is available for every indexed chunk via the chunk endpoint. For job states, error codes, and SDK examples, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). # Get metadata snapshot Source: https://docs.seekr.com/flow/reference/get_vector_database_metadata_snapshot_v1_flow_vectordb__database_id__metadata_get get /v1/flow/vectordb/{database_id}/metadata Retrieve the current metadata snapshot for a vector database, listing the most common metadata keys and values across its chunks. Return the current metadata snapshot for a vector database. The snapshot lists the most common metadata keys, the inferred type of each, and the most common values per key. For SDK examples, see [Generate a metadata snapshot](/flow/sdk/data-engine/generate-metadata-snapshot). # Get vector database Source: https://docs.seekr.com/flow/reference/get_vector_database_route_v1_flow_vectordb__database_id__get get /v1/flow/vectordb/{database_id} Retrieve the configuration and status of a specific vector database. # Get versions Source: https://docs.seekr.com/flow/reference/get_versions_v1_flow_versions_get get /v1/flow/versions Retrieve version information for the SeekrFlow API. # Getting started Source: https://docs.seekr.com/flow/reference/getting-started-with-your-api Learn how to authenticate and make your first Seekr API request. The SeekrFlow API provides programmatic access to train, validate, deploy, and manage AI models. You can use the API to build applications across financial services, customer support, risk management, and compliance workflows. This guide shows you how to authenticate and make your first API request. To use the Python SDK instead, see the [Developer Guide](/flow/sdk/getting-started). ## Prerequisites Before you begin, you need a SeekrFlow account. If you don't have one, [sign up for SeekrFlow](https://apps.seekr.com/flow). ## Get your API key Sign in to the [SeekrFlow dashboard](https://apps.seekr.com/flow). From the user menu, go to **My Account**. From the **My Account** page, go to **API Key**. Generate and copy a new key. Keep your API key secure. Don't share it in publicly accessible areas such as GitHub, client-side code, or support channels. ## Base URL All API requests use this base URL: ``` https://flow.seekr.com/v1 ``` ## Authentication All API requests require authentication. Include your API key in the `Authorization` header: ``` Authorization: YOUR_API_KEY ``` ## Selecting a team Resources belong to a team. To scope a request to a specific team, include the `x-team-id` header with the team's ID: ``` x-team-id: YOUR_TEAM_ID ``` If you omit the header, the request uses your personal workspace. You can find your team IDs on the [Teams Settings page](/flow/app/manage-permissions#find-a-team-id) in the SeekrFlow web interface. For the underlying access model, see [Role-based access control](/flow/role-based-access-control). ## Request and response format For `POST` and `PUT` requests, send data as JSON and include the `Content-Type` header: ```bash cURL theme={null} curl --location 'https://flow.seekr.com/v1/flow/agents/create' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: YOUR_API_KEY' \ --data '{ "name": "EXAMPLE", "instructions": "EXAMPLE", "tools": [ { "name": "web_search", "tool_env": { "WEB_SEARCH_TOOL_DESCRIPTION": "TESTING" } } ], "model_id": "43" }' ``` All responses use JSON format. Each endpoint's response schema is documented in the [SeekrFlow API](/flow/reference/delete_v1_flow_agents__agent_id__delete). ## Versioning The API version is included in the URL path (`v1`). When breaking changes are introduced: 1. A new API version is released. 2. The current version continues to function. 3. You receive notification with migration timelines before deprecation. This approach ensures your application continues to work while you migrate to a new version. # Check inference health Source: https://docs.seekr.com/flow/reference/health_v1_inference_health_get get /v1/inference/health Check the health and availability of the inference service. # Convert PDF files to markdown Source: https://docs.seekr.com/flow/reference/ingest_files_v1_flow_alignment_ingestion_post post /v1/flow/alignment/ingestion Convert PDF files to Markdown format for use in alignment and fine-tuning. The alignment endpoints are deprecated. Use the data jobs endpoints instead. Submit one or more uploaded file IDs to start an ingestion job. The system converts each file to markdown for use in downstream workflows like fine-tuning. The response includes a `file_records` array with per-file tracking. Each record contains the file's status, timestamps for each state transition, and error diagnostics if a failure occurs. For job states, error codes, and SDK examples, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). # Convert PDF files to markdown Source: https://docs.seekr.com/flow/reference/ingest_files_v1_flow_ingestion_post post /v1/flow/ingestion Convert PDF files to Markdown format for use in data jobs and fine-tuning. # Get file conversion job Source: https://docs.seekr.com/flow/reference/ingestion_get_v1_flow_alignment_ingestion__ingestion_job_id__get get /v1/flow/alignment/ingestion/{ingestion_job_id} Retrieve the status and file records for a specific file conversion job. The alignment endpoints are deprecated. Use the data jobs endpoints instead. Retrieve the full details of an ingestion job, including its status, output files, and `file_records` array. Each file record includes the file's processing state, timestamps for each state transition, queue position, and error diagnostics when failures occur. For job states, error codes, and SDK examples, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). # Get file conversion job Source: https://docs.seekr.com/flow/reference/ingestion_get_v1_flow_ingestion__ingestion_job_id__get get /v1/flow/ingestion/{ingestion_job_id} Retrieve the status and file records for a specific file conversion job. # List file conversion jobs Source: https://docs.seekr.com/flow/reference/ingestion_list_v1_flow_alignment_ingestion_get get /v1/flow/alignment/ingestion Retrieve a list of all file conversion jobs in your organization. The alignment endpoints are deprecated. Use the data jobs endpoints instead. Retrieve a paginated list of all ingestion jobs. Each job includes its current status and `file_records` with per-file tracking. For details on interpreting job states and file records, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). # List file conversion jobs Source: https://docs.seekr.com/flow/reference/ingestion_list_v1_flow_ingestion_get get /v1/flow/ingestion Retrieve a list of all file conversion jobs in your organization. # List agents v1 Source: https://docs.seekr.com/flow/reference/list_agents_v1_flow_agents__get get /v1/flow/agents/ Retrieve a list of all agents in your organization. This endpoint is deprecated. Use `GET /v2/flow/agents` instead. # List agents Source: https://docs.seekr.com/flow/reference/list_agents_v2_flow_agents__get get /v2/flow/agents/ Retrieve a list of all agents in your organization. # List files Source: https://docs.seekr.com/flow/reference/list_files_v1_flow_files_get get /v1/flow/files Retrieve a list of all files in your organization. # List fine-tuning jobs Source: https://docs.seekr.com/flow/reference/list_fine_tune_v1_flow_fine_tunes_get get /v1/flow/fine-tunes Retrieve a list of all fine-tuning jobs in your organization. # List messages Source: https://docs.seekr.com/flow/reference/list_messages_endpoint_v1_threads__thread_id__messages_get get /v1/threads/{thread_id}/messages List messages in a thread. Returns all messages in a thread in chronological order. Use this after a run completes to read the agent's response. When the agent used file search, each retrieved chunk's source tracing fields are appended to the assistant message content: `chunk_id`, `page`, `lines`, and `section`. Use `chunk_id` to call the chunk endpoint for full Markdown provenance and the `file_id` of the source document. # List functions Source: https://docs.seekr.com/flow/reference/list_python_function_endpoint_v1_functions_get get /v1/functions Retrieve a list of all Python functions in your organization. # List runs Source: https://docs.seekr.com/flow/reference/list_runs_endpoint_v1_threads__thread_id__runs_get get /v1/threads/{thread_id}/runs List runs in a thread. # List threads Source: https://docs.seekr.com/flow/reference/list_threads_endpoint_v1_threads_get get /v1/threads Retrieve a list of all threads in your organization. # List tools Source: https://docs.seekr.com/flow/reference/list_tools_v1_flow_tools_get get /v1/flow/tools Retrieve a list of all tools in your organization. Retrieve a paginated list of tools. Use the `tool_type` parameter to filter by type—for example, `tool_type=agent_as_tool` returns only agent-as-tool entries. # List chunks Source: https://docs.seekr.com/flow/reference/list_vector_database_chunks_v1_flow_vectordb__database_id__chunks_post post /v1/flow/vectordb/{database_id}/chunks Search and list chunks in a vector database, with optional filtering by file, chunk IDs, or metadata fields. Results are paginated. Return a paginated list of chunks from a vector database. Filter by `file_id`, by specific `chunk_ids`, or by user-defined `metadata` fields. Metadata filters use the same operator syntax as file search filters (`$in`, `$gt`, `$gte`, `$lt`, `$lte`), and multiple filters are combined with AND. Each chunk in the response includes its text, metadata, heading hierarchy, and source locations. # List files in vector database Source: https://docs.seekr.com/flow/reference/list_vector_database_files_v1_flow_vectordb__database_id__files_get get /v1/flow/vectordb/{database_id}/files Retrieve a list of files in a vector database, including their queue positions. # List vector database ingestion jobs Source: https://docs.seekr.com/flow/reference/list_vector_database_ingestion_jobs_v1_flow_vectordb__database_id__ingestion_get get /v1/flow/vectordb/{database_id}/ingestion Retrieve a list of all ingestion jobs for a vector database. Each job in the response includes a `file_records` array that provides per-file tracking. Every file gets its own record with independent status, timestamps, and error information. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion) for a full guide to job states, file record fields, and error handling. # List vector databases Source: https://docs.seekr.com/flow/reference/list_vector_databases_v1_flow_vectordb_get get /v1/flow/vectordb Retrieve a list of all vector databases in your organization. Retrieve a paginated list of ingestion jobs for a specific vector database. Each job includes its current status and `file_records` with per-file tracking. For details on interpreting job states and file records, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). # Get model Source: https://docs.seekr.com/flow/reference/ml_model_by_model_id_v1_flow_models_info_get get /v1/flow/models/info Retrieve details and metadata for a specific model. # Get model revision Source: https://docs.seekr.com/flow/reference/ml_model_hf_revision_by_model_name_v1_flow_models_hf_revision_get get /v1/flow/models/hf_revision Retrieve the Hugging Face revision hash for a specific model. # List models Source: https://docs.seekr.com/flow/reference/ml_models_v1_flow_models_get get /v1/flow/models Retrieve a list of all available models. # Observability Source: https://docs.seekr.com/flow/reference/observability Observability spans are records of agent runs that capture timing, model usage, token consumption, and error details for every run. Use these endpoints to query spans across runs or retrieve the full detail of a specific span by ID. For SDK walkthroughs, see [Observability](/flow/sdk/observability). # Update data job Source: https://docs.seekr.com/flow/reference/patch_data_job_v1_flow_data_jobs__data_job_id__patch patch /v1/flow/data-jobs/{data_job_id} Update the details of an existing data job. Update metadata on an existing data job. Fields are locked once alignment is running. For editable fields and locking behavior, see [Manage data jobs](/flow/sdk/data-engine/manage-data-jobs). # Modify fine-tuning job Source: https://docs.seekr.com/flow/reference/patch_fine_tune_v1_flow_fine_tunes__fine_tune_id__patch patch /v1/flow/fine-tunes/{fine_tune_id} Update the configuration of an existing fine-tuning job. # Update tool Source: https://docs.seekr.com/flow/reference/patch_tool_v1_flow_tools__tool_id__patch patch /v1/flow/tools/{tool_id} Partially update an existing tool. Omitted fields remain unchanged. Tool type cannot be changed after creation. If you include the `type` field in your request, it must match the existing tool type. Tool updates propagate immediately to all agents using the tool. ## MCP connector You can update `name` and `description`. If you need to connect to a different server or change credentials, create a new MCP connector tool and update your agent's `tool_ids`. ## Agent as tool You can update `name` and `description`. The underlying sub-agent cannot be changed. To use a different sub-agent, create a new agent-as-tool for that sub-agent. # Update agent v1 Source: https://docs.seekr.com/flow/reference/patch_v1_flow_agents__agent_id__patch patch /v1/flow/agents/{agent_id} Partially update an agent's configuration. Omitted fields remain unchanged. This endpoint is deprecated. Use `PATCH /v2/flow/agents/{agent_id}` instead. Active agents transition to `Updating` during the patch and return to `Active` once complete. If redeployment fails, the agent status is set to `Failed`. Agents in `Inactive` or `Failed` states remain in their current state after a patch. To activate an updated agent, [promote it](/flow/reference/promote_v1_flow_agents__agent_id__promote_put) manually. The `tool_ids` parameter accepts IDs for any tool type, including agent-as-tools. Agent-as-tools must be created before adding them to `tool_ids`. See [Agent as tool](/flow/sdk/agents/agent-as-tool) for setup instructions. # Update agent Source: https://docs.seekr.com/flow/reference/patch_v2_flow_agents__agent_id__patch patch /v2/flow/agents/{agent_id} Partially update an agent's configuration. Omitted fields remain unchanged. Active agents transition to `Updating` during the patch and return to `Active` once complete. If redeployment fails, the agent status is set to `Failed`. Agents in `Inactive` or `Failed` states remain in their current state after a patch. To activate an updated agent, [promote it](/flow/reference/promote_v2_flow_agents__agent_id__promote_put) manually. The `tool_ids` parameter accepts IDs for any tool type, including agent-as-tools. Agent-as-tools must be created before adding them to `tool_ids`. See [Agent as tool](/flow/sdk/agents/agent-as-tool) for setup instructions. # Promote agent v1 Source: https://docs.seekr.com/flow/reference/promote_v1_flow_agents__agent_id__promote_put put /v1/flow/agents/{agent_id}/promote Promote an agent to active status so it can serve requests. This endpoint is deprecated. Use `PUT /v2/flow/agents/{agent_id}/promote` instead. Activate an agent so it can handle inference requests. Agents are automatically promoted on creation—this endpoint is only needed after an agent has been demoted. When promoting an agent that has sub-agents linked as tools, SeekrFlow automatically promotes the sub-agents first. The supervisor remains in `Pending` state until all sub-agents are ready. # Promote deployment Source: https://docs.seekr.com/flow/reference/promote_v1_flow_deployments__deployment_id__promote_put put /v1/flow/deployments/{deployment_id}/promote Promote a deployment from staging to production status. # Promote agent Source: https://docs.seekr.com/flow/reference/promote_v2_flow_agents__agent_id__promote_put put /v2/flow/agents/{agent_id}/promote Promote an agent to active status so it can serve requests. Activate an agent so it can handle inference requests. Agents are automatically promoted on creation. You only need this endpoint after an agent has been demoted. When promoting an agent that has sub-agents linked as tools, SeekrFlow automatically promotes the sub-agents first. The supervisor remains in `Pending` state until all sub-agents are ready. # Query spans Source: https://docs.seekr.com/flow/reference/query_spans_v1_observability_spans_post post /v1/observability/spans Query observability spans filtered by user and other criteria. Returns a list of span summaries matching the provided filters. All filters are optional. If `min_start_datetime` is not provided, the query defaults to the last 15 minutes. Start with `run_id` when investigating a specific agent run. Use `limit` and `offset` to paginate results and `order` to sort by start time. To retrieve the full record for a specific span, use the [retrieve span](/flow/reference/retrieve_span_v1_observability_spans__span_id__get) endpoint. # Remove files from data job Source: https://docs.seekr.com/flow/reference/remove_files_from_data_job_v1_flow_data_jobs__data_job_id__remove_files_post post /v1/flow/data-jobs/{data_job_id}/remove-files Remove files from an existing data job. Remove one or more file IDs from a data job. Use this to replace a failed file or remove an unwanted file before starting alignment. Files can only be removed before the job has started running. # Change file name Source: https://docs.seekr.com/flow/reference/rename_file_v1_flow_files__file_id__rename_put put /v1/flow/files/{file_id}/rename Update the display name of an existing file. # Get span Source: https://docs.seekr.com/flow/reference/retrieve_span_v1_observability_spans__span_id__get get /v1/observability/spans/{span_id} Retrieve a specific observability span by ID. Use this endpoint to retrieve the complete record for a specific span. The [query spans](/flow/reference/query_spans_v1_observability_spans_post) endpoint returns span summaries. This endpoint returns the full span object. # Create chat completion Source: https://docs.seekr.com/flow/reference/route_chat_completion_v1_inference_chat_completions_post post /v1/inference/chat/completions Generate a chat completion response from a deployed model. # Create completion Source: https://docs.seekr.com/flow/reference/route_completion_v1_inference_completions_post post /v1/inference/completions Generate a text completion response from a deployed model. # Create embedding Source: https://docs.seekr.com/flow/reference/route_embeddings_v1_inference_embeddings_post post /v1/inference/embeddings Generate vector embeddings for one or more input texts. # Transcribe audio Source: https://docs.seekr.com/flow/reference/route_v1_audio_transcriptions_v1_inference_audio_transcriptions_post post /v1/inference/audio/transcriptions Submit an audio file for transcription. # Rerank documents Source: https://docs.seekr.com/flow/reference/route_v1_rerank_v1_inference_rerank_post post /v1/inference/rerank Rerank a list of documents by relevance to a query. # Score text Source: https://docs.seekr.com/flow/reference/route_v1_score_v1_inference_score_post post /v1/inference/score Score a query-document pair for relevance. # Stream agent run Source: https://docs.seekr.com/flow/reference/run_agent_stream_v1_threads__thread_id__runs_stream_post post /v1/threads/{thread_id}/runs/stream Run an agent on a thread and stream the response as server-sent events. # Stream agent run (Vercel AI SDK) Source: https://docs.seekr.com/flow/reference/run_agent_stream_vercel_v1_threads__thread_id__runs_stream_vercel_post post /v1/threads/{thread_id}/runs/stream/vercel Stream an agent run response formatted for the Vercel AI SDK. # Run agent Source: https://docs.seekr.com/flow/reference/run_agent_v1_threads__thread_id__runs_post post /v1/threads/{thread_id}/runs Run an agent on a thread and return the completed response. # Start data job alignment Source: https://docs.seekr.com/flow/reference/start_data_job_alignment_v1_flow_data_jobs__data_job_id__start_post post /v1/flow/data-jobs/{data_job_id}/start Start the alignment process for a data job. Start the alignment process for a data job. The job must be in `ready_to_start` status. Pre-flight checks vary by job type: * For `principle_files` jobs: a `system_prompt` must be set and files have been added to the data job * For `context_grounded_files` jobs: files must have been added to the data job * For `context_grounded_vector_db` jobs: a `vector_database_id` must be set For the full pre-flight requirements and workflow, see [Create instruction fine-tuning data](/flow/sdk/data-engine/standard-instruction-finetuning). # Submit data job Source: https://docs.seekr.com/flow/reference/submit_data_job_v1_flow_data_jobs_post post /v1/flow/data-jobs Create a new data job. Create a new data job. The `job_type` field determines the workflow: * `principle_files` — generates a QA pair dataset for instruction fine-tuning * `context_grounded_files` — generates context-grounded training data from uploaded documents * `context_grounded_vector_db` — generates context-grounded training data using an existing vector database Newly created jobs have no files attached. Use `POST /v1/flow/data-jobs/{id}/add-files` to attach uploaded file IDs after creation. For the complete workflow, see [Create instruction fine-tuning data](/flow/sdk/data-engine/standard-instruction-finetuning) or [Create context-grounded fine-tuning data](/flow/sdk/data-engine/context-grounded-fine-tuning-data). # Update deployment Source: https://docs.seekr.com/flow/reference/update_deployment_v1_flow_deployments__deployment_id__patch patch /v1/flow/deployments/{deployment_id} Update the configuration of an existing deployment. # Update message Source: https://docs.seekr.com/flow/reference/update_message_endpoint_v1_threads__thread_id__messages__message_id__patch patch /v1/threads/{thread_id}/messages/{message_id} Update a message's content and/or metadata. # Update function Source: https://docs.seekr.com/flow/reference/update_python_function_endpoint_v1_functions__function_id__patch patch /v1/functions/{function_id} Update the code or metadata for an existing Python function. # Replace tool Source: https://docs.seekr.com/flow/reference/update_tool_v1_flow_tools__tool_id__put put /v1/flow/tools/{tool_id} Update an existing tool. This endpoint is deprecated. Use `PATCH /v1/flow/tools/{tool_id}` instead. Update a tool's configuration. This endpoint requires full object replacement — include all fields in the request, even those you are not changing, or they will be set to null. ## MCP connector You can update an MCP connector tool's `name` and `description`. The server URL and authentication credentials (`config.URL`, `config.CLIENT_ID`, `config.CLIENT_SECRET`) cannot be updated. To use a different server or credentials, delete the tool and create a new one, then update your agent's `tool_ids`. MCP connector tools cannot be duplicated. ## Agent as tool When updating an agent-as-tool, the `config.agent_id` must match the original sub-agent. You cannot swap the underlying sub-agent—if you need a different one, delete this tool and create a new one. For SDK examples and full constraints, see [Agent as tool](/flow/sdk/agents/agent-as-tool). # Replace agent v1 Source: https://docs.seekr.com/flow/reference/update_v1_flow_agents__agent_id__update_put put /v1/flow/agents/{agent_id}/update Update an agent's model, instructions, or tools. This endpoint is deprecated. Use `PATCH /v2/flow/agents/{agent_id}` instead. Replace an agent's configuration entirely. All fields must be provided—this endpoint does not support partial updates. The `tool_ids` parameter accepts IDs for any tool type, including agent-as-tools. Agent-as-tools must be created before adding them to `tool_ids`. See [Agent as tool](/flow/sdk/agents/agent-as-tool) for setup instructions. When an active supervisor agent is updated to include new sub-agents, the supervisor transitions to `Updating` while the sub-agents are promoted, then returns to `Active` when ready. # Replace agent Source: https://docs.seekr.com/flow/reference/update_v2_flow_agents__agent_id__update_put put /v2/flow/agents/{agent_id}/update Update an agent's model, instructions, or tools. This endpoint is deprecated. Use `PATCH /v2/flow/agents/{agent_id}` instead. Replace an agent's configuration entirely. All fields must be provided; this endpoint does not support partial updates. The `tool_ids` parameter accepts IDs for any tool type, including agent-as-tools. Agent-as-tools must be created before adding them to `tool_ids`. See [Agent as tool](/flow/sdk/agents/agent-as-tool) for setup instructions. When an active supervisor agent is updated to include new sub-agents, the supervisor transitions to `Updating` while the sub-agents are promoted, then returns to `Active` when ready. # Update chunk metadata Source: https://docs.seekr.com/flow/reference/update_vector_database_metadata_v1_flow_vectordb__database_id__metadata_patch patch /v1/flow/vectordb/{database_id}/metadata Overwrite metadata on chunks in a vector database, targeted by file IDs or chunk IDs. This replaces all existing metadata on the targeted chunks. Overwrite user-defined metadata on chunks within a vector database. Target the chunks with exactly one of `chunk_ids` or `file_ids`; providing both, or neither, returns an error. This operation is destructive: the supplied `metadata` object replaces all existing metadata on every targeted chunk, so include any fields you want to keep. # Update vector database Source: https://docs.seekr.com/flow/reference/update_vector_database_route_v1_flow_vectordb__database_id__patch patch /v1/flow/vectordb/{database_id} Update a vector database's name or description. # Create function Source: https://docs.seekr.com/flow/reference/upload_python_function_v1_functions_post post /v1/functions Upload a new Python function for the user. # Create or update project Source: https://docs.seekr.com/flow/reference/upsert_project_v1_flow_projects_post post /v1/flow/projects Create a new project or update an existing one by name. # Vector database Source: https://docs.seekr.com/flow/reference/vector-database The vector database endpoints manage the full lifecycle of your vector databases, from creation and file ingestion to chunk-level provenance. Use these endpoints to create and configure databases, submit ingestion jobs that convert your files into searchable embeddings, and manage the files indexed within each database. Ingestion jobs capture source tracing metadata for every chunk. Use the chunk endpoint to trace any file search result to its exact location in the source document and retrieve the original uploaded file. You can also attach user-defined metadata to chunks, list or filter chunks by that metadata, and edit it after ingestion. # Role-based access control Source: https://docs.seekr.com/flow/role-based-access-control Manage access to SeekrFlow resources through organizations, teams, and role-based permissions. SeekrFlow uses a team-based access model to organize users and control what they can do. All resources (agents, fine-tuning jobs, deployments, files, and vector databases) belong to a team, and access is enforced based on a user's role within that team. Create and manage teams and members through the SeekrFlow web interface. Scope SDK requests to a team to create and read team-owned resources. ## Organizations and teams An **organization** is the top-level container for a SeekrFlow account. All users, teams, and resources belong to a single organization. A **team** is a group of users within an organization. Resources are scoped to a team, meaning each team has its own isolated view of agents, fine-tuning jobs, deployments, files, and vector databases. Users can belong to multiple teams and switch between them to access the resources associated with each. When a new account is created, a new organization is provisioned if the user doesn't already belong to one. An existing organization owner can also invite new users. For self-hosted deployments, a default organization is created during installation. Teams are not automatically provisioned in either case. Each user also gets a personal workspace, a private team with no other members. ## Roles Every user has an organization role and, within each team they belong to, a team role. Together these determine what a user can see and do. ### Organization roles **Owner** – Full organization access to manage settings, teams, and roles. **Member** – Access limited to assigned teams and their resources. ### Team roles **Admin** – Full team access to manage members, roles, and settings. **Creator** – Can contribute within assigned teams without managing roles or access. ### Permissions summary | Action | Owner | Member + admin | Member + creator | | ---------------------------- | ----- | -------------- | ---------------- | | Create, rename, delete teams | ✓ | ✗ | ✗ | | Add and remove team members | ✓ | ✓ | ✗ | | Change member roles | ✓ | ✓ | ✗ | | Create and manage resources | ✓ | ✓ | ✓ | ## Resource isolation Resources are scoped to the team they were created in. When a user switches their active team, the resource lists (agents, fine-tuning jobs, deployments, files, and vector databases) update to show only what belongs to that team. API and SDK calls are similarly scoped to the active team, and requests for resources outside a user's teams are rejected. For how to select a team from the SDK, see [Work with teams](/flow/sdk/teams). ## Migration from single-user deployments Existing users are migrated to an organization, and select users are assigned the Owner role. Existing resources move to each user's personal workspace. No teams are automatically created and no team roles are automatically assigned. Self-hosted customers need to upgrade to the version that includes role-based access control and perform the migration manually. # Agents Source: https://docs.seekr.com/flow/sdk/agents Build and run agents programmatically with the SeekrFlow Python SDK. An agent is an AI system that reasons through problems and executes tasks autonomously. Agents are configured by specifying models, tools, instructions, and reasoning approach—providing everything needed to accomplish tasks from simple workflows to complex, open-ended objectives. Use the SeekrFlow Python SDK to build and run agents programmatically. This section covers the core building blocks: Configure agents, reasoning effort, and tools. Use threads, messages, and runs to run your agent. Control the format of agent responses. Extend agent capabilities with file search, web search, code interpreter, custom tools, and more. # Agent as tool Source: https://docs.seekr.com/flow/sdk/agents/agent-as-tool Use agents as callable tools to build multi-agent workflows. ### What is an agent as tool? An agent-as-tool lets a supervisor agent delegate subtasks to other agents. Instead of handing over control, the supervisor invokes a sub-agent as a callable tool, receives the result, and integrates it into a unified response. This enables composable, multi-agent systems where each agent focuses on a specific capability. Use agent-as-tool when a task spans multiple intents or requires synthesis across specialized skills—for example, a research assistant that calls one sub-agent to fetch data and another to evaluate its relevance, then merges the results. ### How it works **Create sub-agents** – [Create an agent](/flow/sdk/agents/create-agents) for each specific capability, and note its agent ID. **Wrap each sub-agent as a tool** – Create an agent-as-tool that references the sub-agent's ID. **Attach the tools to a supervisor agent** – The supervisor uses the agent-as-tool like any other tool. **Run the supervisor** – The supervisor decides when to invoke sub-agents based on the task and the tool descriptions you provide. Sub-agents and their agent-as-tool wrappers must be created before the supervisor agent that uses them. ## Create an agent as tool First, [create the sub-agent](/flow/sdk/agents/create-agents) you want to expose as a tool and note its agent ID. Then wrap it: ```python Python theme={null} from seekrai import SeekrFlow from seekrai.types import CreateAgentAsTool, AgentAsToolConfig client = SeekrFlow() # Create the agent-as-tool agent_as_tool = client.tools.create( CreateAgentAsTool( name="research-agent-tool", description="Searches the web for current information on a given topic and returns a summary.", config=AgentAsToolConfig( agent_id="agent-abc123", ), ) ) print(f"Tool ID: {agent_as_tool.id}") ``` ### Parameters | Parameter | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------- | | **name** (required) | The name of the tool. Appears in spans and traces. | | **type** (required) | Must be `agent_as_tool`. | | **description** (required) | Helps the supervisor agent decide when to invoke this tool. Included in the supervisor's system prompt. | | **config.agent\_id** (required) | The ID of the sub-agent to run when this tool is invoked. | Each agent can only have one agent-as-tool wrapper. Attempting to create a second agent-as-tool for the same sub-agent returns an error. ## Update an agent as tool You can update the tool's name and description. The underlying sub-agent cannot be changed. To use a different sub-agent, create a new agent-as-tool for that sub-agent. ```python Python theme={null} from seekrai.types import UpdateAgentAsTool updated_tool = client.tools.update( agent_as_tool.id, UpdateAgentAsTool( name="updated-research-tool", description="Updated description for the research sub-agent.", ) ) ``` ## Delete an agent as tool Deleting an agent-as-tool removes the tool only. The underlying sub-agent is not affected. ```python Python theme={null} client.tools.delete(agent_as_tool.id) ``` An agent-as-tool cannot be deleted if it is still linked to a supervisor agent. Unlink it from the supervisor first. ## Attach to a supervisor agent Pass agent-as-tool IDs in the `tool_ids` parameter when creating or updating a supervisor agent. The syntax is the same as for any other tool type. ```python Python theme={null} from seekrai.types import UpdateAgentRequest agent = client.agents.update( agent_id=supervisor.id, request=UpdateAgentRequest( name="Supervisor Agent", instructions="You are a research coordinator. Use your sub-agents to gather and analyze information.", model_id="meta-llama/Llama-3.3-70B-Instruct", reasoning_effort="high", tool_ids=[agent_as_tool.id, web_search_tool.id], ) ) ``` ## Deployment behavior When a supervisor agent is promoted, SeekrFlow automatically promotes any linked sub-agents that are not already active. The supervisor remains in `Pending` state until all sub-agents are ready. When a supervisor is demoted, its sub-agents are **not** automatically demoted. You must demote each sub-agent individually if needed. ## Constraints * **No cycles** — The agent graph must be a tree. Agent A cannot be a tool for Agent B if Agent B is already a tool for Agent A, directly or indirectly. * **One tool per agent** — Each agent can only have one agent-as-tool wrapper. Duplicating an agent-as-tool is not supported. * **Sub-agent deletion** — A sub-agent cannot be deleted while it is still linked to a supervisor. Unlink the agent-as-tool from the supervisor and delete the tool first. * **Sub-agent demotion** — A sub-agent cannot be demoted while its supervisor is active. Either demote the supervisor first, or unlink the sub-agent. # Create and manage agents Source: https://docs.seekr.com/flow/sdk/agents/create-agents Create, configure, and manage agents using the SeekrFlow Python SDK. An agent must be active before it can process requests. Create and promote your agent using the operations below, then see [Run an agent](/flow/sdk/agents/run-an-agent) to start processing requests. ## Create an agent The most common properties of an agent you'll configure are: | Parameter | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | **Required.** A string that identifies your agent. | | `instructions` | Also known as a developer message or system prompt. Guides how the agent operates and generates its response. | | `model_id` | The model used to generate the agent's response. Can be a base model or fine-tuned model. | | `tool_ids` | IDs of the tools the agent can use. Create the tools in the [tool library](/flow/sdk/agents/tools) first, then provide their IDs. | | `reasoning_effort` | How much reasoning the agent uses when working through a request. Accepts `LOW`, `MEDIUM`, or `HIGH`. Defaults to `MEDIUM`. | | `temperature` | **Optional.** Controls the predictability of the agent's reasoning. Lower values produce more consistent results, and higher values introduce more variation. Accepts a value from `0` to `2`. Defaults to `0.6`. | **Endpoint:** [`POST /v1/flow/agents/create`](/flow/reference/create_v1_flow_agents_create_post) ```python Python theme={null} from seekrai.types import CreateAgentRequest, ReasoningEffort from seekrai import SeekrFlow api_key = "your_api_key" client = SeekrFlow(api_key=api_key) agent = client.agents.create( CreateAgentRequest( name="homework_tutor_bot", instructions="You are a tutor bot for middle schoolers. Answers the questions in a way middle schoolers can understand", model_id="meta-llama/Llama-3.3-70B-Instruct", tool_ids=[], reasoning_effort=ReasoningEffort.MEDIUM, temperature=0.6 ) ) print(f"Agent created with ID: {agent.id}") print(f"Agent status: {agent.status}") ``` The model that generates an agent's response can be any base or fine-tuned model available on the SeekrFlow platform. For details on agent status, see [Agent status](/flow/components/agents#agent-status). ### Write effective instructions When writing your agent’s instructions, follow these best practices: 1. **Define role, goal, and context.** Clearly state the agent’s persona, objective, and any relevant background. *Example: “You are a procurement research assistant tasked with finding active government contracts based on user input.”* 2. **Be specific and prescriptive.** Break complex tasks into simpler subgoals and specify how each tool should be used. *Example: “Use the search\_contracts tool only after collecting both a state and keyword.”* 3. **Call out edge cases explicitly.** If the agent should not respond to certain queries, say so directly. *Example: “Do not answer legal or compliance questions — respond with: ‘I’m not able to help with that.’”* 4. **Specify output format.** If not using structured outputs, be clear about the desired format and tone. *Example: “Respond in a numbered list with no more than 3 items. Use plain language and avoid technical jargon.”* ### Configure reasoning effort The `reasoning_effort` level determines how much reasoning the agent uses to process information, decide how to approach the task, and select appropriate tools. SeekrFlow agents support three levels. The default is `MEDIUM`. | Level | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `ReasoningEffort.LOW` | Prioritizes speed. Best for simple, latency-sensitive tasks with a small tool set. | | `ReasoningEffort.MEDIUM` | Balances speed and thoroughness. A good starting point for most use cases. | | `ReasoningEffort.HIGH` | Prioritizes thoroughness. Best for complex workflows with many tools where accuracy matters more than response time. | We recommend experimenting with different levels during agent development to find the optimal configuration for your use case. The `SPEED_OPTIMIZED` and `PERFORMANCE_OPTIMIZED` values are only supported for backward compatibility. Use `LOW`, `MEDIUM`, or `HIGH` for new agents. `SPEED_OPTIMIZED` corresponds to `LOW`, and `PERFORMANCE_OPTIMIZED` to `HIGH`. To adjust how predictable or varied the agent's reasoning is, set `temperature` (a value from `0` to `2`, default `0.6`). Lower values produce more consistent results, and higher values introduce more variation. ### Configure output settings By default, an agent produces a natural-language response using the same `instructions`, `model_id`, and `temperature` that guide its reasoning. To control the response separately, provide an `output` configuration. All of its fields are optional. | Parameter | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `output.instructions` | Instructions for generating the final response. When set, the top-level `instructions` guide only the agent's reasoning, and these guide the response. | | `output.model_id` | The model used to generate the final response, overriding the top-level `model_id`. Can be a base model or fine-tuned model. | | `output.temperature` | Controls the predictability of the final response. Accepts a value from `0` to `2`. Defaults to `0.6`. | | `output.frequency` | When the agent produces a written response: `ALWAYS`, `AUTOMATIC` (the agent decides), or `NEVER`. Use `NEVER` for automation cases where a natural-language response isn't needed. | ```python Python theme={null} from seekrai.types import CreateAgentRequest, AgentOutputConfig, AgentOutputFrequency agent = client.agents.create( CreateAgentRequest( name="research_assistant", instructions="Work through the user's question using the available tools.", model_id="meta-llama/Llama-3.3-70B-Instruct", tool_ids=[], output=AgentOutputConfig( instructions="Summarize the findings in a concise, professional tone.", temperature=0.4, frequency=AgentOutputFrequency.AUTOMATIC, ), ) ) ``` You must provide either `model_id` or `output.model_id`. ## List your agents and their status To list all of the agents you've created and their associated status, you can use the below code snippet: **Endpoint:** [`GET /v1/flow/agents/`](/flow/reference/list_agents_v1_flow_agents__get) ```python Python theme={null} available_agents = client.agents.list_agents() print("Available agents:") for agent in available_agents: print(f"ID: {agent.id}, Name: {agent.name}, Status: {agent.status}") ``` ## Update an agent Use `agents.update` to make partial changes to an existing agent. Provide only the fields you want to change. Omitted fields remain unchanged. **Endpoint:** [`PATCH /v1/flow/agents/{agent_id}`](/flow/reference/patch_v1_flow_agents__agent_id__patch) ```python Python theme={null} from seekrai.types import UpdateAgentRequest updated_agent = client.agents.update( agent_id=agent.id, request=UpdateAgentRequest( instructions="You are a tutor bot for high schoolers. Answer questions in a way high schoolers can understand." ) ) print(f"Agent updated: {updated_agent.id}") ``` | Parameter | Description | | ------------------ | ----------------------------------------------------- | | `name` | Updated agent name. | | `instructions` | Updated system prompt. | | `tool_ids` | Updated list of tool IDs. Replaces the existing list. | | `model_id` | Updated response model. | | `reasoning_effort` | Updated reasoning effort. | | `temperature` | Updated temperature. | | `output` | Updated output configuration. | Agents in `Inactive` or `Failed` states remain in their current state after an update. To activate an updated agent, [promote it](/flow/reference/promote_v1_flow_agents__agent_id__promote_put) manually. ### Preview an agent update Use `agents.update_diff` to simulate an update without applying it. The response shows exactly what would change. **Endpoint:** [`PATCH /v1/flow/agents/{agent_id}/diff`](/flow/reference/diff_v1_flow_agents__agent_id__diff_patch) ```python Python theme={null} from seekrai.types import UpdateAgentRequest diff = client.agents.update_diff( agent_id=agent.id, request=UpdateAgentRequest( name="homework_tutor_bot_v2", instructions="You are a tutor bot for high schoolers." ) ) print(diff) ``` The response includes the complete before and after agent state, and a `diff` object identifying each changed field: ```python Python theme={null} AgentDiffResponse( before=..., after=..., diff={ "name": { "before": "homework_tutor_bot", "after": "homework_tutor_bot_v2" }, "instructions": { "before": "You are a tutor bot for middle schoolers...", "after": "You are a tutor bot for high schoolers." } } ) ``` ## Promote an agent Agent create requests will promote an agent automatically. Agents only need to be promoted after they've been demoted and are in an inactive state. **Endpoint:** [`PUT /v1/flow/agents/{agent_id}/promote`](/flow/reference/promote_v1_flow_agents__agent_id__promote_put) ```python Python theme={null} agent = client.agents.promote(agent.id) print(f"Agent promoted. Agent ID: {agent.id}") ``` When promoting an agent that has [sub-agents linked as tools](/flow/sdk/agents/agent-as-tool), SeekrFlow automatically promotes the sub-agents first. The supervisor remains in `Pending` state until all sub-agents are ready. ## Demote an agent Demoting an agent moves it to an inactive state. This is useful when you want to retain the agent's definition without allowing it to handle inference requests. **Endpoint:** [`PUT /v1/flow/agents/{agent_id}/demote`](/flow/reference/demote_v1_flow_agents__agent_id__demote_put) ```python Python theme={null} agent = client.agents.demote(agent.id) print(f"Agent demoted. Agent ID: {agent.id}") ``` Demoting a supervisor does not automatically demote its sub-agents. Each sub-agent must be demoted individually if needed. A sub-agent cannot be demoted while it is still linked to an active supervisor—demote the supervisor first, or unlink the sub-agent. See [Agent as tool](/flow/sdk/agents/agent-as-tool) for details. ## Delete an agent This permanently removes an agent from the SeekrFlow platform. **Endpoint:** [`DELETE /v1/flow/agents/{agent_id}`](/flow/reference/delete_v1_flow_agents__agent_id__delete) ```python Python theme={null} del_response = client.agents.delete(agent.id) print(f"Agent deleted. Agent ID: {agent.id}") ``` Deleting a supervisor does not affect its sub-agents or their agent-as-tool wrappers. To delete a sub-agent, first unlink it from any supervisors and delete its associated [agent-as-tool](/flow/sdk/agents/agent-as-tool). # Custom tools Source: https://docs.seekr.com/flow/sdk/agents/custom-tools Developer-defined Python functions for specialized business logic. Custom tools are developer-defined Python functions that extend agent capabilities at runtime. Once created, a custom tool becomes part of the agent's available toolset. The agent autonomously determines when and how to invoke the tool based on its instructions, context, and user input. ## Common use cases Custom tools are most often used to: * Access internal knowledge stores — proprietary data sources or repositories unique to your business * Transform or enrich data — clean, format, or augment text, numerical, or structured data * Execute specialized business logic — operations tailored to specific organizational needs ## Quick start ### 1. Define your Python function Each custom tool must be implemented in its **own `.py` file**. The following example creates a simple tool that adds two integers: ```python Python theme={null} def add(a: int, b: int) -> int: """Add two numbers together. This function takes two integers and returns their sum. Use this function when you need to perform a simple addition operation on exactly two integer inputs. Args: a (int): First number. b (int): Second number. Returns: int: The total of a and b. """ return a + b ``` ### 2. Create the custom function ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() add_function = client.agents.custom_functions.create( file_path="relative-path-to/add.py" ) print(f"Function ID: {add_function.id}") ``` `file_path` accepts a relative or absolute path to the `.py` file containing your function. ### 3. Create a code interpreter tool with the custom function Custom functions run within the code interpreter. Create a code interpreter tool and include the function IDs in its configuration: ```python Python theme={null} from seekrai.types import CreateRunPython, RunPythonConfig code_tool = client.tools.create( CreateRunPython( name="addition_tool", description="Perform basic addition and return the answer.", config=RunPythonConfig( function_ids=[add_function.id] ) ) ) print(f"Tool created: {code_tool.id}") ``` ## Parameters | Parameter | Required | Description | | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `name` | Yes | A unique name for the tool. | | `description` | Yes | Description that helps the agent understand when to use this tool. | | `function_ids` | No | List of custom function IDs to include. Without this parameter, the tool functions as a standard code interpreter. | ### 4. Link to an agent ```python Python theme={null} from seekrai.types import CreateAgentRequest agent = client.agents.create( CreateAgentRequest( name="addition-agent", instructions="Agent that performs basic addition and returns the answer.", model_id="meta-llama/Llama-3.3-70B-Instruct", tool_ids=[code_tool.id] ) ) print(f"Agent ID: {agent.id}") ``` ### 5. Run the agent Run the agent as you would for any other tool configuration. For details, see [Create and manage agents](/flow/what-is-seekrflow). ## Docstring requirements Your function must contain a valid docstring in [Google-style format](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings). A Google-style docstring has four components: 1. **Short description**: A brief, one-line description of what the function does. 2. **Long description (optional)**: A more detailed explanation of the function's purpose, behavior, and when to use it. 3. **Args**: Documentation for each parameter, including the parameter name, type, and description. 4. **Returns**: Documentation of the return value, including its type and description. ## Manage custom functions ### Update a custom function ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() updated_function = client.agents.custom_functions.update( function_id=add_function.id, file_path="relative-path-to/add.py" ) ``` An agent that is currently `Active` must be demoted and re-promoted for the updated function to take effect: ```python Python expandable theme={null} import time from seekrai.types import AgentStatus # Demote the agent agent = client.agents.demote(agent.id) while True: agent = client.agents.retrieve(agent.id) if agent.status == AgentStatus.INACTIVE: break time.sleep(5) print(f"Agent demoted: {agent.id}") # Re-promote the agent agent = client.agents.promote(agent.id) while True: agent = client.agents.retrieve(agent.id) if agent.status == AgentStatus.ACTIVE: break time.sleep(5) print(f"Agent promoted: {agent.id}") ``` ### Delete a custom function ```python Python theme={null} result = client.agents.custom_functions.delete(function_id=add_function.id) if result.deleted: print("Custom function deleted successfully.") ``` ### List all custom functions ```python Python theme={null} functions = client.agents.custom_functions.list_functions( limit=20, order="desc", offset=0 ) for fn in functions: print(f"Function ID: {fn.id}, Description: {fn.description}") ``` All parameters are optional: | Parameter | Description | | --------- | ------------------------------------------------------------ | | `limit` | Maximum number of functions to return. | | `order` | Sort direction (`"asc"` or `"desc"`) based on creation time. | | `offset` | Number of records to skip before returning results. | ### Retrieve a custom function ```python Python theme={null} fn = client.agents.custom_functions.retrieve(function_id=add_function.id) print(f"ID: {fn.id}, Description: {fn.description}") ``` ## Best practices ### Write clear, purposeful docstrings The reasoning model relies heavily on function docstrings to determine when and how to invoke your custom tools. Well-crafted docstrings directly impact tool performance and reliability. * **Function description**: Include both a short and long description. The short description should describe when to invoke the function. The long description should specify the conditions or scenarios when the agent should use this tool versus other available options. * **Parameter documentation**: Provide clear, specific descriptions for each parameter that help the reasoning model map conversation context to each argument. Avoid generic descriptions like "input value" — instead use contextual descriptions like "user's email address from the conversation" or "the product ID mentioned in the request." * **Return value documentation**: Clearly describe what the function returns and how the agent should interpret or use the result in its response. **Effective docstring:** ```python Python theme={null} def get_user_order_history(user_email: str, days_back: int = 30) -> List[Dict]: """Retrieve a user's recent order history from the e-commerce database. Use this function when a user asks about their past orders, purchase history, or needs information about previous transactions. Only invoke when you have confirmed the user's email address. Args: user_email (str): The customer's email address as provided in the conversation days_back (int): Number of days to look back for orders (default: 30) Returns: List[Dict]: List of order dictionaries containing order_id, date, items, and total """ ``` **Ineffective docstring:** ```python Python theme={null} def get_user_order_history(user_email: str, days_back: int = 30) -> List[Dict]: """Gets orders. This function gets user orders from the database. Use it for orders. Args: user_email (str): Email days_back (int): Days Returns: List[Dict]: Orders """ ``` ### Test functions locally before deployment SeekrFlow does not validate Python syntax or runtime behavior when you create a custom function — it will be created successfully even if the code contains errors. However, when the agent attempts to invoke a faulty function during a conversation, it will fail. Before creating a custom function, always: * Verify the function runs without syntax errors * Test with representative input data * Handle expected edge cases (null values, empty strings, invalid inputs) ### Use external services for complex logic Custom tools support single function definitions only — helper functions and nested functions within the same file are not supported. For workflows requiring multiple functions or complex business logic, create an external service that your custom tool can call. ## Imports and package support SeekrFlow uses Pyodide to execute custom tools in a secure sandboxed environment. * **Natively supported packages**: Pyodide includes many popular Python packages out of the box. See the [complete list of pre-installed packages](https://pyodide.org/en/0.27.6/usage/packages-in-pyodide.html). * **External packages**: For packages not natively supported, Pyodide automatically attempts to install them at runtime using `micropip`. This works for pure Python packages — those that do not require compiled extensions or system-level dependencies. ### Package best practices * Use natively supported packages when possible for faster execution and guaranteed compatibility. * Verify pure Python compatibility for external packages — check that they have wheels available on PyPI and do not depend on C extensions. * Test thoroughly when using external packages, as installation failures will cause your custom tool to fail at runtime. * If a required package does not compile in Pyodide, create an external service that uses the package and call it from your custom tool via API. # File search Source: https://docs.seekr.com/flow/sdk/agents/filesearch-tool Retrieve relevant data from a vector database using semantic search. File search, sometimes referred to as agentic RAG, gives your agents access to your business documents within an agentic application. When invoked, the tool retrieves the most relevant document chunks to help your agent complete its task. ## When to use file search Anytime you have a use case where you want to leverage your business documentation to complete a task — summarize documents, answer questions based on company knowledge, or generate reports using internal data — configure a file search tool. ## Prerequisites File search requires a populated vector database. To create and populate one, see [Create and populate a vector database](/flow/sdk/data-engine/create-and-populate-a-vector-database). ## Create a file search tool ```python Python theme={null} from seekrai import SeekrFlow from seekrai.types import CreateFileSearch, FileSearchConfig client = SeekrFlow() file_search_tool = client.tools.create( CreateFileSearch( name="doc_search", description="Search through company documents, policies, procedures, and knowledge base articles.", config=FileSearchConfig( file_search_index="", top_k=5, score_threshold=0.7 ) ) ) print(f"Tool created: {file_search_tool.id}") ``` ## Parameters | Parameter | Required | Description | | ------------------- | -------- | ------------------------------------------------------------------ | | `name` | Yes | A unique name for the tool. | | `description` | Yes | Description that helps the agent understand when to use this tool. | | `file_search_index` | Yes | ID of your vector database containing the documents. | | `top_k` | No | Maximum number of chunks to return from the search. | | `score_threshold` | No | Minimum similarity score for a chunk to be included in results. | ## Link to an agent ```python Python theme={null} from seekrai.types import CreateAgentRequest agent = client.agents.create( CreateAgentRequest( name="DocBot", instructions="You are DocBot, an expert assistant that can search through company documents to answer questions. Always cite the specific documents you reference. Respond only with data returned from the file search tool.", model_id="meta-llama/Llama-3.3-70B-Instruct", tool_ids=[file_search_tool.id] ) ) print(f"Agent ID: {agent.id}") print(f"Agent status: {agent.status}") ``` ## Best practices ### Tool description * Write clear, concise descriptions that specify when the tool should be invoked — for example, "Use this tool to search internal company policies when a user asks about HR procedures." * Include example queries or scenarios to help the agent understand the tool's intended use. * Clearly define the scope and limitations of the tool — for example, "This tool only searches technical documentation, not customer support tickets." ### top\_k * **Higher values** increase the likelihood of including relevant results but may introduce more noise. Use for exploratory queries or when context is broad. * **Lower values** give more focused results but risk missing relevant information. Use for targeted tasks. * Common settings are between 3 and 10. ### score\_threshold * Use `score_threshold` to filter out weak or irrelevant matches, improving overall result quality. * Start with a moderate threshold (such as 0.5–0.7) and adjust based on observed retrieval quality. ## Source tracing When file search retrieves chunks during a run, the assistant message includes source tracing fields for each chunk alongside the retrieved text. | Field | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chunk_id` | Unique identifier for the retrieved chunk. Use it with the chunk endpoint to get the full provenance record, including `file_id` and exact Markdown location. | | `text` | The full text of the chunk as indexed. | | `page` | Page number in the source document (`null` for native Markdown and JSON). | | `lines` | Line range in the ingested Markdown. | | `section` | Heading hierarchy path from the document root to this chunk. | For the full retrieval workflow — from run response to original source file — see [Source tracing](/flow/sdk/explainability/source-tracing). # MCP connector Source: https://docs.seekr.com/flow/sdk/agents/mcp-connector Connect a remote MCP server to your agent so it can invoke external tools without a custom integration. With the MCP connector tool, agents can call tools hosted on external Model Context Protocol (MCP) servers. SeekrFlow handles authentication, token refresh, and outbound requests. ## When to use Use an MCP connector tool when you want to connect an agent to an external MCP server. ## Prerequisites * An MCP server URL * For OAuth servers without dynamic client registration: a `client_id` and `client_secret` from the provider ## Create an MCP connector tool SeekrFlow supports three authentication modes depending on your MCP server. An MCP connector tool connects to an entire MCP server. You cannot select individual tools from a server. ### Servers with dynamic client registration (DCR) If the MCP server supports DCR, provide the server URL. SeekrFlow registers itself as an OAuth client and initiates the authorization flow. ```python Python theme={null} from seekrai import SeekrFlow from seekrai.types import CreateMCPConnector, MCPConnectorConfig client = SeekrFlow() mcp_connector_tool = client.tools.create( CreateMCPConnector( name="my_mcp_tool", description="Access external data and actions via the Example MCP server.", config=MCPConnectorConfig( url="https://mcp.example.com" ) ) ) print(f"Tool ID: {mcp_connector_tool.id}") print(f"Status: {mcp_connector_tool.status}") print(f"Authorization URL: {mcp_connector_tool.config.AUTHORIZATION_URL}") ``` The tool is created with a status of `pending_authorization`. Open the `AUTHORIZATION_URL` from the response in a browser and complete the OAuth flow. Once authorized, the tool status changes to `active` and it can be linked to an agent. **Authorization window** You must complete the OAuth flow within one hour. If the window expires, the tool moves to `failed` status and cannot be recovered. Delete it and create a new one. ### Servers without dynamic client registration If your MCP server requires OAuth but does not support DCR, you'll need to register SeekrFlow as an OAuth client with the provider first. Use the SeekrFlow redirect URI provided in your account settings when configuring the OAuth client. Once you have a `client_id` and `client_secret` from the provider: ```python Python theme={null} mcp_connector_tool = client.tools.create( CreateMCPConnector( name="my_mcp_tool", description="Access external data and actions via the Example MCP server.", config=MCPConnectorConfig( url="https://mcp.example.com", client_id="your-client-id", client_secret="your-client-secret" ) ) ) print(f"Status: {mcp_connector_tool.status}") print(f"Authorization URL: {mcp_connector_tool.config.AUTHORIZATION_URL}") ``` Open the `AUTHORIZATION_URL` and complete the OAuth flow. The tool becomes `active` once authorized. ### Servers with no authentication For MCP servers that require no authentication, provide only the URL: ```python Python theme={null} mcp_connector_tool = client.tools.create( CreateMCPConnector( name="my_mcp_tool", description="Access the Example MCP server.", config=MCPConnectorConfig( url="https://mcp.example.com" ) ) ) print(f"Tool ID: {mcp_connector_tool.id}") print(f"Status: {mcp_connector_tool.status}") ``` The tool is created with `active` status immediately. ## Tool status | Status | Description | Can link to agent? | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------ | | `pending_authorization` | OAuth flow not yet completed. Expires after one hour. | No | | `active` | Authentication complete. Tool is ready to use. | Yes | | `failed` | Authorization timed out, or the tool failed at runtime (expired token, unreachable server, revoked access). | No | If a tool enters `failed` status, delete it and create a new one. ## Link to an agent ```python Python theme={null} from seekrai.types import CreateAgentRequest agent = client.agents.create( CreateAgentRequest( name="MyAgent", instructions="You are an expert assistant. Use the MCP tool to access external data when needed.", model_id="meta-llama/Llama-3.3-70B-Instruct", tool_ids=[mcp_connector_tool.id] ) ) print(f"Agent ID: {agent.id}") ``` Only `active` tools can be linked to an agent. ## Manage your tool You can update a tool's name and description at any time: ```python Python theme={null} from seekrai.types import UpdateMCPConnector updated_tool = client.tools.update( mcp_connector_tool.id, UpdateMCPConnector( name="updated_name", description="Updated description." ) ) ``` **Changing the MCP server URL or credentials** MCP connector tools cannot be duplicated. If you need to connect to a different server or change credentials, create a new MCP connector tool and update your agent's `tool_ids`. ## Best practices ### Tool description Write a description that tells the agent specifically when to invoke this tool and what kind of data or actions it provides. | Effective | Ineffective | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | "Use this tool to query live inventory data from the warehouse management system. Invoke it when the user asks about stock levels, item availability, or order fulfillment status." | "Use this tool to access the MCP server." | ### Handle tool failures If a tool moves to `failed` during production use (for example, due to a provider token expiry), the agent will still call it, the call will fail, and the run will continue. To avoid unexpected failures, monitor tool status regularly and recreate tools before they impact your agent. # Run an agent Source: https://docs.seekr.com/flow/sdk/agents/run-an-agent Use threads and messages to start runs and retrieve agent responses. Threads, messages, and runs work together to run your agent. A thread holds the conversation context, with messages capturing your input and the agent's responses as it calls tools. A run starts the agent on a thread. ## Create a thread **Endpoint:** [`POST /v1/threads`](/flow/reference/create_thread_endpoint_v1_threads_post) ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() thread = client.agents.threads.create() print("Thread created: ", thread.id) ``` ## Create a message **Endpoint:** [`POST /v1/threads/{thread_id}/messages`](/flow/reference/create_message_endpoint_v1_threads__thread_id__messages_post) ```python Python theme={null} message = client.agents.threads.create_message( thread_id=thread.id, role="user", content="Explain the concept of derivatives for my calculus class" ) print(f"Message created! ID: {message.id}, Content: {message.content}") ``` ## Start a run Once your thread has a message, start a run against it. SeekrFlow supports synchronous and streaming runs. ### Run synchronously In synchronous mode, the agent processes the request and returns the complete response when generation is finished. **Endpoint:** [`POST /v1/threads/{thread_id}/runs`](/flow/reference/run_agent_v1_threads__thread_id__runs_post) ```python Python theme={null} import time agent_id = "your_agent_id" thread_id = "your_thread_id" run = client.agents.runs.run( agent_id=agent_id, thread_id=thread_id, stream=False ) run_id = run.run_id print(f"✓ Run started → {run_id}") while True: run = client.agents.runs.retrieve(run_id, thread_id=thread_id) if run.status in ['completed']: break time.sleep(1) final_message = client.agents.threads.list_messages(thread_id)[0] print(final_message.content) ``` ### Run with streaming In streaming mode, the agent's response is sent back incrementally as it's generated, allowing your application to display results in real time. **Endpoint:** [`POST /v1/threads/{thread_id}/runs/stream`](/flow/reference/run_agent_stream_v1_threads__thread_id__runs_stream_post) ```python Python theme={null} agent_id = "your_agent_id" thread_id = "your_thread_id" # With stream=True, run() returns an AgentStreaming object stream = client.agents.runs.run( agent_id=agent_id, thread_id=thread_id, stream=True ) # pretty_print consumes the stream, displaying reasoning, tool calls, # and the final answer as they arrive stream.pretty_print() ``` To handle the streamed events yourself instead of printing them, iterate `stream.raw_events()`. Consume the stream only once, with either `pretty_print()` or `raw_events()`. ## Retrieve messages ### Retrieve a message **Endpoint:** [`GET /v1/threads/{thread_id}/messages/{message_id}`](/flow/reference/get_message_endpoint_v1_threads__thread_id__messages__message_id__get) ```python Python theme={null} message = client.agents.threads.retrieve_message( thread_id=thread.id, message_id=message.id ) print("Message retrieved!") print(f"Thread ID: {message.thread_id}, Message ID: {message.id}") ``` ### Retrieve all messages from a thread **Endpoint:** [`GET /v1/threads/{thread_id}/messages`](/flow/reference/list_messages_endpoint_v1_threads__thread_id__messages_get) ```python Python theme={null} thread_id = "your_thread_id" messages = client.agents.threads.list_messages(thread_id=thread_id) print(f"Messages in thread {thread_id}:") for message in messages: print(f"Message ID: {message.id}") print(f"Role: {message.role}") print(f"Content: {message.content}") print("-" * 10) ``` ## Manage threads ### List threads **Endpoint:** [`GET /v1/threads`](/flow/reference/list_threads_endpoint_v1_threads_get) ```python Python theme={null} threads = client.agents.threads.list(limit=20, order="desc") print("Available threads:") for thread in threads: print(f"ID: {thread.id}, Status: {thread.status}") if thread.agent_id is not None: print(f"Agent ID: {thread.agent_id}") ``` ### Retrieve a thread **Endpoint:** [`GET /v1/threads/{thread_id}`](/flow/reference/get_thread_endpoint_v1_threads__thread_id__get) ```python Python theme={null} thread = client.agents.threads.retrieve(thread_id=thread.id) print(f"Thread retrieved: ID={thread.id}, Status={thread.status}") ``` ### Delete a thread **Endpoint:** [`DELETE /v1/threads/{thread_id}`](/flow/reference/delete_thread_endpoint_v1_threads__thread_id__delete) ```python Python theme={null} deleted_status = client.agents.threads.delete(thread_id=thread.id) print(f"Thread {thread.id} deleted: {deleted_status}") ``` ## Manage messages ### Update a message **Endpoint:** [`PATCH /v1/threads/{thread_id}/messages/{message_id}`](/flow/reference/update_message_endpoint_v1_threads__thread_id__messages__message_id__patch) ```python Python theme={null} thread_id = "your_thread_id" message_id = "your_message_id" updated_message = client.agents.threads.update_message( thread_id=thread_id, message_id=message_id, content="What can you help me with?" ) print(f"Message updated in thread {thread_id}!") print(f"Message ID: {updated_message.id}") print(f"New Content: {updated_message.content}") ``` ### Delete a message **Endpoint:** [`DELETE /v1/threads/{thread_id}/messages/{message_id}`](/flow/reference/delete_message_endpoint_v1_threads__thread_id__messages__message_id__delete) ```python Python theme={null} thread_id = "your_thread_id" message_id = "your_message_id" deleted_status = client.agents.threads.delete_message( thread_id=thread_id, message_id=message_id ) print(f"Message {message_id} deleted from thread {thread_id}!") ``` ## Track file search sources When an agent uses file search, each retrieved chunk's source tracing fields are appended to the assistant message content: | Field | Description | | ---------- | ---------------------------------------------------------------------------------- | | `chunk_id` | Unique chunk ID — use this to call the chunk endpoint for full Markdown provenance | | `page` | Source document page number (`null` for native Markdown or JSON) | | `lines` | Line range in the ingested Markdown (e.g. `42-67`) | | `section` | Heading hierarchy path from document root to the chunk | Use `chunk_id` with `GET /v1/flow/vectordb/{database_id}/chunk/{chunk_id}` to retrieve the `file_id` and download the original source document. ## Understand data structures ### Thread ```python Python theme={null} class ThreadStatus(str, Enum): AVAILABLE = "available" LOCKED = "locked" class Thread(BaseModel): id: str object: str created_at: datetime status: ThreadStatus active_run_id: Optional[str] meta_data: dict[str, Any] ``` ### Message ```python Python theme={null} class ThreadMessage(BaseModel): id: str object: str = 'thread.message' created_at: datetime thread_id: str role: str # e.g., 'user', 'assistant' content: ThreadMessageContentType agent_id: Optional[str] run_id: Optional[str] meta_data: dict[str, Any] ``` # Use structured outputs Source: https://docs.seekr.com/flow/sdk/agents/structured-outputs Control the format of agent responses using Pydantic models or JSON schemas. Structured outputs use a Pydantic `BaseModel` or JSON schema to enforce a response format on your agent, giving you typed, integration-ready data without extra parsing or post-processing. Use them when agent responses feed directly into external systems like APIs or databases, or when extracting structured information from unstructured content like documents and emails. ## Define a schema with Pydantic Define a Pydantic model in the `response_format` parameter: **Endpoint:** [`POST /v1/threads/{thread_id}/runs`](/flow/reference/run_agent_v1_threads__thread_id__runs_post) ```python Python theme={null} from pydantic import BaseModel, Field from typing import List from seekrai import SeekrFlow class ProductReview(BaseModel): product_name: str = Field(description="The full product name as listed") pros: List[str] = Field(description="List of positive aspects, maximum 3 items") cons: List[str] = Field(description="List of negative aspects, maximum 3 items") recommended: bool = Field(description="Whether the reviewer recommends this product") # Use structured output with your agent result = client.agents.runs.run( agent_id="your-agent-id", thread_id=thread.id, response_format=ProductReview ) ``` ## Define nested Pydantic objects You can also define multiple levels of Pydantic classes: **Endpoint:** [`POST /v1/threads/{thread_id}/runs`](/flow/reference/run_agent_v1_threads__thread_id__runs_post) ```python Python expandable theme={null} from pydantic import BaseModel, Field from typing import List from seekrai import SeekrFlow # Define nested objects first class ReviewerInfo(BaseModel): name: str verified_purchase: bool review_date: str class ProductSpecs(BaseModel): brand: str model: str price: float category: str # Main object that includes nested objects class ProductReview(BaseModel): product_name: str = Field(description="The full product name as listed") specs: ProductSpecs = Field(description="Technical specifications of the product") reviewer: ReviewerInfo = Field(description="Information about the reviewer") pros: List[str] = Field(description="List of positive aspects, maximum 3 items") cons: List[str] = Field(description="List of negative aspects, maximum 3 items") recommended: bool = Field(description="Whether the reviewer recommends this product") # Use structured output with your agent result = client.agents.runs.run( agent_id="your-agent-id", thread_id=thread.id, response_format=ProductReview ) # Agent will return nested data matching this structure: # { # "product_name": "Wireless Headphones", # "specs": { # "brand": "Sony", # "model": "WH-1000XM4", # "price": 299.99, # "category": "Electronics" # }, # "reviewer": { # "name": "John Smith", # "verified_purchase": true, # "review_date": "2024-01-15" # }, # "pros": ["Great sound quality", "Long battery life"], # "cons": ["Expensive", "Heavy"], # "recommended": true # } ``` ## Handle validation errors When the agent cannot map its response to the defined schema, a validation error is returned. **Endpoint:** [`POST /v1/threads/{thread_id}/runs`](/flow/reference/run_agent_v1_threads__thread_id__runs_post) ```python Python theme={null} # Validation Error - 422 { "error": "Value Error", "feedVersion": "1.0.0", "message": "Value error, Response format JSON schema could not be validated: ", "requestUrl": "https://services-api.seekr.com/v1/agents/runs", "status": 422 } ``` If you receive a validation error, handle the error as shown: ```python Python expandable theme={null} from seekrai import SeekrFlow from pydantic import BaseModel, Field from typing import List class ProductReview(BaseModel): product_name: str specs: ProductSpecs # Nested object reviewer: ReviewerInfo # Nested object pros: List[str] cons: List[str] recommended: bool try: result = client.agents.runs.run( agent_id="your-agent-id", thread_id=thread.id, response_format=ProductReview ) print(result) except Exception as e: print("Structured output validation failed:", str(e)) ``` ## Improve schema accuracy When using structured outputs, we recommend the following: 1. **Keep schemas simple and focused.** Complex structures with excessive fields or deep nesting can reduce model accuracy. Limit nesting to one level deep. While multiple levels are supported, single-level nesting produces the most consistent results. 2. **Use clear field names.** Choose descriptive field names that help the model accurately map response content to your schema. For example, `customer_email` is clearer than `email`, and `total_price_usd` is clearer than `price`. 3. **Use few-shot prompting.** Include examples in your agent's instructions to guide accurate field mapping. Sample inputs and expected outputs help the model understand how to structure its response. 4. **Test your schemas thoroughly.** Validate your schemas against real queries and edge cases before deploying. Test with a range of input types to ensure consistent results. # Tools Source: https://docs.seekr.com/flow/sdk/agents/tools Create and manage tools in the tool library. Tools extend what agents can do. While models provide reasoning capabilities, tools allow agents to take actions—accessing external systems, querying knowledge stores, executing code, or performing web searches to accomplish tasks. The tool library lets you create and manage tools independently of agents, then link them to any agent by tool ID. ## Tool types | Type | SDK class | Description | | ----------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | [File search](/flow/sdk/agents/filesearch-tool) | `CreateFileSearch` | Semantic search and retrieval across vector databases | | [Web search](/flow/sdk/agents/websearch-tool) | `CreateWebSearch` | Real-time information retrieval from web sources | | [Custom tools](/flow/sdk/agents/custom-tools) | `CreateRunPython` | Python code execution for data analysis and computations, with optional developer-defined functions for specialized business logic | | [Agent as tool](/flow/sdk/agents/agent-as-tool) | `CreateAgentAsTool` | Delegate subtasks to another agent and return the result to the supervisor | | [MCP connector](/flow/sdk/agents/mcp-connector) | `CreateMCPConnector` | Connect to external MCP providers through a secure gateway | See the sub-pages for type-specific configuration and parameters. ## Create a tool Create a tool in the library using `client.tools.create()`: ```python Python theme={null} from seekrai import SeekrFlow from seekrai.types import CreateWebSearch client = SeekrFlow() tool = client.tools.create( CreateWebSearch( name="my_web_search", description="Search the web for information relevant to the user's query." ) ) print(f"Tool created: {tool.id}") ``` For tools that require configuration, include a config object: ```python Python theme={null} from seekrai.types import CreateFileSearch, FileSearchConfig tool = client.tools.create( CreateFileSearch( name="my_file_search", description="Search the knowledge base for relevant information.", config=FileSearchConfig( file_search_index="", top_k=10, score_threshold=0.5 ) ) ) ``` ## Retrieve a tool ```python Python theme={null} tool = client.tools.retrieve("") print(tool.name, tool.type) ``` ## List tools ```python Python theme={null} tools = client.tools.list() for tool in tools.data: print(f"{tool.name} ({tool.type}): {tool.id}") ``` ## Update a tool Use `client.tools.update()` to make partial changes to a tool. Provide only the fields you want to change. Omitted fields remain unchanged. **Endpoint:** [`PATCH /v1/flow/tools/{tool_id}`](/flow/reference/patch_tool_v1_flow_tools__tool_id__patch) ```python Python theme={null} from seekrai.types import UpdateWebSearch updated_tool = client.tools.update( tool_id="", request=UpdateWebSearch( description="Updated description for web search." ) ) ``` Tool updates propagate immediately to all agents using the tool. ## Preview a tool update Use `client.tools.update_diff()` to simulate an update without applying it. The response shows exactly what would change. **Endpoint:** [`PATCH /v1/flow/tools/{tool_id}/diff`](/flow/reference/diff_tool_changes_v1_flow_tools__tool_id__diff_patch) ```python Python theme={null} from seekrai.types import UpdateWebSearch diff = client.tools.update_diff( tool_id="", request=UpdateWebSearch( name="my_web_search_v2", description="Updated description for web search." ) ) print(diff) ``` The response includes the complete before and after tool state, and a `diff` object identifying each changed field: ```python Python theme={null} ToolDiffResponse( before=..., after=..., diff={ "name": { "before": "my_web_search", "after": "my_web_search_v2" }, "description": { "before": "Search the web for information.", "after": "Updated description for web search." } } ) ``` ## Duplicate a tool ```python Python theme={null} duplicate = client.tools.duplicate("", "my_duplicate_tool") ``` ## Delete a tool ```python Python theme={null} result = client.tools.delete("") print(result.message) ``` You cannot delete a tool that is linked to an active agent. Demote or delete the agent first. ## List linked agents Check which agents use a specific tool before updating or deleting it: ```python Python theme={null} agents = client.tools.list_agents("") for agent in agents: print(f"{agent.name} ({agent.status}): {agent.id}") ``` ## Link tools to an agent When creating or updating an agent, specify tool IDs in the `tool_ids` parameter: ```python Python theme={null} from seekrai.types import CreateAgentRequest agent = client.agents.create( CreateAgentRequest( name="my_agent", instructions="You are a helpful assistant.", model_id="meta-llama/Llama-3.3-70B-Instruct", tool_ids=["", ""] ) ) ``` For more on agent creation and management, see [Create and manage agents](/flow/sdk/agents/create-agents). # Web search Source: https://docs.seekr.com/flow/sdk/agents/websearch-tool Real-time information retrieval from web sources. The web search tool gives agents access to real-time web information, including current events, recent developments, and external references. ## Create a web search tool ```python Python theme={null} from seekrai import SeekrFlow from seekrai.types import CreateWebSearch client = SeekrFlow() web_search_tool = client.tools.create( CreateWebSearch( name="my_web_search", description="Search the web for current information, news, recent developments, and real-time data." ) ) print(f"Tool created: {web_search_tool.id}") ``` ## Parameters | Parameter | Required | Description | | ------------- | -------- | ------------------------------------------------------------------ | | `name` | Yes | A unique name for the tool. | | `description` | Yes | Description that helps the agent understand when to use this tool. | ## Link to an agent ```python Python theme={null} from seekrai.types import CreateAgentRequest agent = client.agents.create( CreateAgentRequest( name="WebSearchBot", instructions="You are an expert assistant with access to real-time web information. Use the web search tool for current events, recent developments, or information not in your training data.", model_id="meta-llama/Llama-3.3-70B-Instruct", tool_ids=[web_search_tool.id] ) ) print(f"Agent ID: {agent.id}") print(f"Agent status: {agent.status}") ``` ## Best practices ### Tool description A good description clearly states when the tool should be used, what type of content it should retrieve, and what scenarios it should avoid. **Effective description:** "Use this tool to search for real-time product pricing and availability on external e-commerce websites. Only invoke this tool when the user explicitly asks for current prices, stock information, or product comparisons that are not already covered in internal documents. Avoid using this tool for general product information, technical specifications, or reviews — use the file search tool instead if available." **Ineffective description:** "Use this when the user asks a question that you think would benefit from web search." # Data engine Source: https://docs.seekr.com/flow/sdk/data-engine SDK workflows for uploading files, running ingestion, and creating data jobs for fine-tuning and semantic search. The data engine transforms raw content into structured, AI-ready data. It manages the complete data lifecycle from file ingestion through preparation for training and retrieval workflows. Fine-tuning data workflows are built around **data jobs** — managed operations that bundle file ingestion, Markdown review, prompt configuration, and alignment generation into a single tracked unit. For a conceptual overview of the data engine and its capabilities, see [Data engine](/flow/components/data-engine). ## Data engine workflows Upload source documents (PDF, DOCX, PPT, Markdown) and convert them to Markdown via the ingestion API. Track ingestion progress through data job status, per-file records, and timeline events. Set up a vector database and run document ingestion to generate embeddings for semantic search and retrieval. Use a principle\_files data job to generate a QA pair dataset for instruction fine-tuning. Use context\_grounded\_files or context\_grounded\_vector\_db data jobs to generate training data grounded in an existing knowledge source. List, filter, update metadata, and cancel data jobs. # Use AWS Bedrock for ingestion and inference Source: https://docs.seekr.com/flow/sdk/data-engine/aws-bedrock Configure SeekrFlow to use AWS Bedrock for document ingestion and agent inference on self-hosted EKS deployments. **Self-hosted only** AWS Bedrock support is available for self-hosted SeekrFlow deployments on AWS/EKS. It is not available on SeekrFlow SaaS. For self-hosted EKS deployments, SeekrFlow can route document ingestion and agent inference through AWS Bedrock instead of SeekrFlow's built-in models. This lets you run agent inference, embedding generation, and document conversion on AWS. ## Prerequisites * AWS credentials with Bedrock Runtime permissions (`bedrock-runtime:InvokeModel`, `bedrock-runtime:Converse`) * Desired Titan embedding and Claude models enabled in the AWS Console for your region * EKS deployment (agent inference is EKS-only) ## Ingestion ### Bedrock embedding models When you create a vector database with a `bedrock:`-prefixed model name, SeekrFlow routes all embedding requests to AWS Bedrock instead of SeekrFlow's built-in models. The `bedrock:` prefix is stripped before making API calls to AWS. | Model ID | Dimensions | Languages | Notes | | --------------------------------------- | -------------- | --------- | ---------------------------------------------------------- | | `bedrock:amazon.titan-embed-text-v2:0` | 256, 512, 1024 | 100+ | Recommended. Best for RAG, document search, and reranking. | | `bedrock:amazon.titan-embed-text-v1` | 1536 | 25+ | Legacy. Text retrieval and semantic similarity. | | `bedrock:amazon.titan-embed-g1-text-02` | 1536 | 25+ | Legacy G1 model. | | `bedrock:amazon.titan-embed-image-v1` | 256, 384, 1024 | N/A | Multimodal (text + image) embeddings. | To create a vector database with a Bedrock embedding model: ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() vector_db = client.vector_database.create( model="bedrock:amazon.titan-embed-text-v2:0", name="my-bedrock-db", description="Vector database using Bedrock embeddings" ) ``` For a full walkthrough of vector database setup and file ingestion, see [Create and populate a vector database](/flow/sdk/data-engine/create-and-populate-a-vector-database). ### Bedrock vision PDF conversion In Bedrock mode, SeekrFlow supports two PDF conversion methods: | Method | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pymupdf` | Text-based extraction. Fast and lightweight. | | `bedrock-vision` | Vision-based extraction using a Bedrock Claude model. Renders each page as an image and extracts content using the model. Best for scanned documents and image-heavy PDFs. | Other conversion methods (bookmark, seekr-saas, smoldocling, etc.) are not available in Bedrock mode. To enable vision-based conversion, set the `BEDROCK_VISION_MODEL` environment variable. When set, the ingestion pipeline automatically restricts available conversion methods to `pymupdf` and `bedrock-vision`. ### Environment variables | Variable | Required | Default | Description | | ----------------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `AWS_ACCESS_KEY_ID` | Yes\* | None | AWS access key for Bedrock API access. | | `AWS_SECRET_ACCESS_KEY` | Yes\* | None | AWS secret key for Bedrock API access. | | `AWS_REGION` | No | `us-east-1` | AWS region for all Bedrock API calls. | | `BEDROCK_VISION_MODEL` | No | None | Bedrock vision model for PDF conversion. Must use the `bedrock:` prefix — for example, `bedrock:us.anthropic.claude-3-5-sonnet-20241022-v2:0`. | AWS credentials can also be provided via IAM roles, instance profiles, or any standard boto3 credential chain. ## Agent inference When Bedrock is configured, Claude 4.5 is available for all intra-agent inference. Bedrock models appear alongside other models in the agent model-selection UI and are configured via Helm at deploy time. **Current limitations** * Available for agents only. Model Chat is not supported. * Reasoning and speed optimization parameters are ignored. ## Combining ingestion and inference You can use Bedrock for ingestion, inference, or both, including fully Bedrock-backed RAG agents. # Choose a chunking method Source: https://docs.seekr.com/flow/sdk/data-engine/choose-chunking-method Segment ingested content with the markdown, semantic, or sliding window chunking methods, and attach per-chunk metadata. The `chunking_method` parameter on `create_ingestion_job` controls how SeekrFlow segments your content into chunks before embedding. Choose the method that best fits your documents. ## Markdown chunking (default) **Intelligent structure-aware chunking** that automatically detects logical content breaks: * Respects document structure and heading hierarchies * Keeps related content together (headings with their content) * Preserves tables with their headers * Groups small sections to optimize chunk sizes ## Semantic chunking Call with `chunking_method="semantic"` to enable meaning-aware segmentation. This method detects sentence boundaries, embeds paragraphs, and groups them by meaning using hierarchical clustering, rather than relying on document position: * Searches for topic shifts instead of raw heading boundaries to keep tightly related sentences together * Automatically merges short paragraphs or bullets when they express the same idea * Honors document structure when it provides strong signals but can span across headings if the semantics match * Applies `token_count` and `overlap_tokens` as safety caps, splitting only when a semantic chunk would exceed those limits **When to use it:** * Long narrative content (wikis, blogs, requirements) where sections do not follow strict Markdown hierarchy * Mixed-format documents where context spans multiple small headings or callouts No additional markup is required. Tune `token_count` and `overlap_tokens` to control chunk granularity. ## Sliding window chunking Call with `chunking_method="sliding"` to split content into fixed-size overlapping windows. This method has no structural awareness, which makes it fast and predictable. Use it for plain-text or homogeneous content that lacks clear document structure. To force chunk boundaries at specific points, insert `---DOCUMENT_BREAK---` markers in your Markdown: ```text Markdown theme={null} # Section 1 This content will be in one chunk... ---DOCUMENT_BREAK--- # Section 2 This content will be in a separate chunk... ---DOCUMENT_BREAK--- # Section 3 This starts another chunk... ``` Set `token_count` (for example, `1000`) and `overlap_tokens` (for example, `100`) in the same `create_ingestion_job` call to control chunk size and overlap. Document break markers apply only to sliding window chunking. With `markdown` or `semantic` chunking, they are ignored. If the content between two document break markers exceeds `token_count`, the sliding window splits it into multiple chunks. ### Add per-chunk metadata With sliding window chunking, you can attach different metadata to different chunks by embedding a metadata block inside a section. Place the block between `---CHUNK_META_START---` and `---CHUNK_META_END---`, with a single line of JSON in between. The block is scoped to the section it appears in and is removed from the text before indexing and never becomes part of the chunk content. ```text Markdown theme={null} # Introduction ---CHUNK_META_START--- {"author": "Jane Smith", "source": "chapter_1", "classification": "public", "year": 2024} ---CHUNK_META_END--- This is the first chunk of the document. ---DOCUMENT_BREAK--- # Conclusion This chunk has no metadata block and falls back to the job-level metadata from the ingestion request. ``` Per-chunk metadata follows the same rules as job-level metadata and behaves as follows: * It is supported only with sliding window chunking. Including these markers with any other chunking method is an error. * Only one metadata block is allowed per section. A second block in the same section is an error. * A section's block replaces the job-level metadata for that chunk. The two are not merged. * A section with no block inherits the job-level metadata from the ingestion request, or no metadata if the request supplied none. # Create context-grounded fine-tuning data Source: https://docs.seekr.com/flow/sdk/data-engine/context-grounded-fine-tuning-data Generate structured context data for RAG-enhanced fine-tuning using context_grounded_files or context_grounded_vector_db data jobs. SeekrFlow is deprecating context-grounded fine-tuning and will remove it on July 17, 2026. You can keep using it until then. For new projects, choose another [fine-tuning method](/flow/components/fine-tuning#fine-tuning-methods). Context-grounded data jobs ground model responses in an existing knowledge source. Two job types are available: * **`context_grounded_files`** — aligns against uploaded and ingested documents. Follows the same file preparation and ingestion steps as `principle_files`, but no system prompt is required. * **`context_grounded_vector_db`** — aligns against a pre-built SeekrFlow vector database. No file upload or ingestion is needed. Neither type requires a system prompt to start. Not sure which approach fits your use case? See [Fine-tuning](/flow/components/fine-tuning). ## context\_grounded\_files ### Step 1: Create the job **Endpoint:** [`POST /v1/flow/data-jobs`](/flow/reference/submit_data_job_v1_flow_data_jobs_post) ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() data_job = client.data_jobs.create( name="Customer support context grounding", instructions="Generate QA pairs grounded in the ingested support docs.", job_type="context_grounded_files", ) data_job_id = data_job.id print("Data job ID:", data_job_id) ``` ### Step 2: Upload and attach files Upload your source files using the [Files API](/flow/sdk/data-engine/file-ingestion), then attach them to the job. Ingestion runs automatically for non-Markdown files. Markdown files are alignment-ready immediately. **Endpoint:** [`POST /v1/flow/data-jobs/{id}/add-files`](/flow/reference/add_files_to_data_job_v1_flow_data_jobs__data_job_id__add_files_post) ```python Python theme={null} data_job = client.data_jobs.add_files( data_job_id, file_ids=[ "file-25e34f96-2130-11f0-9236-3e11346bffff", "file-efd0b334-2130-11f0-9236-3e11346bffff", ], method="accuracy-optimized", ) print("Status:", data_job.status) ``` Poll `GET /v1/flow/data-jobs/{id}` until `status` is `ready_to_start`. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion) for details on job states and error handling. ### Step 3: Start alignment No system prompt is required. Call `/start` once `status` is `ready_to_start`. **Endpoint:** [`POST /v1/flow/data-jobs/{id}/start`](/flow/reference/start_data_job_alignment_v1_flow_data_jobs__data_job_id__start_post) ```python Python theme={null} detail = client.data_jobs.start(data_job_id) print("Alignment job:", detail.alignment_job.id, detail.alignment_job.status) ``` **Prerequisites:** * `status` must be `ready_to_start` * At least one processed Markdown file attached (ingested or uploaded) ### Step 4: Monitor alignment ```python Python theme={null} detail = client.data_jobs.retrieve(data_job_id) print("Status:", detail.status) if detail.alignment_job: print("Alignment job:", detail.alignment_job.id, detail.alignment_job.status) if detail.alignment_job.status_message: print("Status detail:", detail.alignment_job.status_message) ``` `status_message` gives a human-readable description of the alignment job's current state, including the reason if the job fails. Once `status` shows `completed`, retrieve the output files using the endpoint in Step 5. ### Step 5: Retrieve output files **Endpoint:** [`GET /v1/flow/alignment/{job_id}/outputs`](/flow/reference/alignment_outputs_v1_flow_alignment__alignment_job_id__outputs_get) ```python Python theme={null} import os import requests alignment_job_id = detail.alignment_job.id headers = {"Authorization": os.environ["SEEKR_API_KEY"]} response = requests.get( f"https://flow.seekr.com/v1/flow/alignment/{alignment_job_id}/outputs", headers=headers, ) outputs = response.json() ``` The output file with `"purpose": "fine-tune"` (the `.parquet`) is the file ID to use when creating a fine-tuning job. ## context\_grounded\_vector\_db Use this job type when your knowledge source is already indexed in a SeekrFlow vector database. No file upload or ingestion is needed — attach the vector database ID and start. ### Step 1: Create the job and attach the vector database **Endpoints:** `POST /v1/flow/data-jobs` [Submit data job](/flow/reference/submit_data_job_v1_flow_data_jobs_post) · `PATCH /v1/flow/data-jobs/{id}` [Update data job](/flow/reference/patch_data_job_v1_flow_data_jobs__data_job_id__patch) Create the job and set `vector_database_id` before starting. No file upload or ingestion is needed. ```python Python theme={null} data_job = client.data_jobs.create( name="Customer support refresh", instructions="Generate QA pairs grounded in the existing vector store.", job_type="context_grounded_vector_db", ) data_job_id = data_job.id data_job = client.data_jobs.update( data_job_id, vector_database_id="9aab2ceb-7c7b-4c07-8ff4-5416dfad221a", ) print("Vector DB set:", data_job.vector_database_id) ``` ### Step 2: Start alignment **Endpoint:** [`POST /v1/flow/data-jobs/{id}/start`](/flow/reference/start_data_job_alignment_v1_flow_data_jobs__data_job_id__start_post) ```python Python theme={null} detail = client.data_jobs.start(data_job_id) print("Alignment job:", detail.alignment_job.id, detail.alignment_job.status) ``` **Prerequisites:** * `status` must be `ready_to_start` * `vector_database_id` must be set * No system prompt required ### Step 3: Monitor alignment ```python Python theme={null} detail = client.data_jobs.retrieve(data_job_id) print("Status:", detail.status) if detail.alignment_job: print("Alignment job:", detail.alignment_job.id) ``` Once `status` shows `completed`, retrieve the output files using the endpoint in Step 4. ### Step 4: Retrieve output files **Endpoint:** [`GET /v1/flow/alignment/{job_id}/outputs`](/flow/reference/alignment_outputs_v1_flow_alignment__alignment_job_id__outputs_get) ```python Python theme={null} import os import requests alignment_job_id = detail.alignment_job.id headers = {"Authorization": os.environ["SEEKR_API_KEY"]} response = requests.get( f"https://flow.seekr.com/v1/flow/alignment/{alignment_job_id}/outputs", headers=headers, ) outputs = response.json() ``` The output file with `"purpose": "fine-tune"` (the `.parquet`) is the file ID to use when creating a fine-tuning job. # Create and populate a vector database Source: https://docs.seekr.com/flow/sdk/data-engine/create-and-populate-a-vector-database Set up a vector database and ingest documents to generate embeddings for semantic search and retrieval. This guide covers setting up the vector database, processing your documents, creating embeddings, and monitoring ingestion jobs. A complete example is available following the step-by-step guide, along with guidance for managing your vector databases. ## Step 1: Set up a vector database Seekr's Vector Database SDK provides advanced semantic search capabilities by transforming text into vector embeddings, making it possible to perform semantic searches that focus on meaning and context. This approach provides a smarter and more intuitive way to retrieve documents compared to traditional keyword-based methods. First, choose an embedding model: **Supported embedding models** | Model | Dimensions | Max input tokens | Language support | Availability | | -------------------------------------------------------------------------- | ----------------- | ---------------- | ------------------------------------ | ---------------------------------------------------- | | **E5-Mistral-7B-Instruct**
`intfloat/e5-mistral-7b-instruct` | 4096 | 4096 | English (best); limited multilingual | All deployments | | **Titan Text Embeddings V2**
`bedrock:amazon.titan-embed-text-v2:0` | 256, 512, or 1024 | 8192 | 100+ languages | Self-hosted AWS/EKS only (recommended Bedrock model) | | **Titan Text Embeddings V1**
`bedrock:amazon.titan-embed-text-v1` | 1536 | 8192 | 25+ languages | Self-hosted AWS/EKS only (legacy) | | **Titan Text Embeddings G1**
`bedrock:amazon.titan-embed-g1-text-02` | 1536 | 8192 | 25+ languages | Self-hosted AWS/EKS only (legacy) | | **Titan Multimodal Embeddings**
`bedrock:amazon.titan-embed-image-v1` | 256, 384, or 1024 | 128 | Multimodal (text + image) | Self-hosted AWS/EKS only | Avoid inputs longer than a model's maximum input tokens. Bedrock embedding models are available for self-hosted AWS/EKS deployments only. See [Use AWS Bedrock for ingestion and inference](/flow/sdk/data-engine/aws-bedrock) for setup instructions. ### Create an empty vector database Create the vector database with your chosen model: ```python Python theme={null} from seekrai import SeekrFlow # Initialize the client. Omit api_key if your key is set as an environment variable. client = SeekrFlow(api_key="YOUR_KEY_HERE") # Create the vector database vector_db = client.vector_database.create( model="intfloat/e5-mistral-7b-instruct", name="QuickStart_DB", description="Quick start example database", ) database_id = vector_db.id print(f"Created database: {vector_db.name} (ID: {database_id})") ``` **Sample response:** ```text Output theme={null} Created database: QuickStart_DB (ID: b7123456789-09876-4567) ``` ## Step 2: Upload files Upload your source documents to get the `file_id`s for ingestion. Files can be up to 4GB each. For supported file types and file-preparation guidance, see [Prepare and ingest files](/flow/sdk/data-engine/file-ingestion). If you already have `file_id`s from a separate upload, skip this step and reuse them. ```python Python theme={null} # Upload a file # Replace with the path to your file. # On Windows, use a raw string to avoid backslash issues: r"C:\Users\username\Downloads\document.pdf" file_path = "/Users/username/Downloads/document.pdf" upload_response = client.files.upload(file_path, purpose="alignment") file_id = upload_response.id print(f"Uploaded file with ID: {file_id}") ``` To upload several files at once, or to list and delete uploaded files, see [Prepare and ingest files](/flow/sdk/data-engine/file-ingestion). ## Step 3: Start a vector database ingestion job Next, create a job to ingest documents into your vector database. This step converts the files and creates embeddings from them. Choose an ingestion method and a chunking method, set the chunk size, then start the job. ### Choose an ingestion method **Accuracy-optimized (default)** When you use `method="accuracy-optimized"` or omit the method parameter, the system prioritizes accuracy. Depending on what data is available in your PDF document (bookmarks, tables, text layers), the system combines multiple extraction techniques for best results. **Key features:** * Uses both OCR and direct text extraction, then blends them together * Employs LLM agents to correct and enhance document hierarchy * Applies advanced table detection algorithms for accurate table formatting Documents over 100 pages can take up to 30 minutes to process. **Speed-optimized** When you use `method="speed-optimized"`, the system balances quality with processing speed. It automatically selects faster methods based on document size while maintaining reasonable accuracy for smaller documents. **Key features:** * Small documents still use high-accuracy methods * Larger documents use speed optimized algorithms to meet time constraints Optimized to complete in approximately 3 minutes regardless of document size. Once ingestion is complete, you'll receive a Markdown file that you can use for fine-tuning. **Ingestion mode and the UI** When ingesting files through the SeekrFlow UI, speed-optimized mode is always used. The SDK lets you choose between speed-optimized and accuracy-optimized. ### Choose a chunking method Set `chunking_method` to control how SeekrFlow segments content into chunks. The default is `markdown`; `semantic` and `sliding` are also available. See [Choose a chunking method](/flow/sdk/data-engine/choose-chunking-method) for how each method works and how to attach per-chunk metadata. ### Set chunk size and overlap The `token_count` parameter specifies the target size of each chunk, ensuring each chunk is neither too large (risking truncation by model limits) nor too small (losing semantic coherence). **Best practices:** * Common ranges: For embedding and retrieval, 200–500 tokens per chunk is a widely used range, balancing context and efficiency. The example here uses a token count of 512. * Adjust for document type: If your documents are dense or have complex structure (e.g., legal, technical), consider slightly larger chunks; for conversational or highly variable content, smaller chunks may work better. The `overlap_tokens` parameter creates overlapping regions between adjacent chunks at chunk boundaries, reducing the risk of missing relevant information that spans two chunks. Adjust chunking parameters based on document characteristics: | Document type | Recommended `token_count` | Recommended `overlap_tokens` | | ----------------------- | ------------------------- | ---------------------------- | | Technical documentation | 384-512 | 50-75 | | Legal documents | 512-768 | 75-100 | | Conversational content | 256-384 | 25-50 | ### Create the ingestion job ```python Python theme={null} # Create the ingestion job ingestion_job = client.vector_database.create_ingestion_job( database_id=database_id, files=[file_id], method="accuracy-optimized", chunking_method="markdown", token_count=512, overlap_tokens=50, ) job_id = ingestion_job.id print(f"Created ingestion job: {job_id}") ``` **Sample response:** ```text Output theme={null} Created ingestion job: ij-d80bd45a-4bb5-4bac-bbf3-7e3345409bc8 ``` ### Attach metadata at ingestion To attach user-defined metadata to the chunks created by an ingestion job, include an optional `metadata` object in the request. The metadata is job-level: it is copied onto every chunk produced from every file in the job. You can later filter or edit it with the chunk metadata methods (see [Manage chunk metadata](/flow/sdk/data-engine/manage-chunk-metadata)). ```python Python theme={null} ingestion_job = client.vector_database.create_ingestion_job( database_id=database_id, files=[file_id], method="accuracy-optimized", chunking_method="markdown", token_count=512, overlap_tokens=50, metadata={ "year": 2024, "doc_type": "annual_report", "department": "finance", "is_confidential": True, }, ) ``` The metadata object must follow a few constraints (flat object, typed values, 20 keys maximum); see [Metadata rules](/flow/sdk/data-engine/manage-chunk-metadata#metadata-rules) for the full list. To set different metadata on different chunks within one job, use the per-chunk metadata blocks described under [Add per-chunk metadata](/flow/sdk/data-engine/choose-chunking-method#add-per-chunk-metadata). ## Step 4: Monitor ingestion status (optional) After starting an ingestion job, you can track job progress, view per-file statuses, and diagnose any failures. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion) for details on checking job states, interpreting `file_records`, and resolving errors. Once `status` shows `completed`, your vector database is ready to query. Every ingested chunk also captures provenance metadata (source page, line ranges, heading path) automatically. To trace query results back to their source, see [Source tracing](/flow/sdk/explainability/source-tracing). ## Complete example This example demonstrates the entire workflow for creating a vector database, adding files, and kicking off an ingestion job: ```python Python expandable theme={null} from seekrai import SeekrFlow import time import os client = SeekrFlow() # Step 1: Create vector database print("Creating vector database...") db_name = f"QuickStart_DB_{int(time.time())}" vector_db = client.vector_database.create( model="intfloat/e5-mistral-7b-instruct", name=db_name, description="Quick start example database" ) database_id = vector_db.id print(f"Created database: {vector_db.name} (ID: {database_id})") # Step 2: Upload file print("Uploading file...") file_path = "document.pdf" # Replace with your file path upload_response = client.files.upload(file_path, purpose="alignment") file_id = upload_response.id print(f"Uploaded file with ID: {file_id}") # Step 3: Begin vector database ingestion print("Creating ingestion job...") ingestion_job = client.vector_database.create_ingestion_job( database_id=database_id, files=[file_id], method="accuracy-optimized", token_count=512, overlap_tokens=50 ) job_id = ingestion_job.id print(f"Created ingestion job with ID: {job_id}") # Step 4: Monitor ingestion status # For per-file tracking and error diagnostics, see Monitor ingestion. print("Waiting for ingestion job to complete...") interval = 5 # Check every 5 seconds while True: job_status = client.vector_database.retrieve_ingestion_job(database_id, job_id) status = job_status.status print(f"Ingestion job status: {status}") if status == "completed": print(f"Vector database ready with ID: {database_id}") break elif status == "failed": error = getattr(job_status, "error_message", "Unknown error") print(f"Ingestion job failed: {error}") break time.sleep(interval) print("Setup complete!") ``` # Prepare and ingest files Source: https://docs.seekr.com/flow/sdk/data-engine/file-ingestion Upload multiple files simultaneously in their original formats and the AI-Ready Data Engine will automatically extract relevant data and structure them into a dataset that can be used for fine-tuning. Begin the data preparation process by gathering source documents for upload to the Data Engine. Aim to collect documents that are relevant to the domain, and that are structured in a clear and logical way, with headings and subheadings for readability. ## Step 1: Prepare your file for upload ### Supported file types * Markdown (`.md`) * Text (`.txt`) * PDF (`.pdf`) * Word Documents (`.docx`, `.doc`) * PowerPoint (`.ppt`, `.pptx`) ### Length requirements * Your file should have at least 4 cohesive sections, each detailed enough to form a meaningful “chunk.” * Although exact token counts are not mandatory, each chunk should contain enough substantive text to form meaningful document chunks. ### File formatting guidelines Before uploading, make sure your files are properly formatted by following these steps: **PDF and DOCX**: 1. Use clear headings and avoid images without context. 2. Ensure text content is structured logically for conversion. **Markdown**: 1. Use correct header hierarchy (`#H1, ##H2, ###H3,` etc.). 2. Aim for six heading levels or fewer (`######`). 3. There's a clear, logical flow of information throughout. 4. Avoid missing or empty headers and skipped levels. 5. Ensure all sections have meaningful content under them. Google Docs users can export files as Markdown, PDF, or DOCX. The Data Engine automatically corrects many formatting issues when it processes your files. Markdown files with headers deeper than six levels are accepted instead of rejected, and missing or malformed elements are repaired where possible. If a file can't be repaired, the job stops and reports the specific issue to fix before resubmitting. Once your files are in order, proceed to the next step. ## Step 2: Upload files Use SeekrFlow’s Files API to upload source documents. Documents can be in the following formats: * PDF * DOCX * DOC * Markdown * Text (.txt) * PowerPoint (.ppt, .pptx) The following examples show how to upload a single file or multiple files of varying types: ### Upload a single file Upload a single file, up to 4GB. **Endpoint:** [`PUT /v1/flow/files`](/flow/reference/file_upload_v1_flow_files_put) ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow(api_key="your-api-key") #Note: If your API key is stored as an environment variable, you can leave the parentheses empty, as shown below. # Upload a file upload_resp = client.files.upload("example.pdf", purpose="alignment") print(upload_resp.id) ``` #### Sample response ```curl cURL theme={null} Uploading file example.pdf: 100%|█| 21.6M/21.6M [00:21<00:00, 1.02MB file-25e34f96-2130-11f0-9236-3e11346bffff ``` ### Upload multiple files Upload multiple files up to 4GB each. The endpoint accepts an array of files as input, including large batches of 5,000 files or more in a single submission. Submission time stays constant regardless of batch size. File size limits differ between the API/SDK and [UI](https://apps.seekr.com/flow), which supports file uploads up to 10 files/100mb each. The following example uploads two files, one PDF and one DOCX, simultaneously: **Endpoint:** [`PUT /v1/flow/bulk_files`](/flow/reference/bulk_file_upload_v1_flow_bulk_files_put) ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() bulk_resp = client.files.bulk_upload( ["example1.pdf", "example2.pdf"], purpose="alignment" ) # Access and print the ID of each uploaded file for resp in bulk_resp: print(resp.id) ``` ### List and delete files Keep track of uploaded files and remove duplicates or erroneous uploads as needed. List all uploaded files: **Endpoint:** [`GET v1/flow/files`](/flow/reference/list_files_v1_flow_files_get) ```python Python theme={null} # List all files files_response = client.files.list() for file in files_response.data: print(f"ID: {file.id}, Filename: {file.filename}") ``` Delete a file from the system: **Endpoint:** [`DELETE v1/flow/files/{file_id}`](/flow/reference/delete_file_v1_flow_files__file_id__delete) ```python Python theme={null} # Delete a file client.files.delete(file_id) print(f"Successfully deleted file {file_id}") ``` ## Step 3: Start an ingestion job (for PDFs, DOCX, DOC, and PPT/PPTX only) **Endpoint:** [`POST /v1/flow/alignment/ingestion`](/flow/reference/ingest_files_v1_flow_alignment_ingestion_post) When using data jobs, ingestion is triggered automatically when you attach files via `POST /v1/flow/data-jobs/{id}/add-files` — you do not need to call this endpoint directly. See [Create instruction fine-tuning data](/flow/sdk/data-engine/standard-instruction-finetuning) for the complete data job workflow. If your original source was a PDF, DOCX, DOC, PPT, or PPTX, you must first convert it to Markdown. If you already have a Markdown file, skip this step. Do not ingest Markdown files. This will return an error. If your file has tables embedded, make sure there are no empty cells. Empty cells run the risk of shifting all of your content in your table over to fill in the empty cell. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow(api_key="your api key") ingestion = client.ingestion # Start ingestion on one or more uploaded file IDs response = ingestion.ingest( files=["file-25e34f96-2130-11f0-9236-3e11346bffff", "file-efd0b334-2130-11f0-9236-3e11346bffff"], method="accuracy-optimized" ) print("Ingestion Job ID:", response.id) ``` Once ingestion is complete, you’ll receive a Markdown file that you can use for fine-tuning. **Ingestion mode and the UI** When ingesting files through the SeekrFlow UI, speed-optimized mode is always used. The SDK lets you choose between speed-optimized and accuracy-optimized. ### Choose an ingestion method #### Accuracy-optimized (default) When you use `method="accuracy-optimized"` or omit the method parameter, the system prioritizes accuracy. Depending on what data is available in your PDF document (bookmarks, tables, text layers), the system combines multiple extraction techniques for best results. **Key features:** * Uses both OCR and direct text extraction, then blends them together * Employs LLM agents to correct and enhance document hierarchy * Applies advanced table detection algorithms for accurate table formatting Documents over 100 pages can take up to 30 minutes to process. #### Speed-optimized When you use `method="speed-optimized"`, the system balances quality with processing speed. It automatically selects faster methods based on document size while maintaining reasonable accuracy for smaller documents. **Key features:** * Small documents still use high-accuracy methods * Larger documents use speed optimized algorithms to meet time constraints Optimized to complete in approximately 3 minutes regardless of document size. Once ingestion is complete, you'll receive a Markdown file that you can use for fine-tuning. ## Step 4: Check ingestion status After starting ingestion, you can track job progress, view per-file statuses, and diagnose any failures. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion) for details on checking job states, interpreting `file_records`, and resolving errors. Once `status` shows `completed`, your output file(s) will be available for the next step. ## Step 5: Review and edit ingested file Before moving on to the next step, download the Markdown files created during ingestion to make sure all the information was transferred successfully. This is your opportunity to make any necessary edits in a Markdown editor, then re-upload your file for best results. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() retrieve_resp = client.files.retrieve_content("file-dc6f19d1-b55a-43a0-a38a-56f0e7bd8d8d") file_id = retrieve_resp.id print(f"Retrieve file with ID: {file_id}") ``` #### Markdown editing guidelines Check to make sure standard Markdown formatting conventions are being followed: * Clear hierarchy with appropriate heading levels (`#H1, ##H2, ###H3,` etc.) * Logical flow of information from beginning to end * Consistent formatting throughout the document * Clear separation between sections using headings and whitespace * Meaningful content below each header In addition, do a sweep for incorrect text or characters that may have been picked up during ingestion. For example: ```text Markdown theme={null} # California State Univ University, Monter , Monterey Bay [Digital Commons @ CSUMB](https://digitalcommons.csumb.edu/) ## Movie Music: Film Soundtracks or Film Soundtracks Thr acks Throughout Hist oughout History ``` This file has picked up some erroneous text during ingestion. It's best to remove these to ensure the highest-quality QA pairs for fine-tuning (though a few minor additions like `/`or extra line breaks likely won't affect quality). Once you're satisfied, save your file with a `.md` extension and upload it: ```python Python theme={null} upload_resp = client.files.upload("edited_example.md", purpose="alignment") file_id = upload_resp.id print(f"Uploaded file with ID: {file_id}") ``` ```curl cURL theme={null} Uploading file edited_example.md: 100%|███████████████████████████████████| 41.8k/41.8k [00:01<00:00, 35.3kB/s] Uploaded file with ID: file-9b9bf862-26cd-11f0-958d-52c2a8425a49 ``` Keep the new file ID for the next step. ## Step 6: In-context learning with Markdown (optional) Once you’ve reviewed and edited your ingested Markdown (Step 5), you can use it directly in your prompts without fine-tuning. This works well for simpler, single documents that fit within a context window — for example, an airline’s customer service plan. ### Example The following Markdown file was generated by the AI-Ready Data Engine from a PDF source. Its clearly structured sections make it a good candidate for in-context learning. ```text Markdown expandable theme={null} # American Airlines Customer Service Plan ## Our Commitment American Airlines and American Eagle are in business to provide safe, dependable and friendly air transportation. ## Accommodations for Unaccompanied Minors Children 5–14 years old may travel under our unaccompanied minor (UMNR) service on nonstop or same-plane flights. - Children 8–14 may travel on connecting flights via select airports (CLT, DFW, LAX, etc.). - Children 15–17 may optionally use UMNR service. - UMNR service is not available for codeshare or partner flights. ## Customers with Disabilities American maintains Special Assistance Coordinators (SACs) to arrange accommodations such as: - Pre-reserved seating - Boarding assistance - Wheelchair support - In-cabin storage of assistive devices ## Flight Delays and Cancellations For delays or cancellations: - Rebooking on the next available flight is provided at no cost. - Hotel and meal vouchers are issued if delays are caused by American and result in overnight stays. - In cases of diversions, we provide transportation and accommodations as needed. ## AAdvantage® Program Members earn miles for flights, credit card use, hotel stays, car rentals, and more. Miles can be redeemed for travel, upgrades, or donated. ``` Pass the file contents as context in your prompt: ```text Markdown theme={null} You are a helpful customer support agent. Use only the following context to answer the question. --- Context (american_airlines_customer_service.md) --- Question: "What assistance does American Airlines provide if a flight is diverted to another city?" ``` The model uses the Markdown structure to locate the relevant section and return an answer without any model retraining. ### When to use in-context learning * Best for simple, single documents that fit within a context window (typically 4k–16k tokens) * Reduces initial setup — no model training required * Becomes impractical for large document sets or policies with complex conditional logic * When you need to scale beyond a single document or require consistent precision, consider RAG or fine-tuning instead # Generate a metadata snapshot Source: https://docs.seekr.com/flow/sdk/data-engine/generate-metadata-snapshot Summarize the most common metadata keys and values across a vector database's chunks. A metadata snapshot is a compact summary of the user-defined metadata in a vector database. It captures the most common keys, the most frequent values for each key, and each key's inferred type, giving you a quick view of the metadata present across the database's chunks. A snapshot captures up to the 100 most common keys, with up to the 10 most common values per key, sampled from as many as 10,000 chunks. ## Prerequisites A populated vector database whose chunks carry user-defined metadata. To attach metadata during ingestion or edit it afterward, see [Manage chunk metadata](/flow/sdk/data-engine/manage-chunk-metadata). ## Generate a snapshot Use `generate_metadata_snapshot` to build or rebuild the snapshot for a vector database. The call samples the index, ranks the keys and values by frequency, and stores the result. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() result = client.vector_database.generate_metadata_snapshot( database_id="", ) print(f"Captured {result.keys_captured} keys at {result.created_at}") ``` Generating a snapshot replaces the previous one for that vector database rather than adding to it. **Returns:** | Field | Description | | -------------------- | -------------------------------------------------- | | `vector_database_id` | ID of the vector database the snapshot describes. | | `keys_captured` | Number of metadata keys captured in this snapshot. | | `created_at` | When the snapshot was generated. | ## Read a snapshot Use `get_metadata_snapshot` to retrieve the current snapshot, including each key's type and its top values. ```python Python theme={null} snapshot = client.vector_database.get_metadata_snapshot( database_id="", ) for key in snapshot.keys: print(key.key_name, key.value_type, key.top_values) ``` **Returns:** | Field | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `vector_database_id` | ID of the vector database. | | `created_at` | When the current snapshot was generated. | | `keys` | List of captured metadata keys. Each entry has `key_name`, a `value_type` of `string`, `number`, or `boolean`, and a `top_values` list. | ## Keep the snapshot current SeekrFlow regenerates the snapshot automatically after an ingestion job adds documents to the vector database, so newly introduced keys and values reach the agent without any manual action. Generate a snapshot manually whenever you want to refresh it on demand, such as after editing metadata in place with `update_metadata`. ## Limitations * A snapshot includes only the 100 most common keys, with the 10 most common values each. Metadata that appears rarely across the sampled chunks might not be represented. * Values are ranked by how often they occur in the sample, so their order reflects frequency, not business priority. # Manage chunk metadata Source: https://docs.seekr.com/flow/sdk/data-engine/manage-chunk-metadata Edit user-defined metadata on chunks and list or filter chunks by metadata. User-defined metadata lets you attach structured business fields (such as `year`, `doc_type`, `department`, or `is_confidential`) to the chunks in a vector database, then retrieve and update those fields after ingestion. You can attach metadata when you ingest files (see [Create and populate a vector database](/flow/sdk/data-engine/create-and-populate-a-vector-database)), then use the methods here to browse chunks, filter them by metadata, and edit metadata in place. ## Metadata rules The same rules apply wherever metadata is accepted (ingestion request, manual chunking blocks, and the edit method below): * Metadata is a flat JSON object. Nested objects and arrays of objects are not allowed. * Each value is a string, number, boolean, datetime, or `null`. A `null` value is treated as missing and dropped. * A metadata object has 20 or fewer keys. * Keys are non-empty strings, recommended to be 255 characters or fewer, and cannot start with `_` (reserved for system fields). A request that breaks these rules returns a `422` validation error describing the problem. ## List and filter chunks Use `list_chunks` to return a paginated list of chunks from a vector database. Filter by file, by specific chunk IDs, or by metadata fields. When you provide more than one filter, results must match all of them. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() result = client.vector_database.list_chunks( database_id="", metadata={"year": {"$gte": 2023}, "doc_type": "meeting_notes"}, limit=20, offset=0, ) print(f"{result.total} matching chunks") for chunk in result.data: print(chunk.chunk_id, chunk.metadata) ``` **Parameters:** | Parameter | Description | | ------------- | --------------------------------------------------- | | `database_id` | ID of the vector database. | | `file_id` | Optional. Return only chunks from this file. | | `chunk_ids` | Optional. Return only these chunk IDs. | | `metadata` | Optional. Filter by metadata key-value pairs. | | `limit` | Maximum results to return. Default 20, maximum 100. | | `offset` | Pagination offset. Default 0. | **Metadata filter operators:** Match a value exactly by giving it directly (`{"doc_type": "SOP"}`), or use an operator object for comparisons: | Operator | Meaning | | -------- | -------------------------------------------------------------------------- | | `$in` | Value is one of a list, for example `{"severity": {"$in": ["P0", "P1"]}}`. | | `$gt` | Greater than. | | `$gte` | Greater than or equal to. | | `$lt` | Less than. | | `$lte` | Less than or equal to. | Each chunk in the response includes its `chunk_id`, `file_id`, `text`, `metadata`, `hierarchy`, and `locations`. ## Edit chunk metadata Use `update_metadata` to overwrite the metadata on chunks in a vector database. Target the chunks with either `chunk_ids` or `file_ids`, but not both. Editing is scoped to the vector database, so updating a file's chunks here does not affect chunks of the same file in another vector database. ```python Python theme={null} # Update specific chunks client.vector_database.update_metadata( database_id="", chunk_ids=["chunk-1", "chunk-2"], metadata={"source": "manual_review", "category": "support_doc"}, ) # Update every chunk belonging to one or more files client.vector_database.update_metadata( database_id="", file_ids=["file-abc123"], metadata={"department": "finance", "year": 2024}, ) ``` This operation is destructive. The metadata object you provide replaces all existing metadata on each targeted chunk, so include any fields you want to keep. To find the chunks and current metadata to edit, list them first with `list_chunks`. ## Delete metadata Metadata is removed automatically when its chunks are deleted. Deleting a file from a vector database removes that file's chunks and their metadata. See [Create and populate a vector database](/flow/sdk/data-engine/create-and-populate-a-vector-database) for file deletion. # Manage data jobs Source: https://docs.seekr.com/flow/sdk/data-engine/manage-data-jobs List, filter, clone, update metadata, and cancel data jobs. Use the data jobs API to list and filter jobs, clone a job, update names and instructions, and cancel in-progress alignment runs. ## List data jobs **Endpoint:** [`GET /v1/flow/data-jobs`](/flow/reference/get_data_jobs_v1_flow_data_jobs_get) Returns a paginated list of all data jobs for the authenticated user. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() jobs = client.data_jobs.list() for job in jobs.data: print(job.id, job.name, job.status, job.created_at) ``` ### Filter and sort | Parameter | Type | Options | Default | | ------------ | ------ | ------------------------------------------------------------------------- | ------------ | | `job_type` | string | `principle_files`, `context_grounded_files`, `context_grounded_vector_db` | — | | `sort_by` | string | `name`, `created_at`, `job_type` | `created_at` | | `sort_order` | string | `asc`, `desc` | `desc` | | `limit` | int | 1–100 | 25 | | `offset` | int | ≥ 0 | 0 | ```python Python theme={null} # List only principle_files jobs, most recent first jobs = client.data_jobs.list( job_type="principle_files", sort_by="created_at", sort_order="desc", limit=10, ) for job in jobs.data: print(job.id, job.name, job.status) ``` ## Get job detail **Endpoint:** [`GET /v1/flow/data-jobs/{id}`](/flow/reference/get_data_job_v1_flow_data_jobs__data_job_id__get) Returns the full job detail including ingestion jobs, file records, timeline events, and alignment status. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion) for a field-by-field reference. ```python Python theme={null} detail = client.data_jobs.retrieve("dj-1234567890") print("Status:", detail.status) print("Files:", len(detail.files)) print("Ingestion jobs:", len(detail.ingestion_jobs)) ``` ## Clone a data job **Endpoint:** [`POST /v1/flow/data-jobs/{id}/clone`](/flow/reference/clone_data_job_v1_flow_data_jobs__data_job_id__clone_post) Create a new, editable data job pre-populated from an existing one. The clone copies the source job's configuration and starts as a fresh job that you can adjust before starting alignment. Give the clone a new `name`, or omit `name` to reuse the source job's name. ```python Python theme={null} clone = client.data_jobs.clone( "dj-1234567890", name="Customer support refresh v3", ) print("Cloned job ID:", clone.id) ``` Cloning returns the full job detail, the same shape as [Get job detail](#get-job-detail). ## Update job attributes **Endpoint:** [`PATCH /v1/flow/data-jobs/{id}`](/flow/reference/patch_data_job_v1_flow_data_jobs__data_job_id__patch) Update the job name, instructions, system prompt, or vector database ID without recreating the job. ```python Python theme={null} data_job = client.data_jobs.update( "dj-1234567890", name="Customer support refresh v2", instructions="Cover airline escalation policies in the generated dataset.", system_prompt="You are an airline support expert. Always cite the policy section.", ) print("Updated name:", data_job.name) ``` **Editable fields:** | Field | Notes | | -------------------- | --------------------------------------------------------------------------------------------- | | `name` | Keep under 255 characters. | | `instructions` | Natural-language instructions that guide alignment toward the intended task. | | `system_prompt` | Required for `principle_files` jobs before starting. Immediately overwrites the stored value. | | `vector_database_id` | Required for `context_grounded_vector_db` jobs before starting. | Once alignment starts, job inputs are locked. Attempting to update a running job returns `409 Conflict`. ## Cancel a job **Endpoint:** [`POST /v1/flow/data-jobs/{id}/cancel`](/flow/reference/cancel_data_job_v1_flow_data_jobs__data_job_id__cancel_post) Cancels the alignment run associated with the data job. Only applies when alignment is in `pending`, `queued`, or `running` state. ```python Python theme={null} client.data_jobs.cancel("dj-1234567890") print("Job cancelled.") ``` Attempting to cancel a job whose alignment is not in a cancellable state returns `304 Not Modified`. # Manage vector databases Source: https://docs.seekr.com/flow/sdk/data-engine/manage-vector-databases List, retrieve, and delete vector databases and their files with the SeekrFlow SDK. Use these operations to inspect and clean up your vector databases and their files. Each example assumes an initialized `client` and, where applicable, a `database_id` or `file_id`. ## List all vector databases ```python Python theme={null} databases = client.vector_database.list() for db in databases.data: print(f"ID: {db.id}, Name: {db.name}") ``` ## Get a specific vector database ```python Python theme={null} # Get vector database details db_details = client.vector_database.retrieve(database_id) print(f"Name: {db_details.name}") print(f"Last updated: {db_details.updated_at}") ``` ## Delete a vector database ```python Python theme={null} # Delete a vector database client.vector_database.delete(database_id) print(f"Successfully deleted database {database_id}") ``` ## List all files in a vector database ```python Python theme={null} # List files in vector database db_files = client.vector_database.list_files(database_id) for file in db_files.data: print(f"ID: {file.id}, Filename: {file.filename}") ``` ## Delete a file from a vector database ```python Python theme={null} # Delete a file from vector database client.vector_database.delete_file(database_id, file_id) print(f"Successfully deleted file {file_id} from {database_id}") ``` # Monitor ingestion Source: https://docs.seekr.com/flow/sdk/data-engine/monitor-ingestion Track ingestion progress, interpret per-file statuses, and resolve errors through the data job detail endpoint. Ingestion status is surfaced through the data job that triggered it. `GET /v1/flow/data-jobs/{id}` returns a canonical view of your job — including nested ingestion jobs, per-file records, timeline events, and the derived `status` that tells you whether you're ready to start alignment. ## Understand data job status While ingestion is in progress, the data job moves through these states: | Status | Description | | ----------------- | ------------------------------------------------------------------------------------------- | | `file_processing` | At least one ingestion job is queued or running. | | `needs_review` | Manual action required — failed ingestion records, missing files, or missing system prompt. | | `ready_to_start` | All ingestion completed successfully and prerequisites for alignment are met. | Once you call `/start`, the status mirrors the alignment job (`running`, `completed`, `failed`, etc.). ## Pre-generation validation Before a data job begins generating data, SeekrFlow validates the job and stops it early when it can't produce useful results. Stopping early avoids spending tokens on a job that wouldn't succeed. A job is stopped when: * The instructions are empty or contain only whitespace. * The instructions can't be interpreted as a data-generation task. * The uploaded documents don't match the instructions. * No content in the uploaded documents is relevant enough to the instructions. When a job stops for one of these reasons, its `status_message` names the specific cause and the adjustment to make. Review the message, revise the instructions or documents, and resubmit the job. SeekrFlow also sends an email when a job is stopped this way. The email includes the job ID, the source file, the reason the job stopped, and the steps to resubmit. ## Check job status List all data jobs: **Endpoint:** [`GET /v1/flow/data-jobs`](/flow/reference/get_data_jobs_v1_flow_data_jobs_get) ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() jobs = client.data_jobs.list() for job in jobs.data: print(job.id, job.status, job.created_at) ``` Retrieve a specific data job: **Endpoint:** [`GET /v1/flow/data-jobs/{id}`](/flow/reference/get_data_job_v1_flow_data_jobs__data_job_id__get) ```python Python theme={null} detail = client.data_jobs.retrieve("dj-1234567890") print("Job ID:", detail.id) print("Status:", detail.status) ``` **Sample response:** ```json JSON theme={null} { "id": "dj-1b75f4d5-5c9e-4d33-b164-a2393bc5ab6d", "name": "Customer support refresh", "instructions": "Train a support assistant to answer Q4 product questions.", "job_type": "principle_files", "status": "ready_to_start", "created_at": "2025-11-14T07:35:21.700005Z", "updated_at": "2025-11-14T07:37:52.464993Z", "ingestion_jobs": [...], "files": [...], "timeline": [...] } ``` ## Inspect ingestion jobs and file records The `ingestion_jobs` array contains one entry per ingestion run. Each entry includes a `records` array with independent status and timestamps for every file processed. ```python Python theme={null} detail = client.data_jobs.retrieve("dj-1234567890") for ingestion_job in detail.ingestion_jobs: print(f"Ingestion job: {ingestion_job.id} — {ingestion_job.status}") for record in ingestion_job.records: print(f" {record.filename}: {record.status}") if record.processing_at: print(f" Started: {record.processing_at}") if record.completed_at: print(f" Finished: {record.completed_at}") if record.status == "failed": print(f" Error: {record.error_message}") print(f" Fix: {record.suggested_fix}") ``` ### File record fields | Field | Description | | ---------------- | ----------------------------------------------------------------- | | `record_id` | Unique identifier for the file record | | `filename` | Source filename | | `status` | Per-file processing state | | `method` | Ingestion method used (`speed-optimized` or `accuracy-optimized`) | | `queue_position` | Position in queue when `status` is `queued` | | `error_message` | Plain-language description of what went wrong | | `suggested_fix` | Recommended action to resolve the error | | `created_at` | When the file record was created | | `processing_at` | When the file entered the `running` state | | `completed_at` | When the file entered the `completed` state | | `failed_at` | When the file entered the `failed` state | ### File list The `files` array in the data job detail provides a unified view of ingestion outputs and manually uploaded Markdown files: * Entries with a `record_id` came from ingestion and include per-file processing metadata. * Markdown uploads have `record_id: null` because they skip ingestion and are immediately alignment-ready. ## Read the timeline The `timeline` array contains ordered milestone events for the job lifecycle. ```json JSON expandable theme={null} [ { "timestamp": "2025-11-14T07:35:21.700005Z", "event_type": "Created", "message": "Data job created.", "metadata": {} }, { "timestamp": "2025-11-14T07:35:22.483459Z", "event_type": "File Processing Started", "message": "Started processing files.", "metadata": { "ingestion_job_id": "ij-a19a1923-1d18-4fc7-8365-96d12ea734ce", "status": "running", "record_count": 5 } }, { "timestamp": "2025-11-14T07:37:52.435803Z", "event_type": "File Processing Completed", "message": "Finished processing files.", "metadata": { "ingestion_job_id": "ij-a19a1923-1d18-4fc7-8365-96d12ea734ce", "status": "completed", "record_count": 5 } } ] ``` Events are pre-sorted by timestamp. ## Resolve ingestion failures When a file fails, its record includes `error_message` and `suggested_fix`. The data job remains in `needs_review` until every failed record is resolved — either fixed and retried, or removed. ```python Python theme={null} detail = client.data_jobs.retrieve("dj-1234567890") for ingestion_job in detail.ingestion_jobs: for record in ingestion_job.records: if record.status == "failed": print(f"File: {record.filename}") print(f"Error: {record.error_message}") print(f"Fix: {record.suggested_fix}") ``` To retry, re-upload the corrected file and attach it to the job again via `POST /v1/flow/data-jobs/{id}/add-files`. To skip the file, remove it via `POST /v1/flow/data-jobs/{id}/remove-files`. At least one viable file must remain before alignment can start. ## Troubleshoot common errors | Error | Suggested fix | | -------------------------------------------------------------------------- | --------------------------------------------------- | | The file appears to be empty. | Upload a file with content. | | The PDF may be corrupted, password-protected, or in an unsupported format. | Upload a valid, unprotected PDF. | | The PDF contains pages that exceed the maximum supported size. | Re-export the PDF with smaller page dimensions. | | The file was not found or is not owned by the current user. | Re-upload the file or verify the correct `file_id`. | | Service temporarily unavailable. | Retry the job after a brief wait. | | Internal processing failure. | If the issue persists, contact support. | ### Document processing issues | Issue | Possible cause | Solution | | ----------------------- | --------------------------- | ---------------------------------------------- | | Files fail to upload | File exceeds size limit | Split large files or compress them | | | Invalid file format | Ensure file extension matches actual format | | | Network timeout | Implement retry logic with exponential backoff | | Markdown parsing errors | Improper heading hierarchy | Fix heading structure (ensure proper nesting) | | | Unsupported Markdown syntax | Use standard Markdown formatting | | PDF extraction issues | Protected PDF | Remove password protection before uploading | ### File ingestion issues | Issue | Possible cause | Solution | | -------------------- | -------------------------- | ----------------------------------------- | | Slow ingestion | Complex document structure | Adjust chunking parameters | | | Resource constraints | Monitor system resources during ingestion | | Failed ingestion job | Malformed content | Check files for compatibility issues | | | Service timeout | Increase timeout settings | # Create instruction fine-tuning data Source: https://docs.seekr.com/flow/sdk/data-engine/standard-instruction-finetuning Generate a QA pair dataset for instruction fine-tuning using the principle_files data job workflow. This guide walks you through creating a `principle_files` data job, which generates a QA pair Parquet file you can use for instruction fine-tuning. The workflow bundles file upload, ingestion, prompt configuration, and alignment into a single managed job. **Before you start:** Upload your source files using the [Files API](/flow/sdk/data-engine/file-ingestion) and have your file IDs ready before Step 2. Not sure which approach fits your use case? See [Fine-tuning](/flow/components/fine-tuning). ## Step 1: Create a data job **Endpoint:** [`POST /v1/flow/data-jobs`](/flow/reference/submit_data_job_v1_flow_data_jobs_post) Create a job shell with `job_type` set to `principle_files`. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() data_job = client.data_jobs.create( name="Customer support refresh", instructions="Train a support assistant to answer Q4 product questions.", job_type="principle_files", ) data_job_id = data_job.id print("Data job ID:", data_job_id) ``` **Sample response:** ```json JSON theme={null} { "id": "dj-1b75f4d5-5c9e-4d33-b164-a2393bc5ab6d", "name": "Customer support refresh", "job_type": "principle_files", "status": "needs_setup" } ``` ## Step 2: Add files to the job **Endpoint:** [`POST /v1/flow/data-jobs/{id}/add-files`](/flow/reference/add_files_to_data_job_v1_flow_data_jobs__data_job_id__add_files_post) Attach uploaded file IDs to the job. Non-Markdown files (PDF, DOCX, PPT) trigger ingestion automatically. Markdown files are marked as alignment-ready immediately. ```python Python theme={null} data_job = client.data_jobs.add_files( data_job_id, file_ids=[ "file-25e34f96-2130-11f0-9236-3e11346bffff", "file-efd0b334-2130-11f0-9236-3e11346bffff", ], method="accuracy-optimized", ) print("Data job status:", data_job.status) ``` **Ingestion mode and the UI** When ingesting files through the SeekrFlow UI, speed-optimized mode is always used. The SDK lets you choose between speed-optimized and accuracy-optimized. ### Choose an ingestion method | Method | Approx. time (100+ pages) | Description | | ------------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------- | | `accuracy-optimized` (default) | \~30 min | Combines OCR and direct extraction, runs LLM hierarchy cleanup, and uses advanced table detection. | | `speed-optimized` | \~3 min | Faster extraction heuristics for large documents; smaller documents still use the richer pipeline. | ## Step 3: Monitor ingestion Poll `GET /v1/flow/data-jobs/{id}` until the job status is no longer `file_processing`. ```python Python theme={null} detail = client.data_jobs.retrieve(data_job_id) print("Status:", detail.status) for ingestion_job in detail.ingestion_jobs: for record in ingestion_job.records: print(f" {record.filename}: {record.status}") if record.status == "failed": print(f" Fix: {record.suggested_fix}") ``` | Status | Meaning | | ----------------- | --------------------------------------------------------------- | | `file_processing` | Ingestion still running — wait | | `needs_review` | One or more files failed — resolve `suggested_fix` in `records` | | `ready_to_start` | Ingestion complete and prerequisites met | If a file fails, fix the source, re-upload it, and attach it to the job again. To skip the file instead, remove it via `POST /v1/flow/data-jobs/{id}/remove-files`. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion) for a full reference on job states and error codes. ## Step 4: Review and edit ingested Markdown Download the generated Markdown files from the `files` array in the job detail and review for accuracy. Re-upload any corrected versions and remove the originals before starting alignment. ```python Python theme={null} retrieve_resp = client.files.retrieve_content("file-dc6f19d1-b55a-43a0-a38a-56f0e7bd8d8d") print(f"Retrieved file: {retrieve_resp.id}") ``` Once you've reviewed and edited, re-upload and attach the corrected file: ```python Python theme={null} upload_resp = client.files.upload("edited_example.md", purpose="alignment") print(f"Uploaded file with ID: {upload_resp.id}") ``` See [Prepare and ingest files](/flow/sdk/data-engine/file-ingestion) for Markdown editing guidelines and in-context learning considerations. ## Step 5: Set a system prompt A `system_prompt` is required for `principle_files` jobs before alignment can start. You can generate one from high-level instructions or write your own. ### Generate a prompt **Endpoint:** [`POST /v1/flow/data-jobs/gen_system_prompt`](/flow/reference/generate_system_prompt_v1_flow_data_jobs_gen_system_prompt_post) `gen_system_prompt` returns a suggested prompt but does not save it to the job. You must call `PATCH /v1/flow/data-jobs/{id}` to set it. ```python Python theme={null} result = client.data_jobs.generate_system_prompt( instructions="I want to train a chatbot to answer questions about horror movie tropes.", ) print(result.system_prompt) ``` ### Set the prompt on the job **Endpoint:** [`PATCH /v1/flow/data-jobs/{id}`](/flow/reference/patch_data_job_v1_flow_data_jobs__data_job_id__patch) ```python Python theme={null} data_job = client.data_jobs.update( data_job_id, system_prompt=result.system_prompt, ) print("Prompt set:", data_job.system_prompt) ``` You can also write your own prompt directly via the PATCH endpoint without calling `gen_system_prompt` first. Once alignment starts, the system prompt is locked. Make any changes before calling `/start`. ## Step 6: Start alignment **Endpoint:** [`POST /v1/flow/data-jobs/{id}/start`](/flow/reference/start_data_job_alignment_v1_flow_data_jobs__data_job_id__start_post) The `/start` endpoint enforces pre-flight validation before launching. Requirements for `principle_files`: * `status` must be `ready_to_start` * `system_prompt` must be set * At least one processed Markdown file must be attached ```python Python theme={null} detail = client.data_jobs.start(data_job_id) print("Alignment job:", detail.alignment_job.id, detail.alignment_job.status) ``` If prerequisites are not met, the endpoint returns `422 Unprocessable Entity` with a descriptive message. ## Step 7: Monitor alignment Poll `GET /v1/flow/data-jobs/{id}` to track progress. ```python Python theme={null} detail = client.data_jobs.retrieve(data_job_id) print("Status:", detail.status) if detail.alignment_job: print("Alignment job:", detail.alignment_job.id, detail.alignment_job.status) if detail.alignment_job.status_message: print("Status detail:", detail.alignment_job.status_message) print("Fine-tuning job IDs:", detail.fine_tuning_job_ids) ``` `status_message` gives a human-readable description of the alignment job's current state, including the reason if the job fails. ## Step 8: Retrieve output files **Endpoint:** [`GET /v1/flow/alignment/{job_id}/outputs`](/flow/reference/alignment_outputs_v1_flow_alignment__alignment_job_id__outputs_get) Once `status` shows `completed`, use this endpoint to retrieve metadata for all input and output files associated with the alignment job. ```python Python theme={null} import os import requests alignment_job_id = detail.alignment_job.id headers = {"Authorization": os.environ["SEEKR_API_KEY"]} response = requests.get( f"https://flow.seekr.com/v1/flow/alignment/{alignment_job_id}/outputs", headers=headers, ) outputs = response.json() ``` ```json JSON expandable theme={null} [ { "id": "file-94ab4920-55e6-11f0-a791-96200332ab12", "filename": "freeway_facts_part_1.md", "type": "input", "purpose": "alignment", "bytes": 56826 }, { "id": "file-94d1a85e-55e6-11f0-a791-96200332ab12", "filename": "freeway_facts_part_2.md", "type": "input", "purpose": "alignment", "bytes": 1871 }, { "id": "file-94e397f8-55e6-11f0-a791-96200332ab12", "filename": "freeway_facts_part_3.md", "type": "input", "purpose": "alignment", "bytes": 5387 }, { "id": "file-f883ecfb-1353-4693-928f-0467b268b07b", "filename": "freeway_facts_part_1-20250630191733-raft-qa-pairs-messages.jsonl", "type": "output", "purpose": "alignment", "bytes": 0 }, { "id": "file-2d497c5c-55fa-4bbe-80a3-0b4eccda4d6f", "filename": "freeway_facts_part_1-20250630191733-raft-qa-pairs.parquet", "type": "output", "purpose": "fine-tune", "bytes": 324 } ] ``` The response includes both input and output files. The output file with `"purpose": "fine-tune"` (the `.parquet`) is the file ID to use when creating a fine-tuning job. # Deployments Source: https://docs.seekr.com/flow/sdk/deployments Create and manage model endpoints for real-time inference with the Python SDK. Deployments host a model on dedicated compute infrastructure and make it available for inference requests and agent usage. For conceptual background, see [Deployments](/flow/components/deployments). ## Create a deployment ### Base model ```python Python theme={null} from seekrai import SeekrFlow from seekrai.types.deployments import DeploymentType client = SeekrFlow() deployment = client.deployments.create( name="my-base-model-deployment", description="Base model deployment for inference.", model_type=DeploymentType.BASE_MODEL, model_id="meta-llama/Llama-3.3-70B-Instruct", n_instances=1 ) print(f"Deployment ID: {deployment.id}") print(f"Status: {deployment.status}") ``` ### Fine-tuned model ```python Python theme={null} deployment = client.deployments.create( name="my-fine-tuned-deployment", description="Fine-tuned model deployment for inference.", model_type=DeploymentType.FINE_TUNED_RUN, model_id="ft-1234567890", n_instances=1 ) print(f"Deployment ID: {deployment.id}") print(f"Status: {deployment.status}") ``` ## Parameters | Parameter | Required | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `name` | Yes | A name for the deployment. Must be 5–100 characters. | | `description` | Yes | A description of the deployment. Must be 5–1000 characters. | | `model_type` | Yes | `DeploymentType.BASE_MODEL` for a base model or `DeploymentType.FINE_TUNED_RUN` for a fine-tuned model. | | `model_id` | Yes | The model ID (base model name or fine-tuning job ID) to deploy. | | `n_instances` | Yes | Number of dedicated instances to provision. Must be between 1 and 50. | ## Deployment status | Status | Description | | ---------- | -------------------------------------------------------------- | | `Pending` | Deployment requested, infrastructure provisioning in progress. | | `Active` | Serving inference traffic. | | `Inactive` | Paused, not serving requests. | | `Failed` | Error during startup or runtime. | ## Promote a deployment Promote a deployment to make it active and ready to serve inference requests. ```python Python theme={null} deployment = client.deployments.promote(deployment.id) print(f"Status: {deployment.status}") ``` ## Demote a deployment Demote a deployment to pause it without deleting the endpoint. ```python Python theme={null} deployment = client.deployments.demote(deployment.id) print(f"Status: {deployment.status}") ``` ## List deployments ```python Python theme={null} deployments = client.deployments.list() for d in deployments.data: print(f"{d.name} ({d.status}): {d.id}") ``` ## Retrieve a deployment ```python Python theme={null} deployment = client.deployments.retrieve("") print(f"{deployment.name}: {deployment.status}") ``` # Explainability Source: https://docs.seekr.com/flow/sdk/explainability Trace model outputs back to the sources and training examples that influenced them. Explainability traces model responses back to their origins—whether retrieved context in an agentic workflow or training examples from fine-tuning. This allows you to see which inputs influenced specific outputs. The Explainability SDK provides two capabilities for understanding model outputs. For conceptual background on use cases and when to use each capability, see [Explainability](/flow/components/explainability). ## Explainability workflows Identify which retrieved sources influenced each statement in an agent's response. Works with any agent using file search, web search, or other tools. Identify which fine-tuning examples influenced a fine-tuned model's response. Trace retrieved chunks back to their exact location in the source document — file, page, and lines. # Attribute a response to its sources Source: https://docs.seekr.com/flow/sdk/explainability/context-attribution Context attribution identifies which sources influenced each statement in an agent's response and scores how strongly each one contributed. Run it from the SDK or REST API with the `explainability` methods. For how it works and the full list of source types, see [Context attribution](/flow/components/explainability/context-attribution). ## Attribute a response from an agent run Use this method to attribute a response from a completed SeekrFlow agent thread. The SDK extracts the context, query, and response from the thread automatically. **Endpoint:** [`POST /v1/explainability/context-attributor-from-run`](/flow/reference/get_context_attribution_from_run_v1_explainability_context_attributor_from_run_post) ```python Python theme={null} import os from seekrai import SeekrFlow client = SeekrFlow(api_key=os.environ["SEEKR_API_KEY"]) attribution = client.explainability.get_context_attribution_from_run( thread_id="", ) print(attribution) ``` To target a specific run rather than the latest, and to tune the analysis: ```python Python theme={null} attribution = client.explainability.get_context_attribution_from_run( thread_id="", run_id="", granularity="sentence", top_k=5, ) ``` ## Attribute raw context Use this method when you have the context, query, and response as text strings, for example when running attribution outside of SeekrFlow agents or in a custom pipeline. **Endpoint:** [`POST /v1/explainability/context-attributor`](/flow/reference/get_context_attribution_v1_explainability_context_attributor_post) ```python Python theme={null} attribution = client.explainability.get_context_attribution( context="France is a country in Western Europe with Paris as its capital. " "The Eiffel Tower is a wrought-iron lattice tower in Paris...", query="What is the capital of France and what is it known for?", response="Paris is the capital of France. It is known for the Eiffel Tower.", granularity="sentence", top_k=5, ) print(attribution) ``` ## Attribute a specific portion of a response Set `highlight` to focus attribution on one sentence or phrase instead of the whole response. When `highlight` is set, `segments` is empty and sources are returned in the top-level `sources` field: ```python Python theme={null} attribution = client.explainability.get_context_attribution_from_run( thread_id="", highlight="It is known for the Eiffel Tower.", ) for source in attribution.sources: print(source.attribution, source.text) ``` ## Reading the result Both methods return the same structure: the attributed `response_text`, a list of `segments` (one per sentence or chunk of the response), and the `sources` scored against each segment. Each source carries its `source_type`, the matched `text`, an `attribution` score, and its `offset` in the context. Tool-response sources add tool metadata (`tool_name`, `tool_call_id`, and a `tool` object whose fields vary by tool). For example, an `mcp_tool` object identifies an MCP tool call, including a sub-agent invoked as a tool, through its `tool_name`. For the source types you can encounter, see [Source types](/flow/components/explainability/context-attribution#source-types). A result looks like this, with each segment carrying the sources that influenced it. Here one statement is attributed to an MCP tool response and another to the agent's instructions: ```json JSON expandable theme={null} { "response_text": "Ticket OPS-482 is in progress. Always confirm status with the owner before closing.", "segments": [ { "segment_index": 0, "segment_text": "Ticket OPS-482 is in progress.", "char_offset": 0, "sources": [ { "source_type": "tool_response", "id": 0, "text": "{\"ticket_id\": \"OPS-482\", \"status\": \"In Progress\", \"owner\": \"Dana Ruiz\"}", "attribution": 0.89, "offset": 0, "tool_name": "get_ticket", "tool_call_id": "call_a1b2c3", "tool": { "type": "mcp_tool", "tool_name": "get_ticket", "tool_input": { "ticket_id": "OPS-482" } } } ] }, { "segment_index": 1, "segment_text": "Always confirm status with the owner before closing.", "char_offset": 31, "sources": [ { "source_type": "system_prompt", "id": 1, "text": "Always confirm ticket status with the owner before marking anything closed.", "attribution": 0.76, "offset": 142 } ] } ], "highlight": null } ``` ### Attribution scores Each source has an `attribution` value between -1 and 1. Positive values indicate the source supported the response, meaning removing it would have caused the output to change. Values near 0 indicate little influence. Negative values are uncommon and indicate the source may have had a conflicting effect on the output. ## Best practices * **Granularity:** Sentence-level gives the most interpretable results. When context is large and speed matters more than precision, use `"chunk"` with `get_context_attribution_from_run` or `"paragraph"` with `get_context_attribution`. * **top\_k:** Values of 3–5 work well for most use cases. Increase toward 10 when debugging multi-hop answers where many sources contribute. * **num\_ablations:** Leave unset in production. Override only when benchmarking or reproducing a specific result. * **Segments with no strong sources:** This indicates the model generated that content from prior knowledge rather than retrieved context. It is expected behavior, not an error. ## Common errors For the full list of status codes, see the API reference. The errors you are most likely to act on: * **404 Not found** – The thread or run ID does not exist. Check the IDs you provided. * **422 Unprocessable entity** – The thread has no assistant response, because generation is still in progress or the agent run failed. * **503 Service unavailable** – The request timed out. Retry, reduce context size, or use a coarser granularity. # Trace a response to source documents Source: https://docs.seekr.com/flow/sdk/explainability/source-tracing Trace model output back to the original source document using provenance metadata captured at ingestion. Source tracing lets you prove that any model or agent answer came directly from the exact files you uploaded. Every chunk retrieved from a vector database carries a traceable lineage that connects the model output to the retrieved chunk, its Markdown location, and the original uploaded file. This is designed to support auditability, compliance, and operational decision-making in environments where document-level proof of origin is required. ## How source tracing works When a file is ingested into a vector database, the pipeline captures provenance metadata for every chunk (line range, character offsets, heading hierarchy, and source page number) and stores it alongside the embedding. No additional configuration is required. ## Retrieve source tracing fields from a run After a run completes, list the thread's messages to access the assistant response. When the agent invoked the file search tool, each retrieved chunk carries its source tracing fields: `chunk_id` (use it to fetch full provenance), `page`, `lines`, and `section` (the heading hierarchy path from the document root). `page` is `null` for native Markdown and JSON. **Endpoint:** [`GET /v1/threads/{thread_id}/messages`](/flow/reference/list_messages_endpoint_v1_threads__thread_id__messages_get) ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() messages = client.agents.threads.list_messages(thread_id="") # The assistant response carries the retrieved chunks and their source tracing fields assistant = next(m for m in messages if m.role == "assistant") print(assistant.content) # each file search chunk includes chunk_id, page, lines, and section ``` ## Retrieve chunk provenance Use `chunk_id` with the chunk endpoint to retrieve the full provenance record, which includes the `file_id` of the original uploaded file, the chunk `text` as indexed, and a list of `locations`. **Endpoint:** [`GET /v1/flow/vectordb/{database_id}/chunk/{chunk_id}`](/flow/reference/get_vector_database_chunk_v1_flow_vectordb__database_id__chunk__chunk_id__get) Retrieve a chunk with the `seekrai` SDK using `retrieve_chunk`. The returned object exposes the same fields as the REST response, so you can read `file_id` and walk each location directly. Requires `seekrai` 0.20.0 or later. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() chunk = client.vector_database.retrieve_chunk( database_id="", chunk_id="", # from the file search result ) print(chunk.file_id) # original uploaded file print(chunk.text) # chunk text as indexed for location in chunk.locations: print(location["page_number"], location["hierarchy"]) ``` Use the `file_id` to download the original uploaded file and complete the chain of custody: ```python Python theme={null} client.files.retrieve_content(chunk.file_id, output="source-document.pdf") ``` ## Reading the result Each entry in a chunk's `locations` pins the answer to a precise place in the ingested Markdown: the line range and character offsets, the heading `hierarchy` from the document root to the chunk, and the `page_number` in the source document (1-indexed, and `null` for native Markdown and JSON). Combined with `file_id`, these fields let you open the original document and point to the exact passage an answer was drawn from. For the complete record, see the [chunk endpoint reference](/flow/reference/get_vector_database_chunk_v1_flow_vectordb__database_id__chunk__chunk_id__get). ## Supported file types | File type | `page_number` | `hierarchy` | `lines` | `char_start` / `char_end` | | --------- | ------------- | ----------- | ------- | ------------------------- | | PDF | ✓ | ✓ | ✓ | ✓ | | DOCX | ✓ | ✓ | ✓ | ✓ | | PPTX | ✓ | ✓ | ✓ | ✓ | | Markdown | — | ✓ | ✓ | ✓ | | JSON | — | ✓ | ✓ | ✓ | ## Complete workflow The full source tracing workflow follows this sequence: ```mermaid theme={null} flowchart TD A("Run the agent
POST /v1/threads/{thread_id}/runs") B("List messages
GET /v1/threads/{thread_id}/messages") C("Retrieve chunk provenance
GET /v1/flow/vectordb/{database_id}/chunk/{chunk_id}") D("Download source document
GET /v1/flow/files/{file_id}/content") A -->|"chunk_id, page, section"| B B -->|"file_id, Markdown location"| C C -->|"original file"| D ``` 1. Run the agent against a thread (**Endpoint:** [`POST /v1/threads/{thread_id}/runs`](/flow/reference/run_agent_v1_threads__thread_id__runs_post)), then wait for the run to complete. 2. List the thread's messages (**Endpoint:** [`GET /v1/threads/{thread_id}/messages`](/flow/reference/list_messages_endpoint_v1_threads__thread_id__messages_get)) to find the assistant response. Each retrieved chunk includes `chunk_id`, `page`, and `section`. 3. Call the chunk endpoint with `chunk_id` to get `file_id` and confirm the exact Markdown lines the answer was drawn from. 4. Use `file_id` with the file download endpoint (**Endpoint:** [`GET /v1/flow/files/{file_id}/content`](/flow/reference/file_download_content_v1_flow_files__file_id__content_get)) to retrieve the original uploaded file and complete the chain of custody. # Attribute a response to training data Source: https://docs.seekr.com/flow/sdk/explainability/training-data-attribution Training data attribution surfaces the training data that influenced fine-tuned model outputs. By tracing model responses back to specific question-answer pairs from the training dataset, it helps debug model behavior and audit responses. This method requires a fine-tuned model created with Seekr's [fine-tuning feature](/flow/sdk/fine-tuning). Only models built after September 22nd, 2025 are supported. ## Retrieve influential fine-tuning data **Endpoint:** [`GET /v1/flow/explain/models/{model_id}/influential-finetuning-data`](/flow/reference/get_influential_training_data_route_v1_flow_explain_models__model_id__influential_finetuning_data_get) ```python Python theme={null} import os from seekrai import SeekrFlow client = SeekrFlow(api_key=os.environ["SEEKR_API_KEY"]) model_id = "deployment-" influential_data = client.explainability.get_influential_finetuning_data( model_id=model_id, question="What is SeekrFlow?" ) print(influential_data) ``` If you already have a model response from a prior `chat.completions` call, provide it as `answer` to skip an extra generation: ```python Python theme={null} chat_response = client.chat.completions.create( model=model_id, messages=[{"role": "user", "content": "What is SeekrFlow?"}] ) influential_data = client.explainability.get_influential_finetuning_data( model_id=model_id, question="What is SeekrFlow?", answer=chat_response.choices[0].message.content, ) ``` ## Reading the result The response contains `results`, a list of influential question-answer pairs, along with the `answer` used (echoed back if you provided one, otherwise generated internally) and the schema `version`. Each result carries its `id`, the source `file_id` (use it to trace back and edit the training documents), the `messages` content in `Q: \nA: ` form, and an `influence_level` of `high`, `medium`, or `low`. Irrelevant pairs are filtered out and not returned. For the complete response schema, see the endpoint reference above. ## Best practices * **Interpreting influence levels:** `high` means the Q/A pair strongly shaped the response; `medium` means moderate impact; `low` means minimal contribution. Look for recurring `high` pairs to understand the training patterns driving a response. * **Unexpected results:** If unrelated pairs are surfacing with high influence, review and refine your fine-tuning dataset. * **Empty results:** The model may simply not have found training pairs relevant to the prompt. This is not an error. ## Common errors * **TypeError** – Raised by the SDK when a required parameter such as `question` is missing or invalid. * **404 Not found** – The provided `model_id` does not exist. For all status codes, see the [endpoint reference](/flow/reference/get_influential_training_data_route_v1_flow_explain_models__model_id__influential_finetuning_data_get). # Fine-tuning Source: https://docs.seekr.com/flow/sdk/fine-tuning Train models on your data with the SeekrFlow Python SDK. For conceptual background on fine-tuning methods, training requirements, and when to use each approach, see [Fine-tuning](/flow/components/fine-tuning). ## Fine-tuning workflows Set up projects, configure training and infrastructure, and launch a fine-tuning job. Train reasoning models with reward-based optimization using GRPO. Align model outputs with human preferences using DPO. Fine-tune vision-language models on image-text datasets. Apply low-rank adaptation to reduce training cost and memory usage. Promote models for inference, run chat completions, and manage deployments. # Create a fine-tuning job Source: https://docs.seekr.com/flow/sdk/fine-tuning/create-fine-tuning-job Launch and manage model fine-tuning jobs in SeekrFlow with step-by-step guidance for configuring training parameters, setting up infrastructure, and monitoring progress through event tracking and loss visualization. ## Start a fine-tuning job Here’s a comprehensive example of how to create a fine-tuning job for a Llama 3 8B Instruct model with specific training parameters. ### Before you start: prepare your training data How you prepare your training data depends on what you’re starting with: * **If you have raw documents** (PDFs, DOCX, Markdown): use the Data Engine to ingest and convert them into a training-ready dataset first. See \[doc:data-engine-sdk]. * **If you already have a prepared JSONL or Parquet file**: upload it directly in Step 3 below. To create a fine-tuning job, you’ll first create a project, to which you can associate a fine-tuning run. You can also retrieve project information and get a list of all of your projects: ### Step 1: Create a project ```python Python theme={null} import os from seekrai import SeekrFlow client = SeekrFlow() # Create a new project proj = client.projects.create(name="my_project", description="a bot that answers questions about film tropes") ``` ### Step 2: Retrieve project ID You can locate your specific project with its ID, which you'll need for creating your fine-tuning job, by listing all projects. Project ID is an integer and precedes the project name you set; e.g., `id=588, name='horrorbotv4'`. This is also where to find the rest of the information for your project, including creation and update timestamps, number of runs and number of deployments. **Endpoints:** `GET v1/flow/fine-tune` [List Fine-Tuning Jobs](/flow/reference/list_fine_tune_v1_flow_fine_tunes_get) `GET v1/flow/fine-tunes/{fine_tune_id}` [Retrieve Fine-Tuning Job](/flow/reference/get_fine_tune_v1_flow_fine_tunes__fine_tune_id__get) ```python Python theme={null} # List all projects client.projects.list() # Get project info client.projects.retrieve(proj.id) ``` Before you start a fine-tuning run, you'll need to upload your training file and retrieve its file ID. ### Step 3: Upload a training file **Endpoint:** [`PUT /v1/flow/files`](/flow/reference/file_upload_v1_flow_files_put) **Accepted formats:** JSONL and Parquet The required JSONL schema varies by `purpose`. See [Upload file](/flow/reference/file_upload_v1_flow_files_put) for the correct schema for each purpose value. **cURL example:** ```curl cURL theme={null} curl -X PUT https://flow.seekr.com/v1/flow/files \ -H "Authorization: " \ -F "files=@/path/to/training_data.jsonl" \ -F "purpose=fine-tune" ``` **SDK example:** ```python Python theme={null} response = client.files.upload("/path/to/training_data.jsonl", purpose="fine-tune") print(f"Uploaded file ID: {response.id}") ``` ### Step 4: Retrieve training file ID **Endpoint:** [`GET v1/flow/files`](/flow/reference/list_files_v1_flow_files_get) ```python Python theme={null} # List all files files_response = client.files.list() for file in files_response.data: print(f"ID: {file.id}, Filename: {file.filename}") ``` **Sample response:** ```curl cURL theme={null} ID: file-1234567890, Filename: example_converted_2025-04-24_17-25-58-20250424211627-qa-pairs.parquet ``` ### Step 5: Training configuration **Endpoint:** [`POST v1/flow/fine-tunes`](/flow/reference/fine_tune_v1_flow_fine_tune_post) Next, specify a `TrainingConfig` object and an `InfrastructureConfig` object. The `TrainingConfig` defines all parameters that affect the actual code of the training script, such as the base model to be fine-tuned, number of epochs, quantization, etc. The `InfrastructureConfig` defines the infrastructure for the fine-tuning job. Gaudi2 is available on SeekrFlow, with other compute options available for on-prem installations and AI appliances. This example uses 8 Gaudi2 instances, which triggers SeekrFlow to run on multi-card training mode: ```python Python expandable theme={null} from seekrai.types import TrainingConfig, InfrastructureConfig from seekrai import SeekrFlow import os base_url = "https://flow.seekr.com/v1/" client = SeekrFlow(base_url=base_url) proj = client.projects.create(name="helperbot", description="a bot answers questions about film tropes") training_config = TrainingConfig( training_files=['file-317b8ad2-21dd-11f0-9126-3a035e72fce7'], #find the file id of your parquet file by listing all files model="meta-llama/Meta-Llama-3-8B-Instruct", n_epochs=1, n_checkpoints=1, batch_size=4, learning_rate=1e-5, experiment_name="helperbot_v1", ) infrastructure_config = InfrastructureConfig( n_accel=8, accel_type="GAUDI2", ) ``` `batch_size` and `learning_rate` are optional. Omit them and SeekrFlow computes a default for each from the selected algorithm, model size, and dataset size. Set either value to override its default, as shown above. `n_epochs` is required. Omitting `batch_size` or `learning_rate` requires seekrai 0.31.0 or later. ### Step 6: Fine-tune a base model Now that you've created your configuration files, you're ready to fine-tune a model! **Endpoint:** [`POST v1/flow/fine-tune`](/flow/reference/fine_tune_v1_flow_fine_tune_post) ```python Python theme={null} fine_tune = client.fine_tuning.create( training_config=training_config, infrastructure_config=infrastructure_config, project_id = 123, ) ft_id = fine_tune.id #print status print(client.fine_tuning.retrieve(fine_tune.id).status) ``` **Sample response:** ```curl cURL theme={null} Uploading file-1234567890-qa-pairs.parquet: 100%|█| 85.8k/85.8k [00:00<00:00, 86.2kB/s] FinetuneJobStatus.STATUS_QUEUED ``` ## Tune model hyperparameters Hyperparameters are the configurable parts of a model's learning process, and tuning them allows you to tweak model performance for optimal results. Hyperparameters play a crucial role in the training process, impacting both performance and training efficiency. Here’s a guide to essential hyperparameters, organized by impact level and the logical order for tuning large text models. ### Learning rate This is the most critical hyperparameter, because it determines whether your model will converge properly. Tune this one first, since it forms the foundation of your optimization process. **Consider impact on convergence:** The learning rate controls how much the model’s weights are updated with respect to the loss gradient. A high learning rate can lead to rapid convergence but risks overshooting the optimal solution, while a low learning rate ensures stable convergence but may require more training epochs. **Start with a small value:** A common practice is to start with a small learning rate (e.g., 0.001) and adjust based on the training performance. ### Batch size Next in the tuning sequence, batch size directly interacts with learning rate: the effective learning rate is often considered learning rate × batch size, e.g., if you increase batch size from 32 to 64, you might try increasing learning rate by approximately 2× to maintain similar training dynamics. **Note:** This relationship isn't perfectly linear in practice; at very large batch sizes, more increases in learning rate can lead to instability. **Memory constraints:** Larger batch sizes require more memory, but can lead to faster and more stable training due to more accurate gradient estimates. **Training speed:** Smaller batch sizes can lead to noisier updates, but may converge faster due to more frequent weight updates. **Experimentation:** Start with a moderate batch size (e.g., 32 or 64) and adjust based on memory availability and training speed. ### Epochs Number of epochs should be determined after you've established stable learning rate and batch size settings, because these parameters together will determine how quickly your model converges. **Overfitting:** More epochs allow the model to learn more from the data, but also increase the risk of overfitting (where the model learns the task *too* well, leading to poor generalization on unseen data). **Training time:** The number of epochs impacts the total training time. Ensure that the chosen number of epochs balances training time with model performance. ### Max length Max length defines context window capacity and affects the model's ability to understand and generate coherent text. It's a high-impact architectural decision that affects the model's fundamental capabilities, but is often constrained by hardware limitations. **Sequence length:** The maximum length of input sequences the model will handle. Longer sequences can capture more context but require more memory and computation. **Balance length:** Choose a length that balances capturing sufficient context with computational efficiency. **Task requirements:** Set these based on the typical length of the input data for your task. ## Monitor your fine-tuning run All job runs are tracked using SeekrFlow's event monitoring and tracking system. To retrieve the status and progress of a run, use this: **Endpoint:** [`GET v1/flow/fine-tunes/{fine_tune_id}`](/flow/reference/get_fine_tune_v1_flow_fine_tunes__fine_tune_id__get) ```python Python theme={null} print(client.fine_tuning.retrieve(fine_tune.id).status) ``` ### Plot training loss A training loss chart is automatically generated for you via our [UI](https://apps.seekr.com/flow): Just navigate to Projects and choose your project from the directory. ```python Python expandable theme={null} import matplotlib.pyplot as plt ft_id = fine_tune.id events = client.fine_tuning.retrieve(ft_id).events ft_response_events_sorted = sorted(events, key=lambda x: x.epoch) epochs = [event.epoch for event in ft_response_events_sorted] losses = [event.loss for event in ft_response_events_sorted] plt.figure(figsize=(8, 4)) plt.plot(epochs, losses, marker="o", linestyle="-", color="b") plt.xlabel("Epoch") plt.ylabel("Loss") plt.title("Training Loss Over Epochs") plt.grid(True) max_labels = 10 step = max(1, len(epochs) // max_labels) plt.xticks(epochs[::step], rotation=45) plt.tight_layout() plt.show() ``` ### How to interpret a training loss chart The training loss measures how closely predictions match actual values. A lower value and downward curve forming an elbow shape signal progress; watch out for a flat line or rising lines to indicate learning issues. **Loss:** The Y-axis represents training loss, which quantifies the difference between the model's predictions and the actual target values. A lower loss indicates better performance. **Epochs:** The upper X-axis shows epochs, where each epoch corresponds to one complete pass through the entire training dataset. **Steps:** The lower X-axis represents the training steps, calculated as: Total Steps = (Total Number of Samples ÷ number of instances \* Batch Size) × Number of Epochs **Decreasing loss curve:** Indicates that the model is learning and improving its predictions. **Plateauing loss curve:** The model may have reached its learning capacity with the current configuration. * Try adjusting hyperparameters (e.g., learning rate, batch size) and retrain to see if the model improves. **Increasing loss curve:** May indicate overfitting or issues with the training process. * Review data quality to ensure the training data is clean and representative of the problem space, and retrain with a higher-quality dataset. # Reinforcement tuning Source: https://docs.seekr.com/flow/sdk/fine-tuning/grpo-fine-tuning SeekrFlow supports reinforcement tuning using group relative policy optimization (GRPO). Reinforcement tuning trains a model to generate higher-quality outputs by scoring candidates against reference answers using one or more graders. To train a model with reinforcement tuning, follow the same process as standard fine-tuning with a few modifications. First, ensure your dataset has a `reference_answer` field containing the correct answer for each problem. Include a system prompt instructing the model to use the reasoning format: ```python Python theme={null} { "messages":[ { "role": "system", "content": "A conversation between User and Assistant. The user asks a question, and the Assistant solves it. The assistant first thinks about the reasoning process in the mind and then provides the user with the answer. The reasoning process and answer are enclosed within and tags, respectively, i.e., reasoning process here answer here " }, { "role": "user", "content": "Find the smallest positive $a$ such that $a$ is a multiple of $4$ and $a$ is a multiple of $14.$" } ], "reference_answer": "28" } ``` Upload this dataset with the purpose `reinforcement-fine-tune`. See [Upload file](/flow/reference/file_upload_v1_flow_files_put) for the full schema reference. Set `fine_tune_type` and define a reward function using `reward_components` in your `TrainingConfig`: ```python Python expandable theme={null} from seekrai import SeekrFlow from seekrai.types import TrainingConfig, InfrastructureConfig from seekrai.types.finetune import ( FineTuneType, Grader, GraderType, RewardComponents, StringOperation, TextSimilarityOperation ) client = SeekrFlow() training_config = TrainingConfig( training_files=[''], model="meta-llama/Llama-3.2-1B", n_epochs=1, n_checkpoints=1, batch_size=4, learning_rate=1e-6, # lower learning rate is typical for reinforcement tuning experiment_name="helperbot_grpo_v1", fine_tune_type=FineTuneType.REINFORCEMENT, reward_components=RewardComponents( graders=[Grader(type=GraderType.MATH_ACCURACY)] ) ) ``` Create the fine-tuning job using the standard workflow. See [Create a fine-tuning job](/flow/sdk/fine-tuning/create-fine-tuning-job) for the full process. LoRA can be used with reinforcement tuning to reduce memory requirements. See [LoRA](/flow/sdk/fine-tuning/lora) for configuration details. ## Reward functions A reward function defines how model outputs are scored during training. In SeekrFlow, reward functions are built from one or more **graders** — individual scoring operations that each evaluate a specific quality of the output. ### Grader types | Type | Enum value | Description | Operations | | -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | | Numerical accuracy | `GraderType.MATH_ACCURACY` | Returns `1` if the model output is numerically equal to the reference answer, else `0`. | None | | String check | `GraderType.STRING_CHECK` | Returns `1` if the model output matches the reference based on the selected operation. | `equals`, `not_equals`, `contains`, `case_insensitive_contains` | | Text similarity | `GraderType.TEXT_SIMILARITY` | Returns a similarity score between the model output and the reference answer. | `bleu`, `rouge` | | LLM (LLM-as-a-judge) | `GraderType.LLM` | Uses an LLM to score how closely the model output matches the reference answer in meaning and quality. | None | ### Create graders ```python Python theme={null} # Numerical accuracy — no operation needed math_grader = Grader(type=GraderType.MATH_ACCURACY) # String check — requires an operation keyword_grader = Grader( type=GraderType.STRING_CHECK, operation=StringOperation.CONTAINS ) # Text similarity — requires an operation similarity_grader = Grader( type=GraderType.TEXT_SIMILARITY, operation=TextSimilarityOperation.BLEU ) # LLM-as-a-judge — no operation; optional generation parameters judge_grader = Grader(type=GraderType.LLM) ``` ### LLM grader The LLM grader (LLM-as-a-judge) scores each candidate response with an LLM instead of a deterministic metric. The judge compares the model output to the `reference_answer` and rates how well it matches in meaning and quality. Use it for open-ended or subjective outputs, such as semantic correctness, helpfulness, or tone, where string check and text similarity are too rigid. The LLM grader takes no operation. It accepts optional generation parameters that control how the judge produces its scores: | Parameter | Type | Default | Description | | ----------------------- | -------------- | ------- | ----------------------------------------------------------------------------------------- | | `temperature` | float, 0.0–1.5 | `0.0` | Sampling temperature for the judge. Keep it near `0` for consistent, reproducible scores. | | `top_p` | float, 0.0–1.0 | None | Nucleus sampling cutoff for the judge. | | `seed` | integer ≥ 0 | None | Fixes the judge's sampling so scores are reproducible across runs. | | `max_completion_tokens` | integer ≥ 1 | `512` | Maximum number of tokens the judge can generate while scoring each response. | The judge runs on infrastructure managed by SeekrFlow, so you don't configure an inference endpoint or model for it. ```python Python theme={null} # LLM grader with custom generation parameters judge_grader = Grader( type=GraderType.LLM, temperature=0.0, max_completion_tokens=256, seed=42 ) ``` The LLM grader takes a `weight` and combines with other graders the same way, as shown next. ### Combine graders with weights Assign weight percentages to combine multiple graders into a single reward function. Weights must sum to `1.0`. If no weights are provided, graders are weighted equally. ```python Python theme={null} reward = RewardComponents( graders=[ Grader(type=GraderType.MATH_ACCURACY, weight=0.4), Grader(type=GraderType.STRING_CHECK, weight=0.3, operation=StringOperation.EQUALS), Grader(type=GraderType.LLM, weight=0.3, temperature=0.0) ] ) ``` ### Format reward weight By default, 10% of the reward score is based on whether the model uses the correct output format (`` and `` tags). You can adjust this with `format_reward_weight`: ```python Python theme={null} reward = RewardComponents( format_reward_weight=0.2, graders=[ Grader(type=GraderType.MATH_ACCURACY, weight=0.3), Grader(type=GraderType.TEXT_SIMILARITY, weight=0.5, operation=TextSimilarityOperation.BLEU) ] ) ``` When `format_reward_weight` is set explicitly, the sum of all weights (format + graders) must equal `1.0`. # Low-rank adaptation Source: https://docs.seekr.com/flow/sdk/fine-tuning/lora Apply low-rank adaptation to fine-tuning jobs with the SeekrFlow Python SDK. For conceptual background on LoRA, including when to use it and how it compares to full fine-tuning, see [Low-rank adaptation (LoRA)](/flow/components/fine-tuning/lora). ## Add LoRA to a fine-tuning job To use LoRA, set `lora_config` in your `TrainingConfig` using `LoRAConfig`. LoRA works with all fine-tuning methods: instruction, reinforcement, preference, and vision language tuning. ```python Python expandable theme={null} from seekrai import SeekrFlow from seekrai.types import TrainingConfig, InfrastructureConfig from seekrai.types.finetune import LoRAConfig client = SeekrFlow() training_config = TrainingConfig( training_files=[""], model="meta-llama/Meta-Llama-3-8B-Instruct", n_epochs=1, n_checkpoints=1, batch_size=4, learning_rate=1e-5, experiment_name="helperbot_lora_v1", lora_config=LoRAConfig( r=16, alpha=32, ), ) infrastructure_config = InfrastructureConfig( n_accel=8, accel_type="GAUDI2", ) fine_tune = client.fine_tuning.create( training_config=training_config, infrastructure_config=infrastructure_config, project_id=123, ) print(fine_tune.id) ``` ## LoRAConfig parameters | Parameter | Type | Default | Description | | --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- | | `r` | integer | `8` | Adapter rank. Controls adapter capacity and the complexity of patterns the adapter can learn. | | `alpha` | float | `32` | Scaling factor for adapter influence. Controls how strongly learned patterns affect base model behavior. | | `dropout` | float | `0.1` | Dropout probability applied to adapter layers during training. | | `bias` | string | `"none"` | Whether to train bias parameters. Accepted values: `"none"`, `"all"`, `"lora_only"`. | | `extras` | object | — | Optional dictionary for additional LoRA parameters. | For guidance on choosing rank and alpha values, see [Low-rank adaptation (LoRA)](/flow/components/fine-tuning/lora). See [Create a fine-tuning job](/flow/sdk/fine-tuning/create-fine-tuning-job) for the full workflow including project setup, file retrieval, and monitoring. # Preference tuning Source: https://docs.seekr.com/flow/sdk/fine-tuning/preference-tuning Fine-tune models on preference data using direct preference optimization (DPO) with the SeekrFlow Python SDK. For conceptual background on preference tuning, including when to use it and how it compares to other methods, see [Preference tuning (DPO)](/flow/components/fine-tuning/preference-tuning). ## Upload a preference dataset Preference datasets must follow a specific schema with a prompt, a chosen response, and a rejected response. SeekrFlow's data engine does not currently generate preference datasets — you must prepare them externally. ### Dataset schema Each record requires three fields: `messages` (the prompt context), `chosen` (the preferred response), and `rejected` (the dispreferred response). See [Upload file](/flow/reference/file_upload_v1_flow_files_put) for the full schema reference. ```json JSON expandable theme={null} { "messages": [ { "role": "system", "content": "You are an assistant helping a financial analyst understand investment risk." }, { "role": "user", "content": "Explain whether investing in a single startup is high or low risk." } ], "chosen": [ { "role": "assistant", "content": "Investing in a single startup is generally considered high risk..." } ], "rejected": [ { "role": "assistant", "content": "It depends on the startup..." } ] } ``` Upload with the `preference-fine-tune` file purpose. Datasets must be in JSONL or Parquet format. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() # Single file upload upload_resp = client.files.upload( "dpo-dataset.parquet", purpose="preference-fine-tune", ) # Bulk file upload bulk_resp = client.files.bulk_upload( ["dpo-dataset1.parquet", "dpo-dataset2.parquet"], purpose="preference-fine-tune", ) ``` SeekrFlow validates the schema on upload. Uploads fail if the file format is not JSONL or Parquet, or if the schema does not match the expected preference dataset structure. ## Create a preference tuning job Set `fine_tune_type` to `FineTuneType.PREFERENCE` in the training configuration. Preference tuning supports an optional `beta` parameter that controls the KL-divergence penalty — how far the tuned model can deviate from the base model. Values range from `0.0` to `1.0`, with `0.0` as the default. ```python Python expandable theme={null} from seekrai.types.finetune import FineTuneType from seekrai.types import TrainingConfig, InfrastructureConfig from seekrai import SeekrFlow client = SeekrFlow() training_config = TrainingConfig( training_files=[""], model="meta-llama/Llama-3.2-1B", n_epochs=1, n_checkpoints=1, batch_size=8, learning_rate=1e-5, experiment_name="dpo-fine-tune-job", fine_tune_type=FineTuneType.PREFERENCE, beta=0.5, ) infrastructure_config = InfrastructureConfig( accel_type="MI300X", n_accel=8, ) fine_tune = client.fine_tuning.create( training_config=training_config, infrastructure_config=infrastructure_config, project_id=123, ) print(fine_tune.id) ``` Preference tuning works with all base models in SeekrFlow. The remaining steps for monitoring, deployment, and inference are the same as other fine-tuning methods. See [Create a fine-tuning job](/flow/sdk/fine-tuning/create-fine-tuning-job) for the full workflow. # Deploy a fine-tuned model for inference Source: https://docs.seekr.com/flow/sdk/fine-tuning/promote-a-fine-tuned-model Launch and manage model fine-tuning jobs in SeekrFlow, with custom settings, event history, and inference. The FineTuning resource provides a synchronous interface for launching and managing model fine-tuning jobs in SeekrFlow. It supports custom training and infrastructure settings, job cancellation, event history, and inference with chat completions. ## Promote a model for inference After promoting your model to production with SeekrFlow, the next step is to use it for inference. This involves sending input data to the model and receiving predictions. Here’s a detailed guide on setting up and performing inference with your promoted model. ### List all fine-tuning jobs **Endpoint:** [`GET v1/flow/fine-tunes`](/flow/reference/list_fine_tune_v1_flow_fine_tunes_get) To get the job ID, list all model fine-tunes that were previously created. ```python Python theme={null} print(client.fine_tuning.list())# List all jobs ``` Find information including training files, training params, project ID, and description. ```curl cURL theme={null} FinetuneResponse(id='ft-1234567890', training_files=['file-0987654321'], model='meta-llama/Meta-Llama-3-8B-Instruct', accel_type=, n_accel=8, n_epochs=1, batch_size=1, learning_rate=1e-05, created_at=datetime.datetime(2025, 4, 25, 14, 29, 41, 817017, tzinfo=TzInfo(UTC)), experiment_name='12345-examplev1', status=, events=None, inference_available=False, project_id=679, completed_at=datetime.datetime(2025, 4, 25, 14, 52, 34, 785756, tzinfo=TzInfo(UTC)), description=None), ``` ### Retrieve specific fine-tuning job **Endpoint:** [`GET v1/flow/fine-tunes/{fine_tune_id}`](/flow/reference/get_fine_tune_v1_flow_fine_tunes__fine_tune_id__get) This provides the status and detailed information of a specific fine-tuning job, including logging events. ```python Python theme={null} print(client.fine_tuning.retrieve('ft-123456789')) # List specific job ``` ### Promote a model **Endpoint:** [`PUT v1/flow/deployments/{deployment_id}/promote`](/flow/reference/promote_v1_flow_deployments__deployment_id__promote_put) When you've found your job ID, promote it for inference: ```python Python expandable theme={null} from seekrai import SeekrFlow from seekrai.types.deployments import DeploymentType # Initialize the Seekr client with your API key client = SeekrFlow() deployments = client.deployments deployment = client.deployments.create( name="customer-support-model-deployment", # Free-form, must be 5–100 chars description="Serve LLM deployment for chat support", # 5–1000 chars model_type=DeploymentType.FINE_TUNED_RUN, # Use the "Fine-tuned Run" enum model_id="ft-1234567890", # Your fine-tune job ID goes here n_instances=1 # Number of dedicated replicas ) print("Deployment ID:", deployment.id) # Promote to production deployments.promote(deployment.id) # List deployments for d in deployments.list().data: print(d.id, d.status) # Retrieve a specific deployment details = deployments.retrieve(deployment.id) print(details.name, details.status) ``` **Sample response:** Use this deployment ID to run inference with chat completions. ```curl cURL theme={null} Deployment ID: deployment-1234567890 ``` ### Run inference on streaming chat completions Chat completions are a great way to test your model's task- or domain-specific performance, as well as gauge end-user experience. **Endpoint:** [`POST v1/inference/chat/completions`](/flow/reference/route_chat_completion_v1_inference_chat_completions_post) ```python Python expandable theme={null} stream = client.chat.completions.create( model=deployment.id, messages=[ {"role": "system", "content": "You are SeekrBot, a helpful AI assistant trained to answer questions about financial products and services."}, {"role": "user", "content": "Who are you?"} ], stream=True, max_tokens=1024, ) for chunk in stream: print(chunk.choices[0].delta.content or "", end="") stream = client.chat.completions.create( model="deployment-1234567890", # Deployment ID provided in the previous step messages=[ {"role": "system", "content": "You are SeekrBot, a helpful AI assistant trained to answer questions about financial products and services."}, {"role": "user", "content": "Discuss what goes into a good horror movie soundtrack."}, ], stream=True, max_tokens=1024, ) try: for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) except Exception as e: print(f"Error: {e}") ``` **Sample response:** ```curl cURL theme={null} I am SeekrBot, a knowledgeable guide to the realm of financial products and services. ``` For `model`, you can choose any of our base supported models or models that have been promoted for inference. ### Configure parameters in the request body This guide will help you understand what each parameter does and how to tweak them in the request body for best results. | Parameter | Description | How to Use | Example | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | The ID of the model to use for inference. | **Suitability:** Choose a model trained or fine-tuned for the specific task or domain.
**Check Availability:** Make sure the specified model ID is valid and available. | `meta-llama/Meta-Llama-3-8B` | | `messages` | The input messages that form the context for the model. | **Format:** A list of message objects organized by "role" and "content."
**Context:** Provide proper context to help the model generate relevant and coherent responses. | See below. | | `stream` | When set to `True`, the response is streamed back incrementally. | **Use for:** Applications needing real-time response updates.
**Latency:** May introduce slight latency, but with more immediate feedback. | `False`: Returns the response in one complete message.
`True`: Streams the response incrementally. | | `max_tokens` | The maximum number of tokens to generate in the response. | **Value:** Based on the desired length of the response - set appropriately. Zero value indicates no limit, but this can lead to very long responses (which may not be desired). | `50`: Limits the response to 50 tokens.
`0`: No limit, allowing the model to generate a response of any length. | | `temperature` | Controls the randomness of the model’s output. | **Range:** Typically between 0 and 1. Higher values (closer to 1) produce more random and creative responses, while lower values (closer to 0) make the output more focused and deterministic. | `0.7`: Balanced creativity and coherence.
`0.2`: More deterministic and focused responses. | | `frequency_penalty` | Adjusts the likelihood of repeating tokens that have already been used. | **Range:** 0-1. Higher values penalize repeated words, encouraging more diverse outputs. | `0`: No penalty.
`0.5`: Moderate penalty on repetition, useful for generating more varied responses. | | `n` | The number of completions to generate for each input prompt. | **Default value:** Typically set to 1 unless multiple responses are needed for comparison.
**Multiple completions:** Multiple completions are good for generating diverse responses, but increase computational cost. | `1`: Generates a single response.
`3`: Generates three different completions. | | `presence_penalty` | Adjusts the likelihood of introducing new topics or elements not present in the context. | **Range:** 0-1. Higher values encourage the model to bring in new topics or ideas, while lower values focus on the existing context. | `0`: No penalty, more conservative responses.
`0.6`: Encourages introducing new topics, useful for creative or exploratory conversations. | | `stop` | Specifies a sequence where the model will stop generating further tokens. | **Custom Stop Sequence:** Define custom sequences to control where the response should end.
**Multiple Stops:** Multiple stop sequences can be specified. | `"\\n\\n"`: Stops at a double newline, useful for ending paragraphs or sentences. | | `top_k` | Limits the next token prediction to the top K tokens with the highest probabilities. | **Use for:** Reducing the sampling space to make the model's output more predictable. Often used in combination with `top-p` to balance randomness and determinism. | `5`: Considers the top 5 tokens for each prediction step.
`50`: Considers the top 50 tokens, allowing for more variability. | | `top_p` | Nucleus sampling, where the model considers the smallest set of tokens whose cumulative probability is >= to the `top-p` value. | **Range:** 0-1.
**Use for:** Achieving a dynamic cutoff based on cumulative probability, allowing for more flexibility compared to `top-k`. | `1`: Considers all tokens (equivalent to no nucleus sampling).
`0.9`: Considers tokens until their cumulative probability reaches 0.9. | | `user` | Identifier for the end-user making the request. | **Use for:** Tracking and personalization; security and privacy | `"user123"`: Identifier for a specific user session or account. | **Example: Input messages** ```json theme={null} "messages": [ {"role": "user", "content": "How do I reset my password?"}, {"role": "assistant", "content": "To reset your password, go to the account settings and click on 'Reset Password'."} ] ``` ### Return token log probabilities during inference You can also return the token log probabilities, or "logprobs". Logprobs reveal the model’s certainty for each generated token. Low-confidence predictions highlight gaps in training data. During staging, you can flag outputs with low confidence (e.g., logprobs ≪ 0) for manual review or retraining. Unusually high logprobs for irrelevant tokens can signal hallucinations. During staging, this can help refine prompts or adjust temperature settings. The code below follows the OpenAI convention for request formatting: * To return the logprobs of the generated tokens, set `logprobs=True`. * To additionally return the top *n* most likely tokens and their associated logprobs, set `top_logprobs=n`, where *n* > 0. ```python Python theme={null} client = SeekrFlow() stream = client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[{"role": "user", "content": "Tell me about New York."}], stream=True, logprobs=True, top_logprobs=5, # NOTE: Max number, m, depends on model deployment spec; n > m may throw validation error ) for chunk in stream: print(chunk.choices[0].delta.content or "", end="", flush=True) print(chunk.choices[0].logprobs) ``` ### Demote a model **Endpoint:** [`PUT v1/flow/deployments/{deployment_id}/demote`](/flow/reference/demote_v1_flow_deployments__deployment_id__demote_put) When you're done with your model, demote (i.e., unstage) it: ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() deployments = client.deployments # Specify the deployment ID to demote DEPLOYMENT_ID = "ft-12345-67890" # Demote the deployment updated_deployment = deployments.demote(DEPLOYMENT_ID) # Verify demotion status print(f"Deployment {DEPLOYMENT_ID} status: {updated_deployment.status}") print(f"Production status: {'Active' if updated_deployment.status == 'active' else 'Demoted'}") ``` With SeekrFlow, deploying to a staging environment means promoting a model for inference. However, before using the inference model in your production environment, focus on validation and verification of your model’s performance to ensure a smooth transition. ## Run validation checks Make sure your model is ready for production deployment by running comprehensive validation checks. ### Prepare representative validation data Start by curating diverse validation datasets that mirror real-world inputs, including edge cases and difficult examples your model will encounter in production. **Example:** For a customer service chatbot handling clothing returns, include: * Simple queries ("How do I return this shirt?") * Complex scenarios ("I received the wrong size in a different color than ordered") * Edge cases ("I started a return but the tracking shows it's still at my house") * Multi-intent queries ("I want to exchange this and add something to my order") ### Run comprehensive checks Next, evaluate prediction quality and system performance to ensure all production requirements are satisfied. ## Track critical metrics Statistics are a critical tool for making sure your AI is trustworthy. The following are some commonly-used statistical metrics used to evaluate a model's performance: ### Prediction quality metrics | Metric | Definition | When to Prioritize | | --------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Accuracy | Correct predictions ÷ total predictions | Clear-cut, factual tasks (e.g., classification); in contexts where incorrect outputs could lead to significant consequences (medical, legal, financial) | | Precision | True positives ÷ predicted positives | When false positives are the most significant concern (e.g., content moderation) | | Recall | True positives ÷ actual positives | When false negatives are the most significant concern (e.g., compliance monitoring) | | F1 Score | Harmonic mean of precision and recall | When balance between precision and recall is needed | In practice, there's often a trade-off between minimizing false positives and false negatives. The relative cost of each error type helps determine whether to prioritize precision or recall when optimizing a model. The F1 score is specifically designed to balance the concerns of both, by combining precision and recall into a single metric. Going back to the clothing returns chatbot, you might prioritize F1 score when the costs of incorrectly rejecting valid returns (customer dissatisfaction) and incorrectly accepting invalid returns (financial loss) are both significant concerns that need to be balanced. ### System performance metrics **Latency:** Response time per prediction **Throughput:** Prediction volume capacity (e.g., 1000 requests/second) ## Identify areas for improvement and iterate ### Conduct an error analysis Categorize and investigate patterns in incorrect predictions to identify underlying causes. ### Implement targeted improvements Apply insights from error analysis to refine the model through iterative improvements: * [Hyperparameter tuning](/flow/sdk/fine-tuning/create-fine-tuning-job) * Additional training data * Model architecture modifications # Vision language tuning Source: https://docs.seekr.com/flow/sdk/fine-tuning/vision-language-tuning Fine-tune vision-language models on image-text datasets using the SeekrFlow Python SDK. For conceptual background on vision language tuning, including supported models and when to use it, see [Vision language tuning](/flow/components/fine-tuning/vision-language-tuning). ## Prepare a vision language dataset Upload a dataset that follows the vision-language message schema. Each training example is a single-turn conversation where user messages contain both image and text content. ### Example dataset schema ```json JSON theme={null} { "messages": [ { "role": "user", "content": [ {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}, {"type": "text", "text": "What product is this?"} ] }, { "role": "assistant", "content": [ {"type": "text", "text": "This is the ACME Widget Pro X7, a second-generation industrial sensor unit. It features the distinctive blue housing and triple-port connector array."} ] } ] } ``` ### Dataset validation SeekrFlow validates the dataset on upload and rejects datasets with: * Malformed message content or missing required fields * Unsupported image formats * Schema violations against the expected multimodal structure ## Upload a vision language dataset Upload your dataset with `purpose=fine-tune`. See [Upload file](/flow/reference/file_upload_v1_flow_files_put) for the full schema reference. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow() response = client.files.upload("vlm-dataset.jsonl", purpose="fine-tune") print(f"Uploaded file ID: {response.id}") ``` ## Create a vision language fine-tuning job ```python Python expandable theme={null} from seekrai.types import TrainingConfig, InfrastructureConfig from seekrai import SeekrFlow client = SeekrFlow() training_config = TrainingConfig( training_files=[ "file-830e9be3-25tt-13y1-0298-3a035e73o90" # Vision-language dataset file ID ], model="meta-llama/Llama-3.2-11B-Vision-Instruct", n_epochs=1, n_checkpoints=1, batch_size=4, learning_rate=1e-5, experiment_name="vlm_helperbot_v1", ) infrastructure_config = InfrastructureConfig( n_accel=8, accel_type="MI300X", ) fine_tune = client.fine_tuning.create( training_config=training_config, infrastructure_config=infrastructure_config, project_id=123, ) print(fine_tune.id) ``` All other `TrainingConfig` parameters behave the same as in text-only instruction fine-tuning. See [Create a fine-tuning job](/flow/sdk/fine-tuning/create-fine-tuning-job) for the full workflow including project setup, file retrieval, and monitoring. # Getting started Source: https://docs.seekr.com/flow/sdk/getting-started Install the SDK, authenticate, and make your first API call. The [SeekrFlow Python SDK](https://pypi.org/project/seekrai/) provides programmatic access to the SeekrFlow platform, including inference, agents, fine-tuning, content moderation, explainability, and data preparation. The SDK supports Python 3.9+ with synchronous and asynchronous clients. For direct HTTP access without an SDK, see the [API Reference](/flow/reference/getting-started-with-your-api). ## Prerequisites * Python 3.9 or higher * A SeekrFlow account. See [Access SeekrFlow](/flow/app/access-seekrflow) for setup instructions. * A SeekrFlow API key, available in the [User Profile](https://apps.seekr.com/flow/user-profile#api-token) section of the dashboard. ## Installation ```bash Bash theme={null} pip install --upgrade seekrai ``` ## Authentication Set your API key as an environment variable: ```bash Linux / macOS theme={null} export SEEKR_API_KEY=your_api_key ``` ```bash Windows theme={null} set SEEKR_API_KEY=your_api_key ``` Verify the variable is set by running `echo $SEEKR_API_KEY` (or `echo %SEEKR_API_KEY%` on Windows). ## Choosing a team Resources in SeekrFlow belong to a team. If you don't select one, requests use your personal workspace. To work in a specific team, set the `SEEKR_TEAM_ID` environment variable or an `x-team-id` header on the client. See [Work with teams](/flow/sdk/teams) for details. ## Supported integrations SeekrFlow supports the native Python SDK and two third-party clients. All three provide access to the same inference engine. **SeekrFlow SDK** – Native Python client with full platform access, including agents, fine-tuning, data engine, and explainability. No additional packages required beyond `seekrai`. **OpenAI SDK** – OpenAI-compatible inference endpoint. Existing OpenAI-based applications can connect to SeekrFlow by changing the `base_url`. Install with: ```bash Bash theme={null} pip install openai ``` The OpenAI compatibility layer supports `model`, `messages`, `stream`, `temperature`, `logprobs`, `top_logprobs`, `max_tokens`, `stop`, `top_p`, `frequency_penalty`, `presence_penalty`, and `tools`. Parameters such as `tool_choice`, `parallel_tool_calls`, `n`, `logit_bias`, and `max_completion_tokens` are not supported. **LangChain** – The `ChatSeekrFlow` wrapper integrates SeekrFlow models into LangChain chains, prompts, and tools. Install with: ```bash Bash theme={null} pip install langchain langchain-community langchain-seekrflow ``` `ChatSeekrFlow` supports tool calling, structured output, JSON mode, streaming, and token usage tracking. Async APIs, image input, audio input, and video input are not currently supported. ## First API call ```python SeekrFlow SDK theme={null} import os from seekrai import SeekrFlow client = SeekrFlow(api_key=os.environ.get("SEEKR_API_KEY")) response = client.chat.completions.create( model="meta-llama/Llama-3.1-8B-Instruct", messages=[{"role": "user", "content": "What is SeekrFlow?"}], ) print(response.choices[0].message.content) ``` ```python OpenAI SDK theme={null} # Requires: pip install openai from openai import OpenAI client = OpenAI( base_url="https://flow.seekr.com/v1/inference", api_key="your_seekr_api_key", ) response = client.chat.completions.create( model="meta-llama/Llama-3.1-8B-Instruct", messages=[{"role": "user", "content": "What is SeekrFlow?"}], ) print(response.choices[0].message.content) ``` ```bash LangChain theme={null} # Requires: pip install seekrai langchain langchain-community langchain-seekrflow import os from seekrai import SeekrFlow from langchain_seekrflow import ChatSeekrFlow from langchain.schema import HumanMessage seekr_client = SeekrFlow(api_key=os.environ.get("SEEKR_API_KEY")) llm = ChatSeekrFlow( client=seekr_client, model_name="meta-llama/Llama-3.1-8B-Instruct", ) response = llm.invoke([HumanMessage(content="What is SeekrFlow?")]) print(response.content) ``` ## Asynchronous usage The SeekrFlow SDK includes an asynchronous client for non-blocking requests. ```python Python theme={null} import os, asyncio from seekrai import AsyncSeekrFlow client = AsyncSeekrFlow(api_key=os.environ.get("SEEKR_API_KEY")) async def main(): response = await client.chat.completions.create( model="meta-llama/Llama-3.1-8B-Instruct", messages=[{"role": "user", "content": "What is SeekrFlow?"}], ) print(response.choices[0].message.content) asyncio.run(main()) ``` ## What you can build Create agents, attach tools, manage threads, and run multi-turn conversations. Train models on your data with instruction fine-tuning, context-grounded fine-tuning, or reinforcement tuning. Classify content for safety and brand risk using Seekr ContentGuard and Meta Llama Guard. Ingest files, generate training datasets, and build vector databases for retrieval. Retrieve the fine-tuning data that influenced a model's response. # Integrations Source: https://docs.seekr.com/flow/sdk/integrations Use SeekrFlow with OpenAI SDK and LangChain SeekrFlow is compatible with popular AI frameworks, allowing you to use familiar tools and patterns. Tool calling and function definitions with the OpenAI Python SDK. Build chains and agents with the ChatSeekrFlow wrapper. # OpenAI Source: https://docs.seekr.com/flow/sdk/integrations/custom-functions This quickstart guide will help you get started using SeekrFlow via OpenAI. The Compatibility API allows developers to use SeekrFlow through OpenAI’s SDK. It makes it easy to switch existing OpenAI-based applications to use Seekr’s models while still maintaining the use of OpenAI SDK — no big refactors needed. ## Installation First, install the OpenAI SDK and import the package. Then, create a client and configure it with the Compatibility API base URL and your Seekr API key. ```python Python theme={null} import os import openai # Set the API key os.environ["OPENAI_API_KEY"] = "Your OpenAI API key here" # Create the OpenAI client and retrieve the API key. client = openai.OpenAI( base_url="https://flow.seekr.com/v1/inference", api_key=os.environ.get("SEEKR_API_KEY") ) ``` ### Basic chat completions Here’s a basic example using the Chat Completions API: ```python Python expandable theme={null} from openai import OpenAI client = OpenAI( base_url="https://flow.seekr.com/v1/inference", api_key="SEEKR_API_KEY", ) completion = client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B", messages=[ { "role": "user", "content": "Write a haiku about eating cake at the gym.", }, ], ) print(completion.choices[0].message) ``` ### Chat with streaming To stream the response, set the stream parameter to `True`. ```python Python expandable theme={null} from openai import OpenAI client = OpenAI( base_url="https://flow.seekr.com/v1/inference", api_key="SEEKR_API_KEY", ) stream = client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B", messages=[ { "role": "user", "content": "Write a haiku about eating cake at the gym.", }, ], stream=True, ) for chunk in stream: print(chunk.choices[0].delta.content or "", end="") ``` ### State management For state management, use the `messages` parameter to build the conversation history. You can include a system message via the developer role and the multiple chat turns between the user and assistant. ```python Python expandable theme={null} from openai import OpenAI client = OpenAI( base_url="https://flow.seekr.com/v1/inference", api_key="SEEKR_API_KEY", ) completion = client.chat.completions.create( messages=[ { "role": "user", "content": "Respond in the style of Russ Hanneman.", }, { "role": "user", "content": "What does ROI mean?", }, { "role": "assistant", "content": "Radio. On. Internet.", }, { "role": "user", "content": "How did you make your first billion?", }, ], model="meta-llama/Meta-Llama-3-8B", ) print(completion.choices[0].message) ``` ### Tool use (function calling) You can utilize the tool use feature by passing a list of tools to the tools parameter in the API call. This one creates a custom unit conversion tool that can be configured dynamically. ```python Python expandable theme={null} import os from openai import OpenAI client = OpenAI( base_url="https://flow.seekr.com/v1/inference", api_key=os.environ.get("OPENAI_API_KEY") ) # Send a request to the OpenAI API to leverage the specified Llama model as a unit conversion tool. response = client.chat.completions.create( model="meta-llama/Llama-3.1-8B-Instruct", stream=False, messages=[{ "role": "user", "content": "Convert from 5 kilometers to miles" }], max_tokens=100, tools=[{ "type": "function", "function": { "name": "convert_units", "description": "Convert between different units of measurement", "parameters": { "type": "object", "properties": { "value": {"type": "number"}, "from_unit": {"type": "string"}, "to_unit": {"type": "string"} }, "required": ["value", "from_unit", "to_unit"] } } }] ) ``` Next, register the function from JSON and run the unit conversion tool: ```python Python expandable theme={null} # Parse json and register def register_from_json(json_obj): code = f"def {json_obj['name']}({', '.join(json_obj['args'])}):\n{json_obj['docstring']}\n{json_obj['code']}" print(code) namespace = {} exec(code, namespace) return namespace[json_obj["name"]] # Execute our tool def execute_tool_call(resp): tool_call = resp.choices[0].message.tool_calls[0] func_name = tool_call.function.name args = tool_call.function.arguments func = globals().get(func_name) if not func: raise ValueError(f"Function {func_name} not found") if isinstance(args, str): import json args = json.loads(args) return func(**args) execute_tool_call(response) ``` ## Supported parameters The following is the list supported parameters in the Compatibility API, including those that are not explicitly demonstrated in the examples above: * model * messages * stream * temperature * logprobs * top\_logprobs * max\_tokens * stop * top\_p * frequency\_penalty * presence\_penalty ## Unsupported parameters The following parameters are not supported in the Compatibility API: * tool\_choice * store * reasoning\_effort * metadata * logit\_bias * max\_completion\_tokens * n * modalities * prediction * audio * service\_tier * stream\_options * parallel\_tool\_calls * user # LangChain Source: https://docs.seekr.com/flow/sdk/integrations/using-seekrflow-langchain This quickstart guide will help you get started using LangChain with SeekrFlow chat models. This guide provides a quick overview for getting started with Seekr [chat models](https://python.langchain.com/concepts/chat_models) via our LangChain integration. ## Introduction `ChatSeekrFlow` class wraps a chat model endpoint hosted on SeekrFlow, enabling seamless integration with LangChain applications. ### Integration Details | Class | Package | Local | Serializable | Package downloads | Package latest | | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----- | ------------ | ------------------------------ | ---------------------------- | | [ChatSeekrFlow](https://github.com/benfaircloth/langchain-seekrflow/blob/main/langchain_seekrflow/seekrflow.py) | [langchain-seekrflow](https://pypi.org/project/langchain-seekrflow/) | ❌ | beta | PyPI - Downloads | PyPI - Version | ### Model Features | [Tool calling](https://python.langchain.com/how_to/tool_calling/) | [Structured output](https://python.langchain.com/how_to/structured_output/) | JSON mode | [Image input](https://python.langchain.com/how_to/multimodal_inputs/) | Audio input | Video input | [Token-level streaming](https://python.langchain.com/how_to/chat_streaming/) | Native async | [Token usage](https://python.langchain.com/how_to/chat_token_usage_tracking/) | [Logprobs](https://python.langchain.com/how_to/logprobs/) | | ----------------------------------------------------------------- | --------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------- | ----------- | ----------- | ---------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------- | | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | **Supported Methods** `ChatSeekrFlow` supports all methods of `ChatModel`, **except async APIs**. **Endpoint Requirements** The serving endpoint `ChatSeekrFlow` wraps **must** have OpenAI-compatible chat input/output format. It can be used for: 1. **Fine-tuned Seekr models** 2. **Custom SeekrFlow models** 3. **RAG-enabled models using Seekr's retrieval system** For async usage, please refer to `AsyncChatSeekrFlow` (coming soon). ## Installation Ensure you have the necessary dependencies installed: ```bash Bash theme={null} pip install seekrai langchain langchain-community ``` You must also have an API key from Seekr to authenticate requests. ```python Python theme={null} # Standard library import getpass import os # Third-party from langchain.prompts import ChatPromptTemplate from langchain.schema import HumanMessage from langchain_core.runnables import RunnableSequence # OSS SeekrFlow integration from langchain_seekrflow import ChatSeekrFlow from seekrai import SeekrFlow ``` ## API Key Setup You'll need to set your API key as an environment variable to authenticate requests. Run the below cell. Or manually assign it before running queries: ```python Python theme={null} SEEKR_API_KEY = "your-api-key-here" ``` ```python Python theme={null} os.environ["SEEKR_API_KEY"] = getpass.getpass("Enter your Seekr API key:") ``` ## Instantiation ```python Python theme={null} os.environ["SEEKR_API_KEY"] seekr_client = SeekrFlow(api_key=SEEKR_API_KEY) llm = ChatSeekrFlow( client=seekr_client, model_name="meta-llama/Meta-Llama-3-8B-Instruct" ) ``` ## Invocation ```python Python theme={null} response = llm.invoke([HumanMessage(content="Hello, Seekr!")]) print(response.content) ``` Output: ``` Hello there! I'm Seekr, nice to meet you! What brings you here today? Do you have a question, or are you looking for some help with something? I'm all ears (or rather, all text)! ``` ## Chaining ```python Python theme={null} prompt = ChatPromptTemplate.from_template("Translate to French: {text}") chain: RunnableSequence = prompt | llm result = chain.invoke({"text": "Good morning"}) print(result) ``` **Sample response:** ``` content='The translation of "Good morning" in French is:\n\n"Bonne journée"' additional_kwargs={} response_metadata={} ``` ```python Python theme={null} def test_stream(): """Test synchronous invocation in streaming mode.""" print("\n🔹 Testing Sync `stream()` (Streaming)...") for chunk in llm.stream([HumanMessage(content="Write me a haiku.")]): print(chunk.content, end="", flush=True) # ✅ Ensure streaming is enabled llm = ChatSeekrFlow( client=seekr_client, model_name="meta-llama/Meta-Llama-3-8B-Instruct", streaming=True, # ✅ Enable streaming ) # ✅ Run sync streaming test test_stream() ``` **Sample response:** ``` 🔹 Testing Sync `stream()` (Streaming)... Here is a haiku: Golden sunset fades Ripples on the quiet lake Peaceful evening sky ``` ## Error Handling & Debugging ```python Python expandable theme={null} # Define a minimal mock SeekrFlow client class MockSeekrClient: """Mock SeekrFlow API client that mimics the real API structure.""" class MockChat: """Mock Chat object with a completions method.""" class MockCompletions: """Mock Completions object with a create method.""" def create(self, *args, **kwargs): return { "choices": [{"message": {"content": "Mock response"}}] } # Mimic API response completions = MockCompletions() chat = MockChat() def test_initialization_errors(): """Test that invalid ChatSeekrFlow initializations raise expected errors.""" test_cases = [ { "name": "Missing Client", "args": {"client": None, "model_name": "seekrflow-model"}, "expected_error": "SeekrFlow client cannot be None.", }, { "name": "Missing Model Name", "args": {"client": MockSeekrClient(), "model_name": ""}, "expected_error": "A valid model name must be provided.", }, ] for test in test_cases: try: print(f"Running test: {test['name']}") faulty_llm = ChatSeekrFlow(**test["args"]) # If no error is raised, fail the test print(f"❌ Test '{test['name']}' failed: No error was raised!") except Exception as e: error_msg = str(e) assert test["expected_error"] in error_msg, f"Unexpected error: {error_msg}" print(f"✅ Expected Error: {error_msg}") # Run test test_initialization_errors() ``` Output: ``` Running test: Missing Client ✅ Expected Error: SeekrFlow client cannot be None. Running test: Missing Model Name ✅ Expected Error: A valid model name must be provided. ``` ### API reference * `ChatSeekrFlow` class: [`langchain_seekrflow.ChatSeekrFlow`](https://github.com/benfaircloth/langchain-seekrflow/blob/main/langchain_seekrflow/seekrflow.py) * PyPI package: [`langchain-seekrflow`](https://pypi.org/project/langchain-seekrflow/) # Observability Source: https://docs.seekr.com/flow/sdk/observability Query and inspect spans to monitor agent runs Observability spans are records generated during agent runs that capture timing, model usage, token consumption, and error details. Use the observability resource to query spans across runs or retrieve the full record for a specific span. ## Query spans Use `query_spans` to retrieve span summaries matching a set of filters. All filters are optional. If `min_start_time` is not provided, the query defaults to the last 15 minutes. Start with `run_id` to scope results to a specific run. **Endpoint:** [`POST /v1/observability/spans`](/flow/reference/query_spans_v1_observability_spans_post) ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow(api_key="your_api_key") spans = client.observability.query_spans( run_id="your_run_id" ) for span in spans.spans: print(f"Span ID: {span['span_id']}, Name: {span['span_name']}, Kind: {span['kind']}") ``` Additional filters you can combine: | Parameter | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `agent_id` | Filter by agent | | `thread_id` | Filter by thread | | `trace_id` | Filter by trace | | `group` | Filter by group | | `metadata` | Filter by custom metadata key-value pairs | | `min_start_time` | Filter spans starting after this datetime. Defaults to 15 minutes before the request time if not provided. | | `max_start_time` | Filter spans starting before this datetime | | `limit` | Number of results to return (default: 100) | | `offset` | Pagination offset (default: 0) | | `order` | Sort order by start time (`asc` or `desc`, default: `desc`) | ## Retrieve a span Use `retrieve_span` to fetch the full span object for a specific span by ID. Unlike `query_spans`, which returns summaries, this returns the complete record. **Endpoint:** [`GET /v1/observability/spans/{span_id}`](/flow/reference/retrieve_span_v1_observability_spans__span_id__get) ```python Python theme={null} span = client.observability.retrieve_span(span_id="your_span_id") print(span) ``` ## Investigate a failed run A common pattern is to query spans for a run, then retrieve a specific span to investigate further. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow(api_key="your_api_key") # Get all spans for a run spans = client.observability.query_spans(run_id="your_run_id") # Find the first span with an exception failed_span = next( (s for s in spans.spans if s.get("is_exception")), None ) if failed_span: full_span = client.observability.retrieve_span(span_id=failed_span["span_id"]) print(full_span) ``` # Work with teams Source: https://docs.seekr.com/flow/sdk/teams Scope SDK requests to a team so resources are created in and read from the right place. Every resource in SeekrFlow (agents, fine-tuning jobs, deployments, files, and vector databases) belongs to a team. SDK requests are scoped to a single team. Resources you create are owned by that team, and list and retrieve calls return only that team's resources. For the underlying access model, see [Role-based access control](/flow/role-based-access-control). Threads, and the messages and runs in them, are always user-owned, so selecting a team doesn't affect them. Agents are team-owned, but the threads you run them on are not. ## Set the active team Setting a team is optional. If you don't, requests use your **personal workspace**, the private, single-member team that every user has by default. The [Teams Settings page](/flow/app/manage-permissions#find-a-team-id) in the SeekrFlow web interface lists every team you belong to and its ID. Resources returned by the SDK also include the `team_id` of their owning team. The SDK sends the team you select as the `x-team-id` request header. You can set it in two ways. **Environment variable (recommended).** Set `SEEKR_TEAM_ID` and the SDK applies it automatically to every request: ```bash Linux / macOS theme={null} export SEEKR_TEAM_ID=124cb1bb-d8d3-4e9b-9c96-2039fba43e78 ``` ```bash Windows theme={null} set SEEKR_TEAM_ID=124cb1bb-d8d3-4e9b-9c96-2039fba43e78 ``` ```python Python theme={null} import os from seekrai import SeekrFlow # Picks up SEEKR_API_KEY and SEEKR_TEAM_ID from the environment. client = SeekrFlow() ``` **Per-client header.** Set `supplied_headers` when you construct the client. This takes precedence over `SEEKR_TEAM_ID`, which is useful when one process works across several teams: ```python Python theme={null} import os from seekrai import SeekrFlow client = SeekrFlow( api_key=os.environ.get("SEEKR_API_KEY"), supplied_headers={"x-team-id": "124cb1bb-d8d3-4e9b-9c96-2039fba43e78"}, ) ``` Both approaches work the same way on the asynchronous client: ```python Python theme={null} from seekrai import AsyncSeekrFlow client = AsyncSeekrFlow(supplied_headers={"x-team-id": "124cb1bb-d8d3-4e9b-9c96-2039fba43e78"}) ``` The team applies to the whole client. Every call made through a client is scoped to that client's team. To act on more than one team in the same process, create a separate client per team. ## Create resources in a team Once a client is scoped to a team, every resource you create through it belongs to that team. No extra argument is needed on individual calls: ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow(supplied_headers={"x-team-id": "124cb1bb-d8d3-4e9b-9c96-2039fba43e78"}) # Owned by the client's team. uploaded = client.files.upload(file="training_data.jsonl", purpose="fine-tune") ``` ## Read resources from a team List and retrieve calls return only the resources owned by the client's team. Requests for a resource that belongs to a team you aren't a member of are rejected. ```python Python theme={null} from seekrai import SeekrFlow client = SeekrFlow(supplied_headers={"x-team-id": "124cb1bb-d8d3-4e9b-9c96-2039fba43e78"}) # Only files owned by the client's team. for f in client.files.list().data: print(f.id, f.filename) ``` Returned resources carry the `team_id` of their owning team alongside the `user_id` of the creator, so you can confirm where a resource lives: ```python Python theme={null} agent = client.agents.retrieve(agent_id) print(agent.team_id) # e.g. "124cb1bb-d8d3-4e9b-9c96-2039fba43e78" print(agent.user_id) # the user who created it ``` ## Work across multiple teams To operate on several teams in one program, create one client per team: ```python Python theme={null} from seekrai import SeekrFlow research = SeekrFlow(supplied_headers={"x-team-id": "124cb1bb-d8d3-4e9b-9c96-2039fba43e78"}) production = SeekrFlow(supplied_headers={"x-team-id": "7d9f2a10-4c6b-4f23-8a1e-5b0c9d3e4f21"}) research_files = research.files.list().data production_files = production.files.list().data ``` A resource created in one team is not visible to another. To use a resource across teams, recreate it in each team. # Use cases Source: https://docs.seekr.com/flow/use-case-identification Industry-specific examples of SeekrFlow applications across different workflows and business verticals. This page provides industry-specific examples of SeekrFlow applications across different workflow types, including potential document sources, collection strategies, and expected business impact. ## Government | | Instruction fine-tuning or context-grounded workflow | Agentic workflow | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Example use case** | Automated document summarization for policy briefings with explainable citations | Fraud detection systems that flag suspicious patterns for human review | | Domain-specific elements | Regulatory language, legal frameworks, and agency-specific terminology. | Agency-specific fraud patterns, jurisdiction-based enforcement criteria | | Document sources | Federal regulations, agency handbooks, court decisions, policy manuals, precedent documents, and interagency communications | Historical transaction data, fraud case files, customer profiles with normal behavior patterns, regulatory requirements, investigation procedures, alert handling protocols, performance metrics | | Expected business impact | Enhanced policy analysis with 40% faster brief generation and 25-30% reduction in citizen services | Estimated 30-40% decrease in manual review time with potential to identify 15-25% more fraudulent activities | | HITL component | Managers or officials approve AI-generated content before publication and can provide feedback to improve future outputs | Analysts investigate flagged patterns and determine their risk level, then provide feedback to improve future outputs | ## Manufacturing and supply chain | | Instruction fine-tuning or context-grounded workflow | Agentic workflow | | ------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Example use case** | Predictive maintenance reports based on equipment sensor data | Autonomous inventory management that orders supplies when thresholds are reached | | Domain-specific elements | Production processes, equipment tolerances, supply chain dependencies | Lead time variations, supplier reliability metrics, seasonal demand patterns | | Document sources | Equipment manuals, maintenance logs, quality control standards, vendor specifications | Inventory master data, supplier agreements and fulfillment records, threshold configuration documentation, cost management frameworks, performance metric standards (e.g., service level targets, stockout tolerance thresholds) | | Expected business impact | 15-25% decrease in overall maintenance expenses with 20-30% improvement in maintenance labor utilization | 10-20% decrease in inventory holding costs with 30-50% reduction in stockout events | | HITL component | Production managers can review and adjust AI recommendations for critical equipment | Production managers can review and adjust AI purchases of critical equipment | ## Media and publishing | | Instruction fine-tuning or context-grounded workflow | Agentic workflow | | ------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **Example use case** | Content personalization across platforms with brand voice adaptation | Automated content moderation with escalation paths for borderline cases | | Domain-specific elements | Content rights management, publishing workflows, audience engagement metrics | Platform-specific community guidelines, cultural context sensitivity | | Document sources | Style guides, published content archives, audience research, competitor analysis | Moderation precedents, policy documents, context-dependent examples | | Expected business impact | 20-30% reduction in content production costs, with 15-25% higher conversion rates | 50-70% decrease in policy violation exposure time with 40-60% reduction in human moderation workload | | HITL component | Editors review AI-generated headlines and summaries before publication | Community moderators can review and adjust flagged content violations | ## Hospitality and travel logistics | | Instruction fine-tuning or context-grounded workflow | Agentic workflow | | ------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Example use case** | Personalized itinerary creation with explanation of recommendations | Dynamic pricing systems that adjust based on demand patterns | | Domain-specific elements | Seasonal travel patterns, regulatory requirements, loyalty program structures | Competitive rate intelligence, demand forecasting patterns, event impact analysis | | Document sources | Guest history, booking terminology, destination descriptions, service amenities | Historical pricing performance, competitor positioning, market response patterns | | Expected business impact | 10-15% increase in average booking value with 25-30% increase in NPS | 8-12% increase in profit margin with 15-20% reduction in unbooked inventory | | HITL component | Customer service representatives can override AI-suggested solutions | Pricing systems can be reviewed and adjusted for unusual demand patterns, or price changes outside a certain range | ## Financial services | | Instruction fine-tuning or context-grounded workflow | Agentic workflow | | ------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | **Example use case** | Risk assessment reports with highlighted factors and confidence levels | Anomaly detection for transactions that autonomously escalates suspicious activity | | Domain-specific elements | Market mechanics, financial products, regulatory frameworks | Transaction pattern baselines, risk scoring models, regulatory thresholds | | Document sources | Regulatory filings, market reports, financial statements, compliance documents, reporting templates | Historical transaction data, regulatory compliance documents, escalation protocols, risk assessment frameworks | | Expected business impact | 40% faster report generation with 25-30% reduction in risk exposure | 40-60% improvement in fraud detection rates with 60-80% faster processing of legitimate transactions | | HITL component | Financial analysts review model outputs for major investment decisions | Analysts review and adjust flagged activity and provide feedback on accuracy to improve future outputs | ## Customer support | | Instruction fine-tuning or context-grounded workflow | Agentic workflow | | ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Example use case** | Knowledge base article generation with source attribution | Support ticket routing and prioritization with automatic responses for common issues | | Domain-specific elements | Product terminology, service procedures, product capabilities | Support escalation paths, troubleshooting procedures, technical specifications, regulatory or compliance-related urgency factors, solution documentation structure, customer segmentation criteria | | Document sources | Product documentation, knowledge base articles, resolved ticket history, FAQs | SLA documentation, prioritization frameworks, knowledge base articles, support team structure, historical ticket database, response templates, reporting templates, performance metrics (success, customer satisfaction, accuracy, QA review processes) | | Expected business impact | 30-40% reduction in support ticket filing, with 15-20% increase in customer retention | 30-50% improvement in first-contact resolution with 15-25% increase in CSAT scores | | HITL component | Customer support can review articles and sources for accuracy and appropriateness and adjust accordingly | Support managers review alerts for potentially problematic interactions and adjust as needed | # What is SeekrFlow Source: https://docs.seekr.com/flow/what-is-seekrflow An overview of SeekrFlow's platform capabilities for building enterprise AI solutions. SeekrFlow is a complete AI development platform for organizations to build, customize, and scale generative and agentic AI solutions with full visibility and control over how AI learns, reasons, and delivers results. SeekrFlow provides a unified framework for the entire AI development lifecycle—from data preparation to model deployment and monitoring. The platform serves organizations that need enterprise-grade AI solutions with domain-specific knowledge, strict compliance requirements, and full data sovereignty. SeekrFlow supports both prebuilt solutions for common use cases and custom applications built on a robust, extensible architecture designed for enterprise scale. To start using SeekrFlow, see the [User Guide](/flow/app/dashboard) for UI-based workflows or the [API Reference](/flow/reference/getting-started-with-your-api) for programmatic access. ## Key components SeekrFlow is built on several core components: * **Agents** – Configurable AI systems that reason and execute tasks * **Data engine** – Transform raw content into AI-ready data * **Fine-tuning** – Adapt models to specific domains * **Deployments** – Launch and manage model endpoints * **Explainability** – Understand the sources and training data behind model responses * **Content moderation** – Evaluate content safety and compliance For detailed information about each component, see [Components](/flow/components). ## Prebuilt solutions SeekrFlow offers prebuilt AI solutions for enterprise and government use cases, including geospatial intelligence, threat analysis, procurement automation, and content moderation. All solutions can be customized with organization-specific data while maintaining security and compliance requirements. For a complete catalog of available solutions, see [Solutions](https://www.seekr.com/solutions/). ## Deployment options SeekrFlow provides flexible deployment options to meet different security, compliance, and performance requirements: * **Our cloud** – Build and deploy fast with fully managed AI as a Service, no infrastructure required * **Your cloud** – Integrate seamlessly with your preferred cloud platform * **Your data center** – Run on your terms—whether it's your own compute, on-premises, or fully air-gapped environments * **At the edge** – Deploy AI anywhere and reduce latency with edge solutions preloaded with SeekrFlow, models, storage, and networking ## Security With Seekr, your data remains yours. We never use it to train other models and give you full control to install our platform wherever your data resides: * **SOC 2 Type II certified** ensuring best-in-class security standards * **Complete data sovereignty** with ringfenced data and completions that never leave your environment * **Flexible deployment** on your cloud or hardware of choice * **Explainability and oversight** built into every component, from data processing to model outputs