Seekr Explainability API

openapi: 3.2.0
info:
  title: SeekrFlow Explainability API
  description: SeekrFlow API Documentation
  termsOfService: http://www.seekr.com/support
  contact:
    name: Seekr API Support
    url: http://www.seekr.com/contact
    email: contact@seekr.com
  version: 5.17.1
servers:
- url: https://flow.seekr.com
  description: SeekrBuild server base URL
tags:
- name: Explainability
paths:
  /v1/explainability/context-attributor:
    post:
      tags:
      - Explainability
      summary: Get Context Attribution
      description: 'Compute context attribution scores for a model response.


        Determines which parts of the provided context contributed to the model''s response

        using the ContextCite algorithm.


        Required fields:

        - context: The context text that was provided to the model

        - query: The user''s query/question

        - response: The model''s response to attribute


        Optional fields:

        - model: Model name for attribution computation (default: Llama-3.1-8B-Instruct)

        - highlight: Specific portion of response to attribute. If omitted,

        returns attributions for all response segments.

        - granularity: Context partitioning granularity (sentence/chunk)

        - top_k: Number of top sources to return per segment

        - num_ablations (32-256): Advanced tuning


        Returns:

        ContextAttributionResult with either:

        - Single-highlight format (when highlight provided): response_text, highlight, sources

        - Segment-based format (when highlight omitted): response_text, segments[]'
      operationId: get_context_attribution_v1_explainability_context_attributor_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextAttributionRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextAttributionResult'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /v1/explainability/context-attributor-from-run:
    post:
      tags:
      - Explainability
      summary: Get Context Attribution From Run
      description: 'Compute context attribution scores from an agent run.


        Extracts context (tool results from message parts, or logfire spans as a SaaS

        fallback), the agent''s system prompt (from ``agent.instructions``), the query

        (user input), and the response (assistant output), then runs context

        attribution analysis.


        Required fields:

        - thread_id: ID of the thread to analyze


        Optional fields:

        - run_id: If not provided, uses the latest completed run

        - highlight: Specific portion of response to attribute

        - granularity: Context partitioning granularity (sentence/chunk)

        - top_k: Number of top sources to return per segment


        Returns:

        ContextAttributionResult with either:

        - Single-highlight format (when highlight provided): response_text, highlight, sources

        - Segment-based format (when highlight omitted): response_text, segments[]


        Raises:

        404: If no completed run or spans found

        422: If no user query or assistant response found'
      operationId: get_context_attribution_from_run_v1_explainability_context_attributor_from_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextAttributionFromRunRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextAttributionResult'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
components:
  schemas:
    MCPToolContent:
      properties:
        type:
          type: string
          const: mcp_tool
          title: Type
          default: mcp_tool
        tool_name:
          type: string
          title: Tool Name
        tool_input:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tool Input
          description: The args sent to the tool (e.g. the prompt passed to a subagent). Truncated to ~2k chars when serialized; mirrors the sensitivity classification of the underlying run.
      type: object
      required:
      - tool_name
      title: MCPToolContent
      description: 'Content for generic MCP tool calls.


        This is the canonical type for any tool call that does not have a

        dedicated first-class handler (web_search, file_search,

        code_interpreter). In practice this covers all MCP tools, including

        "agents as tools" (subagents) — at the persistence layer those are

        indistinguishable from any other MCP tool call.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CodeInterpreterToolContent:
      properties:
        type:
          type: string
          const: code_interpreter
          title: Type
          default: code_interpreter
        code:
          type: string
          title: Code
      type: object
      required:
      - code
      title: CodeInterpreterToolContent
      description: Content specific to code interpreter sources.
    SystemPromptSource:
      properties:
        source_type:
          type: string
          const: system_prompt
          title: Source Type
          default: system_prompt
        id:
          type: integer
          title: Id
          description: Index of this source in the system prompt partition.
        text:
          type: string
          title: Text
          description: The source text content (a sentence or chunk of the system prompt).
        attribution:
          type: number
          title: Attribution
          description: Attribution score in range (-1, 1). Positive values indicate support.
        offset:
          type: integer
          title: Offset
          description: Character offset of this source within the system prompt string.
      type: object
      required:
      - id
      - text
      - attribution
      - offset
      title: SystemPromptSource
      description: 'A context source that originated from the agent''s system prompt.


        Indicates that the response segment was influenced by the agent''s

        operator-defined instructions rather than retrieved documents or tool outputs.

        Character offsets are relative to the system prompt string itself.'
    FromRunGranularityType:
      type: string
      enum:
      - sentence
      - chunk
      title: FromRunGranularityType
      description: Granularity for /context-attributor-from-run endpoint.
    ToolResponseSource:
      properties:
        source_type:
          type: string
          const: tool_response
          title: Source Type
          default: tool_response
        id:
          type: integer
          title: Id
          description: Index of this source in the original context partition.
        text:
          type: string
          title: Text
          description: The source text content.
        attribution:
          type: number
          title: Attribution
          description: Attribution score in range (-1, 1). Positive values indicate support.
        offset:
          type: integer
          title: Offset
          description: Character offset of this source in the original context.
        tool_name:
          type: string
          title: Tool Name
          description: Name of the tool that produced this source.
        tool_call_id:
          type: string
          title: Tool Call Id
          description: Unique identifier for the tool call.
        tool:
          oneOf:
          - $ref: '#/components/schemas/WebSearchToolContent'
          - $ref: '#/components/schemas/FileSearchToolContent'
          - $ref: '#/components/schemas/CodeInterpreterToolContent'
          - $ref: '#/components/schemas/MCPToolContent'
          title: Tool
          description: Tool-specific metadata and content.
          discriminator:
            propertyName: type
            mapping:
              code_interpreter: '#/components/schemas/CodeInterpreterToolContent'
              file_search: '#/components/schemas/FileSearchToolContent'
              mcp_tool: '#/components/schemas/MCPToolContent'
              web_search: '#/components/schemas/WebSearchToolContent'
      type: object
      required:
      - id
      - text
      - attribution
      - offset
      - tool_name
      - tool_call_id
      - tool
      title: ToolResponseSource
      description: 'A context source that originated from a tool call.


        This model contains the core attribution fields plus tool-specific metadata

        nested in the `tool` field.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ContextAttributionRequest:
      properties:
        context:
          type: string
          title: Context
          description: The context text provided to the model.
        query:
          type: string
          title: Query
          description: The user's question/query.
        response:
          type: string
          title: Response
          description: The model's response to attribute.
        highlight:
          anyOf:
          - type: string
          - type: 'null'
          title: Highlight
          description: Specific portion of response to attribute. If None, attributes all segments.
        granularity:
          $ref: '#/components/schemas/BaseGranularityType'
          description: 'Granularity for partitioning context: sentence or paragraph.'
          default: sentence
        top_k:
          type: integer
          minimum: 1
          title: Top K
          description: Number of top attributed sources to return per segment.
          default: 5
        num_ablations:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Ablations
          description: Number of ablation experiments to run. If None, computed dynamically using O(k log d) formula. Must be between 32 and 256 (inclusive) if specified.
        return_diagnostics:
          type: boolean
          title: Return Diagnostics
          description: If True, include diagnostic information in the response.
          default: false
      type: object
      required:
      - context
      - query
      - response
      title: ContextAttributionRequest
      description: 'Request model for context attribution.


        Computes which parts of the context contributed to the model''s response

        using the ContextCite algorithm.'
    WebSearchToolContent:
      properties:
        type:
          type: string
          const: web_search
          title: Type
          default: web_search
        url:
          type: string
          title: Url
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        search_query:
          type: string
          title: Search Query
      type: object
      required:
      - url
      - search_query
      title: WebSearchToolContent
      description: Content specific to web search sources.
    SegmentAttribution:
      properties:
        segment_index:
          type: integer
          title: Segment Index
          description: Index of this segment in the response (0-based).
        segment_text:
          type: string
          title: Segment Text
          description: The text content of this segment.
        char_offset:
          type: integer
          title: Char Offset
          description: Character offset of this segment in the response.
        sources:
          items:
            oneOf:
            - $ref: '#/components/schemas/ToolResponseSource'
            - $ref: '#/components/schemas/RawContextSource'
            - $ref: '#/components/schemas/SystemPromptSource'
            discriminator:
              propertyName: source_type
              mapping:
                raw: '#/components/schemas/RawContextSource'
                system_prompt: '#/components/schemas/SystemPromptSource'
                tool_response: '#/components/schemas/ToolResponseSource'
          type: array
          title: Sources
          description: Context sources attributed to this segment.
      type: object
      required:
      - segment_index
      - segment_text
      - char_offset
      - sources
      title: SegmentAttribution
      description: Attribution results for a single response segment (e.g., a sentence).
    ContextAttributionResult:
      properties:
        response_text:
          type: string
          title: Response Text
          description: The full response text that was attributed.
        segments:
          items:
            $ref: '#/components/schemas/SegmentAttribution'
          type: array
          title: Segments
          description: Attribution results for each response segment. Populated when highlight is not provided.
          default: []
        highlight:
          anyOf:
          - type: string
          - type: 'null'
          title: Highlight
          description: The highlighted portion of the response (if provided in request).
        sources:
          anyOf:
          - items:
              oneOf:
              - $ref: '#/components/schemas/ToolResponseSource'
              - $ref: '#/components/schemas/RawContextSource'
              - $ref: '#/components/schemas/SystemPromptSource'
              discriminator:
                propertyName: source_type
                mapping:
                  raw: '#/components/schemas/RawContextSource'
                  system_prompt: '#/components/schemas/SystemPromptSource'
                  tool_response: '#/components/schemas/ToolResponseSource'
            type: array
          - type: 'null'
          title: Sources
          description: Context sources for the highlight. Only populated when highlight is provided.
        diagnostics:
          anyOf:
          - $ref: '#/components/schemas/ContextAttributionDiagnostics'
          - type: 'null'
          description: Diagnostic information. Only populated when return_diagnostics=True.
      type: object
      required:
      - response_text
      title: ContextAttributionResult
      description: Response model for context attribution.
    ContextAttributionDiagnostics:
      properties:
        num_sources:
          type: integer
          title: Num Sources
          description: Number of context sources after partitioning.
        num_ablations:
          type: integer
          title: Num Ablations
          description: Number of ablation experiments performed.
        lasso_alpha:
          type: number
          title: Lasso Alpha
          description: LASSO regularization strength used.
        mask_probability:
          type: number
          title: Mask Probability
          description: Probability of including each source in ablations.
        y_vector_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Y Vector Stats
          description: Statistics of the aggregated Y vector (mean, std, min, max, range).
        raw_coef_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Raw Coef Stats
          description: Statistics of raw LASSO coefficients before tanh (min, max, absmax, nonzero, sparsity).
        scaler_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Scaler Stats
          description: StandardScaler statistics (mean, scale arrays).
      type: object
      required:
      - num_sources
      - num_ablations
      - lasso_alpha
      - mask_probability
      title: ContextAttributionDiagnostics
      description: Diagnostic information for context attribution debugging.
    FileSearchToolContent:
      properties:
        type:
          type: string
          const: file_search
          title: Type
          default: file_search
        file_path:
          anyOf:
          - type: string
          - type: 'null'
          title: File Path
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
        query:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
      type: object
      title: FileSearchToolContent
      description: Content specific to file search sources.
    BaseGranularityType:
      type: string
      enum:
      - sentence
      - paragraph
      title: BaseGranularityType
      description: Granularity for /context-attributor endpoint.
    ContextAttributionFromRunRequest:
      properties:
        thread_id:
          type: string
          title: Thread Id
          description: ID of the thread to analyze.
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
          description: Optional run ID. If not provided, uses the latest completed run.
        highlight:
          anyOf:
          - type: string
          - type: 'null'
          title: Highlight
          description: Specific portion of response to attribute. If None, attributes all segments.
        granularity:
          $ref: '#/components/schemas/FromRunGranularityType'
          description: 'Granularity for partitioning context: sentence or chunk.'
          default: sentence
        top_k:
          type: integer
          minimum: 1
          title: Top K
          description: Number of top attributed sources to return per segment.
          default: 5
        num_ablations:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Ablations
          description: Number of ablation experiments to run. If None, computed dynamically using O(k log d) formula. Must be between 32 and 256 (inclusive) if specified.
        return_diagnostics:
          type: boolean
          title: Return Diagnostics
          description: If True, include diagnostic information in the response.
          default: false
      type: object
      required:
      - thread_id
      title: ContextAttributionFromRunRequest
      description: Request model for context attribution from an agent run. Extracts the context, query, and response from the run, then computes attribution scores across the retrieved sources.
    RawContextSource:
      properties:
        source_type:
          type: string
          const: raw
          title: Source Type
          default: raw
        id:
          type: integer
          title: Id
          description: Index of this source in the original context partition.
        text:
          type: string
          title: Text
          description: The source text content.
        attribution:
          type: number
          title: Attribution
          description: Attribution score in range (-1, 1). Positive values indicate support.
        offset:
          type: integer
          title: Offset
          description: Character offset of this source in the original context.
      type: object
      required:
      - id
      - text
      - attribution
      - offset
      title: RawContextSource
      description: 'A context source from raw context (not from a tool).


        This model is used for context that was provided directly, not retrieved

        by a tool call.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      description: Your Seekr API key, sent in the Authorization header with no 'Bearer' prefix.
      in: header
      name: Authorization