Osmosis knowledge API

openapi: 3.2.0
info:
  title: Osmosis Improvement agent Knowledge API
  description: Improve agentic improvements by learning from past interactions
  version: 1.0.0
servers:
- url: https://api.osmosis.ai
  description: Base URL declared by the provider in apis.yml (roadmap#122).
security:
- ApiKeyAuth: []
tags:
- name: knowledge
  description: Operations for managing the knowledge base
paths:
  /store_knowledge:
    post:
      tags:
      - knowledge
      summary: Store Knowledge
      description: "Store and process agent interaction knowledge asynchronously.\n\nThis endpoint accepts knowledge about agent interactions and queues it for background\nprocessing. The processing pipeline analyzes the interaction, generates insights,\nand stores them for future use.\n\nArgs:\n    knowledge: Details about the agent interaction including:\n        - tenant_id: Tenant identifier for organization/project\n        - query: The user's original query/request\n        - turns: List of interaction turns between user and agent\n        - success: Whether the interaction achieved the user's goal\n        - agent_type: Type of agent that handled the interaction\n        - timestamp: When the interaction occurred (ISO format)\n    background_tasks: FastAPI background tasks handler for async processing\n\nReturns:\n    Dict containing:\n        - status: \"accepted\"\n        - message: Processing acknowledgement\n        - tenant_id: The tenant ID from the request\n\nNotes:\n    - Each turn should capture the key decision points and context\n    - The memory field helps track the agent's understanding\n    - Success should reflect whether the user's goal was achieved\n    - Timestamp should be in ISO 8601 format\n    - Agent type helps categorize different interaction patterns\n\nRaises:\n    HTTPException(500): If there is an error queueing the knowledge"
      operationId: store_knowledge_store_knowledge_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentKnowledgeUpload'
              description: Agent interaction knowledge to store
            examples:
              browser_agent_example:
                summary: Example of a browser agent interaction
                description: A successful interaction where a browser agent helps find and purchase a product
                value:
                  tenant_id: webarena
                  query: Find and purchase a red Nike running shoe in size 10
                  turns:
                  - turn: 1
                    inputs: On shopping website homepage. Need to search for red Nike running shoes.
                    decision: '{''action_type'': ''click'', ''element_name'': ''search_bar'', ''text'': [''Nike red running shoes''], ''element_role'': ''searchbox'', ''coords'': [120, 35], ''url'': ''https://shop.example.com''}'
                    result: click [120, 35] where [120, 35] is searchbox 'Search products...' followed by typing 'Nike red running shoes'
                    memory: User wants red Nike running shoes. Starting search from homepage.
                  - turn: 2
                    inputs: Search results show multiple Nike running shoes. Need to select size 10 in red.
                    decision: '{''action_type'': ''click'', ''element_name'': ''product_link'', ''text'': [''Nike Air Zoom Pegasus - Red''], ''element_role'': ''link'', ''coords'': [250, 320], ''url'': ''https://shop.example.com/products/nike-air-zoom-pegasus?color=red&size=10''}'
                    result: click [250, 320] where [250, 320] is link 'Nike Air Zoom Pegasus - Red' in size 10 with 4.8/5 stars (2,453 reviews)
                    memory: Selected Pegasus model in red, size 10 based on positive reviews and exact match to requirements
                  success: 'true'
                  agent_type: browser
                  timestamp: '2024-03-14T10:30:00Z'
                  metadata:
                    browser_type: chrome
                    site: shopping_admin
                    interaction_duration_seconds: 120
                    user_satisfaction_score: 0.95
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Store Knowledge Store Knowledge Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /delete_by_intent:
    post:
      tags:
      - knowledge
      summary: Delete By Intent
      description: "Delete documents from the knowledge store based on intent similarity.\n\nThis endpoint:\n1. Takes an intent and tenant_id\n2. Searches for documents with similar intent using the default similarity threshold\n3. Deletes matching documents\n4. Returns the count of deleted documents\n\nArgs:\n    tenant_id: The tenant identifier\n    intent: The intent to match against\n    similarity_threshold: Optional threshold for similarity matching\n\nReturns:\n    Dict containing:\n        - deleted_count: Number of documents deleted\n        - status: Operation status message\n\nRaises:\n    HTTPException: If deletion fails"
      operationId: delete_by_intent_delete_by_intent_post
      parameters:
      - name: tenant_id
        in: query
        required: true
        schema:
          type: string
          title: Tenant Id
      - name: intent
        in: query
        required: true
        schema:
          type: string
          title: Intent
      - name: similarity_threshold
        in: query
        required: false
        schema:
          anyOf:
          - type: number
          - type: 'null'
          description: Optional similarity threshold for matching documents
          default: 0.5
          title: Similarity Threshold
        description: Optional similarity threshold for matching documents
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Delete By Intent Delete By Intent Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /knowledge_status/{job_id}:
    get:
      tags:
      - knowledge
      summary: Knowledge Status
      description: "Get the status of a knowledge upload job.\n\nArgs:\n    job_id: The job ID for the knowledge upload, passed as path parameter"
      operationId: knowledge_status_knowledge_status__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Knowledge Status Knowledge Status  Job Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentTurn:
      properties:
        turn:
          type: integer
          title: Turn
          description: The turn number in the interaction
        inputs:
          type: string
          title: Inputs
          description: The flattened input the agent sees
        decision:
          type: string
          title: Decision
          description: The output/action of the agent
        memory:
          anyOf:
          - type: string
          - type: 'null'
          title: Memory
          description: What the agent remembers from this turn
        result:
          anyOf:
          - type: string
          - type: 'null'
          title: Result
          description: The result of the action
      type: object
      required:
      - turn
      - inputs
      - decision
      title: AgentTurn
      description: Represents a single turn in an agent's interaction.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AgentKnowledgeUpload:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
          description: Unique identifier for the tenant/user
        query:
          type: string
          title: Query
          description: The original user query or instruction
        turns:
          items:
            $ref: '#/components/schemas/AgentTurn'
          type: array
          title: Turns
          description: The sequence of agent turns
        success:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Success
          description: Whether the agent completed its task successfully
        agent_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Type
          description: Type of agent (e.g., 'browser', 'voice')
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        metadata:
          anyOf:
          - type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - tenant_id
      - query
      - turns
      title: AgentKnowledgeUpload
      description: Represents uploaded knowledge about agent interactions.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key