# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for TextQL v2 Sandcastles API
  version: 1.0.0
extends: openapi/textql-sandcastles-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/v2/sandcastles'].get
  update:
    x-apievangelist-phrasing:
      intent: List my organization's sandcastles
      effect: read
      questions:
      - Which Python sandcastles are running in my TextQL organization?
      - Can I list only stopped sandboxes?
      - Why might a sandbox that crashed still show as running for a while?
      instructions:
      - text: List sandcastles with status {status}.
        slots:
          status: query.status
      - text: Show the next {limit} sandcastles after cursor {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles'].post
  update:
    x-apievangelist-phrasing:
      intent: Start or restart a sandcastle
      effect: write
      questions:
      - How do I spin up a fresh Python sandbox for running code?
      - Can I restart an existing sandcastle instead of creating a new one?
      instructions:
      - text: Start a new sandcastle.
      - text: Restart sandcastle {sandbox_id}.
        slots:
          sandbox_id: requestBody.sandbox_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a sandcastle's status and memory
      effect: read
      questions:
      - How much memory is my sandbox using right now?
      - Which dataframes are loaded in a sandcastle?
      instructions:
      - text: Get the status of sandcastle {id}.
        slots:
          id: path.id
      - text: Show memory usage and loaded dataframes for sandbox {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop and destroy a sandcastle
      effect: destructive
      questions:
      - How do I shut down a sandcastle I'm done with?
      - Can I still read a sandbox's execution history after it is stopped?
      instructions:
      - text: Stop sandcastle {id}.
        slots:
          id: path.id
      - text: Destroy the running sandbox {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/executions'].get
  update:
    x-apievangelist-phrasing:
      intent: List executions run in a sandcastle
      effect: read
      questions:
      - What code has been run in my sandcastle so far?
      - Does the execution log include SQL and bash runs as well as Python?
      instructions:
      - text: List executions in sandcastle {id}.
        slots:
          id: path.id
      - text: Show the latest {limit} runs in sandbox {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Run Python code in a sandcastle
      effect: write
      questions:
      - How do I run Python in a sandcastle and get stdout back?
      - Does Python run in a persistent kernel so variables survive between calls?
      instructions:
      - text: Run Python {code} in sandcastle {id}.
        slots:
          code: requestBody.code
          id: path.id
      - text: 'Execute this Python snippet in sandbox {id}: {code}'
        slots:
          id: path.id
          code: requestBody.code
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/query'].post
  update:
    x-apievangelist-phrasing:
      intent: Load connector data into a sandcastle dataframe
      effect: write
      questions:
      - How do I pull query results from a connector into a sandbox dataframe?
      - Can I run a saved .tql file instead of inline SQL when loading data?
      - Is there a cap on how many rows get loaded into the dataframe?
      instructions:
      - text: Load {query} from connector {connector_id} into sandcastle {id}.
        slots:
          query: requestBody.query
          connector_id: requestBody.connector_id
          id: path.id
      - text: Run saved TQL {tql_path} on connector {connector_id} into dataframe {dataframe_name} in sandbox {id}.
        slots:
          tql_path: requestBody.tql_path
          connector_id: requestBody.connector_id
          dataframe_name: requestBody.dataframe_name
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List files in a sandcastle directory
      effect: read
      questions:
      - What files are in my sandbox's working directory?
      - Can I browse a subfolder of the sandcastle, like the mounted library?
      instructions:
      - text: List files in sandcastle {id}.
        slots:
          id: path.id
      - text: List the {path} directory inside sandbox {id}.
        slots:
          path: query.path
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file to a sandcastle
      effect: write
      questions:
      - How do I put a CSV into my sandbox so Python can read it?
      - Can I upload a file directly into a sandcastle's working directory?
      instructions:
      - text: Upload {file} to sandcastle {id}.
        slots:
          file: requestBody.file
          id: path.id
      - text: Send file {file} into sandbox {id}'s working directory.
        slots:
          file: requestBody.file
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/files/{path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a file from a sandcastle
      effect: read
      questions:
      - How do I download a chart or output file my sandbox generated?
      - Can I fetch a file from a nested folder in the sandcastle?
      instructions:
      - text: Download {path} from sandcastle {id}.
        slots:
          path: path.path
          id: path.id
      - text: Fetch the bytes of file {path} in sandbox {id}.
        slots:
          path: path.path
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/files/{path}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a file from a sandcastle
      effect: destructive
      questions:
      - How do I remove a file from my sandbox's working directory?
      - Can I delete a whole directory in a sandcastle with one call?
      instructions:
      - text: Delete {path} from sandcastle {id}.
        slots:
          path: path.path
          id: path.id
      - text: Remove file {path} in sandbox {id}.
        slots:
          path: path.path
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/exec'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a one-shot shell command in a sandcastle
      effect: write
      questions:
      - Can I run a bash command in my sandbox as a fresh process?
      - Do shell commands share state with the Python kernel in a sandcastle?
      instructions:
      - text: Run command {command} in sandcastle {id}.
        slots:
          command: requestBody.command
          id: path.id
      - text: Exec {command} in sandbox {id} with environment {env}.
        slots:
          command: requestBody.command
          id: path.id
          env: requestBody.env
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/ontology/diff'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview pending Ontology edits in a sandcastle
      effect: read
      questions:
      - Has my sandbox changed any files in its mounted Ontology library?
      - Can I dry-run the diff before writing sandbox edits back to the Ontology?
      instructions:
      - text: Diff the Ontology mount in sandcastle {id}.
        slots:
          id: path.id
      - text: Show pending library changes in sandbox {id} without authoring a change.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/sandcastles/{id}/ontology/changes'].post
  update:
    x-apievangelist-phrasing:
      intent: Write sandcastle Ontology edits back as a change
      effect: write
      questions:
      - How do I save library edits from my sandbox back to the organization's Ontology?
      - Can I open the writeback change as a draft for review?
      instructions:
      - text: Create an Ontology change from sandcastle {id} titled {title}.
        slots:
          id: path.id
          title: requestBody.title
      - text: Write back sandbox {id}'s library edits as a draft described as {description}.
        slots:
          id: path.id
          description: requestBody.description
      method: generated
      generated: '2026-10-01'