### Start Mastra Dev Server (Bash)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_REFACTORING.md

Starts the Mastra server using npm. The server will be accessible at http://localhost:4111.

```bash
npm run mastra:dev
```

--------------------------------

### Install Mastra Core and Vercel AI SDK (npm)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_AGENTS.md

Installs the Mastra core package along with the Vercel AI SDK for OpenAI. This setup is for integrating Mastra agents with Vercel's AI ecosystem.

```bash
npm install @mastra/core @ai-sdk/openai
```

--------------------------------

### Simplified User Flow Example

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-08-enhanced-byok-multi-provider-plan.md

This outlines a simplified user flow for selecting a model, specifically GPT-4o, demonstrating the steps from clicking a provider section to successfully applying the chosen model.

```plaintext
User wants GPT-4o
→ Clicks OpenAI section
→ Sees "Add API key to unlock"
→ Pastes key, clicks Save
→ Section expands showing all OpenAI models
→ Selects GPT-4o
→ Clicks Apply
→ Done!
```

--------------------------------

### Directory Structure Example

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/00_DEV_PLAN_TEMPLATE.md

Visualizes the expected directory and file structure for the project. It indicates new files, modified files, new directories, and files that remain unchanged, aiding in understanding the project layout.

```bash
[directory]/
├── file1.ts              (MODIFY - description)
├── dir/                  (NEW DIRECTORY)
│   └── file2.ts          (NEW FILE - description)
└── file3.ts              (NO CHANGES)
```

--------------------------------

### TypeScript Implementation Step Example

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/00_DEV_PLAN_TEMPLATE.md

Illustrates a code snippet representing a step within a TypeScript implementation. This serves as a placeholder for actual logic and demonstrates the expected code structure for a given task.

```typescript
// Code example
```

--------------------------------

### POST /api/v1/projects

Source: https://context7.com/andrelandgraf/aileen/llms.txt

Creates a new project with automated database, repository, authentication, and development server setup.

```APIDOC
## POST /api/v1/projects

### Description
Creates a new project with automated database, repository, authentication, and development server setup.

### Method
POST

### Endpoint
/api/v1/projects

### Parameters
#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the project to create.

### Request Example
```json
{
  "name": "my-saas-app"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created project.
- **name** (string) - The name of the project.
- **repoId** (string) - The ID of the associated repository.
- **neonProjectId** (string) - The ID of the Neon project.
- **threadId** (string) - The ID of the associated chat thread.
- **userId** (string) - The ID of the user who created the project.
- **currentDevVersionId** (string | null) - The ID of the current development version, if any.
- **createdAt** (string) - The timestamp when the project was created.
- **updatedAt** (string) - The timestamp when the project was last updated.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-saas-app",
  "repoId": "fs-repo-abc123",
  "neonProjectId": "neon-proj-xyz789",
  "threadId": "thread-def456",
  "userId": "user-123",
  "currentDevVersionId": null,
  "createdAt": "2025-12-09T01:23:45.678Z",
  "updatedAt": "2025-12-09T01:23:45.678Z"
}
```
```

--------------------------------

### Example Response for Branch Expiration

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/BRANCHING_DOCS.md

This is an example JSON response from the Neon API when creating a branch with an expiration timestamp. It includes fields like 'expires_at' showing the deletion time and 'ttl_interval_seconds' for the initial expiration duration.

```json
{
  "branch": {
    "id": "br-feature-67890",
    "name": "feature-test-branch",
    "expires_at": "2024-12-15T18:02:16Z",
    "ttl_interval_seconds": 604800,
    "created_at": "2024-12-08T18:02:16Z"
  }
}

```

--------------------------------

### Install Mastra Core Package (npm)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_AGENTS.md

Installs the core Mastra package using npm. This is a prerequisite for using Mastra's agent functionalities.

```bash
npm install @mastra/core
```

--------------------------------

### TypeScript Import Statement Example

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/00_DEV_PLAN_TEMPLATE.md

Shows an example of importing modules or types in TypeScript. This is crucial for managing dependencies and utilizing external code within the project.

```typescript
import ... from "...";
```

--------------------------------

### Request Dev Server

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

This endpoint allows you to request a dev server for a specific Git repository. The server will be started and provided with a URL for previewing.

```APIDOC
## POST /dev-servers/request

### Description
Requests a new dev server instance for a given repository ID. This server will provide a hot-reloading environment for development and previewing.

### Method
POST

### Endpoint
/dev-servers/request

### Parameters
#### Request Body
- **repoId** (string) - Required - The ID of the repository to create a dev server for.
- **preset** (string) - Optional - A preset for the dev server (e.g., 'nextJs', 'vite', 'expo', 'auto'). Overrides any preset set on the repository.
- **dev_command** (string) - Optional - The command to run to start the development server. Overrides the default command for the chosen preset or repository setting.
- **install_command** (string) - Optional - The command to run to install dependencies. Overrides the default command.
- **ports** (array) - Optional - An array of port mappings (external -> target). Overrides the default ports.
  - Each element is an object with 'external' and 'target' keys (both numbers).
- **envVars** (object) - Optional - Environment variables to set for the dev server. Overrides any existing environment variables.

### Request Example
```json
{
  "repoId": "your-repo-id-here",
  "preset": "nextJs"
}
```

### Response
#### Success Response (200)
- **ephemeralUrl** (string) - The URL to access the ephemeral dev server.
- **status** (string) - The current status of the dev server (e.g., 'running', 'pending').

#### Response Example
```json
{
  "ephemeralUrl": "https://your-dev-server-url.example.com",
  "status": "running"
}
```
```

--------------------------------

### Command to install and run Ampersand MCP Server (Shell)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_MCP.md

This command uses npx to install and run the '@amp-labs/mcp-server' package with specific configurations. It sets the transport to 'stdio' and passes project-specific environment variables for integration and group references. The AMPERSAND_API_KEY is also configured in the environment for authentication.

```shell
{
            command: "npx",
            args: [
              "-y",
              "@amp-labs/mcp-server@latest",
              "--transport",
              "stdio",
              "--project",
              process.env.AMPERSAND_PROJECT_ID,
              "--integrationName",
              process.env.AMPERSAND_INTEGRATION_NAME,
              "--groupRef",
              process.env.AMPERSAND_GROUP_REF, // optional
            ],
            env: {
              AMPERSAND_API_KEY: process.env.AMPERSAND_API_KEY,
            },
          }
```

--------------------------------

### Get System Models

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-08-enhanced-byok-multi-provider-plan.md

Retrieves a predefined list of system models that are always available with platform keys. Currently, this includes specific versions of Claude 3.5 Haiku and Sonnet. It filters all available models to return only these system models.

```typescript
export async function getSystemModels(): Promise<NormalizedModel[]> {
  const allModels = await getAllModels();
  return allModels.filter(
    (model) =>
      model.id === "anthropic/claude-3-5-haiku-20241022" ||
      model.id === "anthropic/claude-3-5-sonnet-20241022",
  );
}
```

--------------------------------

### GET /api/v1/models

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-08-enhanced-byok-multi-provider-plan.md

Retrieves a list of available AI models, categorized into system models and user-provided models (BYOK). It also returns the user's saved API key providers.

```APIDOC
## GET /api/v1/models

### Description
This endpoint exposes filtered models to the frontend. It fetches system models (always available) and BYOK (Bring Your Own Key) models based on the user's saved API keys. It also returns a list of the user's saved API key providers.

### Method
GET

### Endpoint
/api/v1/models

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **systemModels** (array) - An array of available system models.
- **byokModels** (array) - An array of BYOK models available based on user's API keys.
- **userProviders** (array) - An array of strings representing the user's saved API key providers (e.g., "anthropic", "openai", "google").

#### Response Example
```json
{
  "systemModels": [
    {
      "id": "openai/gpt-4o",
      "name": "GPT-4o",
      "provider": "openai",
      "type": "completion"
    }
  ],
  "byokModels": [
    {
      "id": "anthropic/claude-3-opus-20240229",
      "name": "Claude 3 Opus",
      "provider": "anthropic",
      "type": "completion"
    }
  ],
  "userProviders": ["anthropic", "openai"]
}
```

#### Error Response (401)
- **error** (string) - "Unauthorized"

#### Error Response (500)
- **error** (string) - "Failed to fetch models"
```

--------------------------------

### Visual Design Enhancements: TypeScript Examples

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-08-enhanced-byok-multi-provider-plan.md

This snippet illustrates visual design enhancements using TypeScript, including color-coded provider badges, status indicators for key management, cost display formatting, and context window badges.

```typescript
// Color-coded provider badges
Anthropic: Blue (#1E90FF)
OpenAI: Green (#10B981)
Google: Multi-color (#4285F4, #EA4335, #FBBC04, #34A853)

// Status indicators
✓ Key Saved: Green badge
+ Add Key: Dashed border, muted
🔒 Locked: Gray overlay on models

// Cost display formatting
Input/Output per M tokens
$1.00/$5.00 instead of verbose text

// Context window badges
<100K: Small badge
100K-500K: Medium badge
500K+: Large badge with ⚡ icon
```

--------------------------------

### Start MCPServer with Workflows (TypeScript)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_WORKFLOW.md

Initializes and starts an `MCPServer` instance, exposing provided workflows as callable tools. It requires the `@mastra/mcp` library and workflow definitions. The server is started on stdio.

```typescript
import { MCPServer } from "@mastra/mcp";

import { testAgent } from "./mastra/agents/test-agent";
import { testTool } from "./mastra/tools/test-tool";
import { testWorkflow } from "./mastra/workflows/test-workflow";

async function startServer() {
  const server = new MCPServer({
    name: "test-mcp-server",
    version: "1.0.0",
    workflows: {
      testWorkflow,
    },
  });

  await server.startStdio();
  console.log("MCPServer started on stdio");
}

startServer().catch(console.error);
```

--------------------------------

### Install MCP Dependency

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_MCP.md

This command installs the latest version of the Mastra MCP package, which is required to use MCPClient and MCPServer functionalities.

```bash
npm install @mastra/mcp@latest
```

--------------------------------

### Create Git Repository for Dev Server (Python)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

Initializes a Freestyle client and creates a new Git repository from a Python SDK. The repository is named, set to public for testing purposes, and configured with a source URL for a 'freestyle-base-nextjs-shadcn' project. This function requires the 'freestyle' Python library and an API key.

```python
import freestyle

client = freestyle.Freestyle("YOUR_FREESTYLE_API_KEY")

repo = client.create_repository(
  name="Test Repository from Python SDK",


  # This will make it easy for us to clone the repo during testing.
  # The repo won't be listed on any public registry, but anybody
  # with the uuid can clone it. You should disable this in production.
  public=True,
  source=freestyle.CreateRepoSource.from_dict(
      {
          "type": "git",
          "url": "https://github.com/freestyle-sh/freestyle-base-nextjs-shadcn",
      }
  ),
)

print(f"Created repo with ID: {repo.repo_id}")

```

--------------------------------

### Clone Repository Locally (Bash)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

Clone a repository locally using the standard git clone command. This allows for local development and testing. Ensure the repository is public or configure git credentials for private repositories.

```bash
git clone https://git.freestyle.sh/<repoId>
```

--------------------------------

### Request Dev Server from Repository (TypeScript)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

Requests a dev server instance for a given repository ID using the 'freestyle-sandboxes' library. It outputs the ephemeral URL of the created dev server, which provides a live preview environment. The dev server will shut down if not kept alive.

```typescript
import { FreestyleSandboxes } from "freestyle-sandboxes";

const freestyle = new FreestyleSandboxes();

const devServer = await freestyle.requestDevServer({ repoId });

console.log(`Dev Server URL: ${devServer.ephemeralUrl}`);

```

--------------------------------

### TypeScript Handler Signature Example

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/00_DEV_PLAN_TEMPLATE.md

Provides an example of a handler function signature in TypeScript, including its asynchronous nature, parameters, and return type. This is useful for defining the structure of API endpoints or event handlers.

```typescript
export async function [FunctionName](params: Type): Promise<ReturnType>
```

--------------------------------

### Create Git Repository for Dev Server (TypeScript)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

Creates a new Git repository to be used as a base for a dev server. It configures the repository with a specified name, sets it to public for easy cloning during testing, and defines a 'nextJs' preset for automatic dev server configuration. This function requires the 'freestyle-sandboxes' library.

```typescript
import { FreestyleSandboxes } from "freestyle-sandboxes";

const freestyle = new FreestyleSandboxes();


const { repoId } = await freestyle.createGitRepository({
  name: "Test Repository",

  // This will make it easy for us to clone the repo during testing.
  // The repo won't be listed on any public registry, but anybody
  // with the uuid can clone it. You should disable this in production.
  public: true,

  source: {
    url: "https://github.com/freestyle-sh/freestyle-next",
    type: "git",
  },
  devServers: {
    preset: "nextJs", // Set the preset for the framework you're using, this will automatically configure the dev server for you
  }
});

console.log(`Created repo with ID: ${repoId}`);

```

--------------------------------

### Tool Normalization TypeScript Example

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_MCP_SETUP.md

Demonstrates the tool normalization process in TypeScript, showing how missing fields like 'type' and 'required' are added to ensure compatibility with Anthropic's requirements. Invalid tools with non-object parameter types are filtered out.

```typescript
// Before normalization
{
  description: "Read a file",
  parameters: {
    properties: { path: { type: "string" } }
    // Missing: type, required
  }
}

// After normalization
{
  description: "Read a file",
  parameters: {
    type: "object", // Added
    properties: { path: { type: "string" } },
    required: [] // Added
  }
}
```

--------------------------------

### Get Operation Details

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/OPERATIONS_DOCS.md

Retrieves the details for a specific operation ID within a project.

```APIDOC
## GET /projects/{project_id}/operations/{operation_id}

### Description
This method shows only the details for the specified operation ID.

### Method
GET

### Endpoint
`/projects/{project_id}/operations/{operation_id}`

#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **operation_id** (string) - Required - The ID of the operation to retrieve.

### Request Example
```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/97c7a650-e4ff-43d7-8c58-4c67f5050167' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

### Response
#### Success Response (200)
- **operation** (object) - An object containing the details of the specified operation.

##### Operation Object
- **id** (string) - The unique identifier for the operation.
- **project_id** (string) - The ID of the project the operation belongs to.
- **branch_id** (string) - The ID of the branch associated with the operation.
- **endpoint_id** (string) - The ID of the endpoint associated with the operation.
- **action** (string) - The type of action performed by the operation.
- **status** (string) - The current status of the operation (e.g., 'finished').
- **failures_count** (integer) - The number of failures encountered during the operation.
- **created_at** (string) - The timestamp when the operation was created.
- **updated_at** (string) - The timestamp when the operation was last updated.

#### Response Example
```json
{
  "operation": {
    "id": "97c7a650-e4ff-43d7-8c58-4c67f5050167",
    "project_id": "autumn-disk-484331",
    "branch_id": "br-wispy-dew-591433",
    "endpoint_id": "ep-orange-art-714542",
    "action": "check_availability",
    "status": "finished",
    "failures_count": 0,
    "created_at": "2022-12-09T08:47:52Z",
    "updated_at": "2022-12-09T08:47:56Z"
  }
}
```
```

--------------------------------

### Create Git Repository

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

This endpoint allows you to create a new Git repository to base your dev server on. You can specify the repository name, whether it should be public, and the source URL.

```APIDOC
## POST /repos

### Description
Creates a new Git repository to be used as a base for dev servers. This repository can be cloned by agents and used to spin up development environments.

### Method
POST

### Endpoint
/repos

### Parameters
#### Request Body
- **name** (string) - Required - The name of the repository.
- **public** (boolean) - Optional - Whether the repository should be publicly accessible. Defaults to false.
- **source** (object) - Required - The source of the repository.
  - **url** (string) - Required - The URL of the Git repository.
  - **type** (string) - Required - The type of the source, e.g., 'git'.
- **devServers** (object) - Optional - Configuration for dev servers based on this repository.
  - **preset** (string) - Optional - A preset for the dev server (e.g., 'nextJs', 'vite', 'expo', 'auto').

### Request Example
```json
{
  "name": "Test Repository",
  "public": true,
  "source": {
    "url": "https://github.com/freestyle-sh/freestyle-next",
    "type": "git"
  },
  "devServers": {
    "preset": "nextJs"
  }
}
```

### Response
#### Success Response (200)
- **repoId** (string) - The ID of the created repository.

#### Response Example
```json
{
  "repoId": "your-repo-id-here"
}
```
```

--------------------------------

### Model Configuration Note in Instructions (TypeScript)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-04-byok-anthropic-api-keys-plan.md

This snippet shows how the current model configuration is displayed within the agent's instructions. It dynamically includes the selected model name and key provider status, indicating whether a personal API key is in use.

```typescript
**Current Model Configuration:**
- Model: ${modelSelection?.model || "claude-haiku-4-5"}
- Key Provider: ${modelSelection?.keyProvider || "platform"} ${modelSelection?.apiKey ? "(using your personal API key)" : "(using platform key)"}
```

--------------------------------

### Get Operation Status with cURL

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/OPERATIONS_DOCS.md

This snippet shows how to poll the status of a specific Neon API operation using cURL. It targets the 'Get operation details' endpoint and requires the operation ID and API key for authentication. The response body will contain the current status of the operation, which can be checked until it reaches a terminal state like 'finished', 'skipped', or 'cancelled'.

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/055b17e6-ffe3-47ab-b545-cfd7db6fd8b8' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

--------------------------------

### GET /api/v2/projects/{project_id}/connection_uri

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/SNAPSHOT_DOCS.md

Retrieves the connection URI for a specific branch. Useful for inspecting the restored branch.

```APIDOC
## GET /api/v2/projects/{project_id}/connection_uri

### Description
Retrieves the connection URI for a specific branch. Useful for inspecting the restored branch.

### Method
GET

### Endpoint
/api/v2/projects/{project_id}/connection_uri

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The Neon project ID.

#### Query Parameters
- **branch_id** (string) - Required - The ID of the branch to get the connection URI for.
- **database_name** (string) - Optional - The name of the database.
- **role_name** (string) - Optional - The name of the role.
- **pooled** (boolean) - Optional - Whether to retrieve a pooled connection URI.

#### Request Body
None

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **uri** (string) - The connection URI for the specified branch.

#### Response Example
(Response structure not detailed in the provided text)
```

--------------------------------

### Create User AI API Keys Table Migration (SQL)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-04-byok-anthropic-api-keys-plan.md

This SQL script defines the database migration to create the 'user_ai_api_keys' table. It includes an enum for AI providers and sets up columns for user ID, provider, API key, and timestamps. The table enforces a unique constraint for user ID and provider combinations.

```sql
CREATE TYPE "ai_provider" AS ENUM ('anthropic', 'openai', 'openrouter');

CREATE TABLE "user_ai_api_keys" (
  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  "user_id" text NOT NULL REFERENCES "users_sync"("id") ON DELETE CASCADE,
  "provider" "ai_provider" NOT NULL,
  "api_key" text NOT NULL,
  "created_at" timestamp NOT NULL DEFAULT now(),
  "updated_at" timestamp NOT NULL DEFAULT now(),
  UNIQUE("user_id", "provider")
);

CREATE INDEX "user_ai_api_keys_user_id_idx" ON "user_ai_api_keys"("user_id");
```

--------------------------------

### GET /api/v2/projects/{project_id}/snapshots

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/SNAPSHOT_DOCS.md

Lists all snapshots for a given project. This can be used to find the snapshot_id for restore operations.

```APIDOC
## GET /api/v2/projects/{project_id}/snapshots

### Description
Lists all snapshots for a given project. This can be used to find the snapshot_id for restore operations.

### Method
GET

### Endpoint
/api/v2/projects/{project_id}/snapshots

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The Neon project ID.

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **snapshots** (array) - A list of snapshot objects.

#### Response Example
(Response structure not detailed in the provided text)
```

--------------------------------

### Manage Neon Postgres Projects, Databases, Branches, and Snapshots

Source: https://context7.com/andrelandgraf/aileen/llms.txt

The NeonService handles Neon Postgres projects, databases, branches, and snapshots. It supports creating projects, initializing authentication, managing allowlisted domains, retrieving connection URIs, creating and restoring database snapshots, and deleting projects.

```typescript
import { neonService } from "@/lib/neon";

// Create project with database
const { neonProjectId, databaseUrl } = await neonService.createProject("my-project");

// Initialize Neon Auth for project
const authConfig = await neonService.initNeonAuth(
  neonProjectId,
  branchId,
  "neondb",
  "neondb_owner"
);

// Add allowlisted domain for authentication
await neonService.addAuthDomain(
  neonProjectId,
  "my-app-dev.freestyle.dev",
  "stack"
);

// Get connection URI for specific branch
const connectionUri = await neonService.getConnectionUri({
  projectId: neonProjectId,
  branchId: "br-main-123",
  databaseName: "neondb",
  roleName: "neondb_owner",
  pooled: true
});

// Create database snapshot
const snapshotId = await neonService.createSnapshot(neonProjectId, {
  name: "checkpoint-feature-complete",
  timestamp: new Date().toISOString()
});

// Restore snapshot to branch
await neonService.applySnapshot(neonProjectId, snapshotId, targetBranchId);

// Delete project and all resources
await neonService.deleteProject(neonProjectId);
```

--------------------------------

### GET /api/v1/models

Source: https://context7.com/andrelandgraf/aileen/llms.txt

Returns list of available AI models with provider information and pricing.

```APIDOC
## GET /api/v1/models

### Description
Retrieves a list of available AI models that can be used with the platform, including information about their providers and pricing.

### Method
GET

### Endpoint
/api/v1/models

### Parameters
None

### Request Example
```bash
curl -X GET https://aileen.example.com/api/v1/models \
  -H "Authorization: Bearer <stack-auth-token>"
```

### Response
#### Success Response (200 OK)
- **models** (array) - A list of available AI models. (Note: The exact structure of each model object is not detailed in the provided text but would typically include name, provider, pricing details, etc.)

#### Response Example
(Example response structure based on typical API design, actual response may vary)
```json
{
  "models": [
    {
      "id": "claude-3-opus-20240229",
      "provider": "anthropic",
      "pricing": {
        "input_token_cost": 0.000015,
        "output_token_cost": 0.000075
      },
      "context_window": 200000
    },
    {
      "id": "gpt-4o",
      "provider": "openai",
      "pricing": {
        "input_token_cost": 0.000005,
        "output_token_cost": 0.000015
      },
      "context_window": 128000
    }
  ]
}
```
```

--------------------------------

### Create Neon Project Branch via cURL

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/BRANCHING_DOCS.md

This snippet demonstrates how to create a branch for a Neon project using a cURL command. It requires the project ID and an API key for authentication. The command specifies the type of compute endpoint to create, such as 'read_write', and the parent branch ID from which to branch. The response will detail the newly created branch and its compute endpoint.

```bash
curl 'https://console.neon.tech/api/v2/projects/<project_id>/branches' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoints": [
    {
      "type": "read_write"
    }
  ],
  "branch": {
    "parent_id": "br-wispy-dew-591433"
  }
}' | jq
```

--------------------------------

### GET /api/v1/projects/{projectId}/versions

Source: https://context7.com/andrelandgraf/aileen/llms.txt

Retrieves all saved versions/checkpoints for a project, ordered by creation date.

```APIDOC
## GET /api/v1/projects/{projectId}/versions

### Description
Retrieves all saved versions/checkpoints for a project, ordered by creation date.

### Method
GET

### Endpoint
/api/v1/projects/{projectId}/versions

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The unique identifier of the project.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET https://aileen.example.com/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/versions \
  -H "Authorization: Bearer <stack-auth-token>"
```

### Response
#### Success Response (200 OK)
- **versions** (array) - A list of version objects.
  - **id** (string) - The unique identifier for the version.
  - **projectId** (string) - The ID of the project this version belongs to.
  - **gitCommitHash** (string) - The Git commit hash associated with this version.
  - **neonSnapshotId** (string) - The ID of the Neon database snapshot.
  - **assistantMessageId** (string) - The ID of the assistant message that triggered this version.
  - **summary** (string) - A brief summary of the changes in this version.
  - **createdAt** (string) - The timestamp when this version was created.
- **currentDevVersionId** (string) - The ID of the current development version.

#### Response Example
```json
{
  "versions": [
    {
      "id": "ver-123",
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "gitCommitHash": "a1b2c3d4e5f6g7h8i9j0",
      "neonSnapshotId": "snap-abc123",
      "assistantMessageId": "msg-xyz789",
      "summary": "Added user authentication and dashboard",
      "createdAt": "2025-12-09T02:30:00.000Z"
    }
  ],
  "currentDevVersionId": "ver-123"
}
```
```

--------------------------------

### Create Mastra Agent with Mixed Vercel AI SDK and Mastra Tools

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_MCP.md

Demonstrates the creation of a Mastra Agent capable of using tools defined in both the Vercel AI SDK format and Mastra's `createTool` format. This example shows how to import and configure tools from both origins within the agent's `tools` configuration, highlighting Mastra's flexibility in supporting diverse tool definitions.

```typescript
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { vercelWeatherTool } from "../tools/vercelWeatherTool"; // Vercel AI SDK tool
import { mastraTool } from "../tools/mastraTool"; // Mastra createTool tool

export const mixedToolsAgent = new Agent({
  name: "Mixed Tools Agent",
  instructions: "You can use tools defined in different formats.",
  model: openai("gpt-4o-mini"),
  tools: {
    weatherVercel: vercelWeatherTool,
    someMastraTool: mastraTool,
  },
});
```

--------------------------------

### Static Tools Pattern Registration (TypeScript)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_REFACTORING.md

Demonstrates how tools are statically registered with an agent during its creation time. This pattern is not used in the current setup.

```typescript
// Tools are registered with the agent at creation time
const agent = new Agent({
  tools: await mcpClient.getTools(),
});
```

--------------------------------

### Request Dev Server from Repository (Python)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

Requests a dev server for a specified repository ID using the Freestyle Python SDK. The function returns the dev server details, including its ephemeral URL, which can be used for live previewing. An API key and the repository object are required.

```python
import freestyle

client = freestyle.Freestyle("YOUR_FREESTYLE_API_KEY")

dev_server = client.request_dev_server(repo_id=repo.repo_id)

print(f"Dev Server URL: {dev_server.ephemeral_url}")

```

--------------------------------

### List Files in Directory on Dev Server (TypeScript, Python)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

List the files and directories within a specified directory on the dev server using the file system interface. This operation is not recursive; for recursive listings, use the 'process' interface to run commands like 'ls -R' or 'find .'.

```typescript
const files = await fs.ls("src");

console.log(files);
```

```python
files = fs.ls("src")

print(files)
```

--------------------------------

### Get Specific Operation Details (cURL)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/OPERATIONS_DOCS.md

Fetches the details of a specific operation using its unique operation ID. This method is useful for inspecting the status and details of a single operation.

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/97c7a650-e4ff-43d7-8c58-4c67f5050167' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

--------------------------------

### Add AI SDK Packages to package.json (JSON)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-08-enhanced-byok-multi-provider-plan.md

This JSON snippet details the addition of new dependencies to the `package.json` file, specifically including the AI SDK packages for OpenAI (`@ai-sdk/openai`) and Google (`@ai-sdk/google`) to support multi-provider AI model integration.

```json
{
  "dependencies": {
    "@ai-sdk/anthropic": "latest",
    "@ai-sdk/openai": "latest", // NEW
    "@ai-sdk/google": "latest" // NEW
    // ... existing dependencies
  }
}

```

--------------------------------

### Format Cost for Display

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/dev/25-11-08-enhanced-byok-multi-provider-plan.md

Formats a cost value (per million tokens) into a user-friendly string representation, typically with a dollar sign and two decimal places. For example, 2.50 becomes '$2.50'.

```typescript
export function formatCost(costPerMillion: number): string {
  return `$${costPerMillion.toFixed(2)}`;
}
```

--------------------------------

### List Operations using Neon API

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/OPERATIONS_DOCS.md

This cURL command demonstrates how to list all operations for a Neon project via the Neon API. It requires an API key for authorization and specifies the project ID in the URL. The response is returned in JSON format.

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

--------------------------------

### Clone Repository with Isomorphic-git (TypeScript)

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_DEV_SERVER.md

Clone a repository using isomorphic-git in a serverless JavaScript environment. This library is recommended for managing Git operations from Node.js, handling file system operations and HTTP protocols for cloning.

```typescript
import git from "isomorphic-git";
import fs from "fs";
import http from "isomorphic-git/http/node";

git.clone({
  fs,
  url: "https://git.freestyle.sh/<repoId>",
  singleBranch: true,
  depth: 1,
  http,
});
```

--------------------------------

### Get Operation Details

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/OPERATIONS_DOCS.md

Retrieves the status of a specific operation initiated by a Neon API request. This is useful for polling the operation's progress until it reaches a terminal state (finished, skipped, or cancelled).

```APIDOC
## GET /api/v2/projects/{project_id}/operations/{operation_id}

### Description
Polls the status of a specific operation by its unique ID.

### Method
GET

### Endpoint
`/api/v2/projects/{project_id}/operations/{operation_id}`

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **operation_id** (string) - Required - The ID of the operation to poll.

### Request Example
```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/055b17e6-ffe3-47ab-b545-cfd7db6fd8b8' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

### Response
#### Success Response (200)
- **operation** (object) - Details about the operation.
  - **id** (string) - The unique identifier of the operation.
  - **project_id** (string) - The ID of the project the operation belongs to.
  - **branch_id** (string, optional) - The ID of the branch associated with the operation.
  - **endpoint_id** (string, optional) - The ID of the endpoint associated with the operation.
  - **action** (string) - The type of action the operation performs (e.g., "create_branch", "start_compute").
  - **status** (string) - The current status of the operation. Possible values: `scheduling`, `running`, `finished`, `failed`, `cancelling`, `cancelled`, `skipped`.
  - **failures_count** (integer) - The number of times the operation has failed.
  - **created_at** (string) - The timestamp when the operation was created (ISO 8601 format).
  - **updated_at** (string) - The timestamp when the operation was last updated (ISO 8601 format).

#### Response Example
```json
{
  "operation": {
    "id": "055b17e6-ffe3-47ab-b545-cfd7db6fd8b8",
    "project_id": "autumn-disk-484331",
    "branch_id": "br-dawn-scene-747675",
    "endpoint_id": "ep-small-bush-675287",
    "action": "start_compute",
    "status": "finished",
    "failures_count": 0,
    "created_at": "2022-12-08T19:55:43Z",
    "updated_at": "2022-12-08T19:55:43Z"
  }
}
```

### Notes
- You should poll this endpoint at intervals (e.g., every 5 seconds) until the `status` is one of the terminal states: `finished`, `skipped`, or `cancelled`.
```

--------------------------------

### Local Testing Bash Script

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/FREESTYLE_MCP_SETUP.md

Commands to set up environment variables and run Mastra dev server and Next.js for local testing of MCP integration. This allows for simulating the production environment and testing agent creation and tool loading.

```bash
# 1. Set environment variables
export FREESTYLE_API_KEY=your_key
export NEON_API_KEY=your_key
export ANTHROPIC_API_KEY=your_key
# ... other vars

# 2. Run Mastra dev server
npm run mastra:dev

# 3. In another terminal, run Next.js
npm run dev

# 4. Create a project and send a chat message
# Check logs to see MCP client creation and tool loading
```

--------------------------------

### Get Agent Reference using Mastra

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_AGENTS.md

Obtain a reference to an agent using the `.getAgent()` method on a `mastra` or `mastraClient` instance. This is preferred over direct import as it preserves Mastra instance configuration.

```typescript
const testAgent = mastra.getAgent("testAgent");
```

--------------------------------

### Starting a Workflow Run with Multiple Inputs in TypeScript

Source: https://github.com/andrelandgraf/aileen/blob/main/docs/MASTRA_WORKFLOW.md

Initiate a workflow run with multiple input data sets. Each input will be processed sequentially through the defined steps, demonstrated here with a 'testWorkflow'.

```typescript
import { mastra } from "./mastra";

const run = await mastra.getWorkflow("testWorkflow").createRunAsync();

const result = await run.start({
  inputData: [{ number: 10 }, { number: 100 }, { number: 200 }],
});
```