version: v2
kind: Spicepod
name: spice-oss-docs

datasets:
  - from: github:github.com/spiceai/docs/files/trunk
    name: spiceai.docs
    description: Spice.ai OSS documentation and reference, from https://docs.spiceai.org
    metadata:
      instructions: |
        Documents are stored in Markdown. Always provide citations.
        When generating reference links for docs, use https://docs.spiceai.org/<docs_path> as a template
        Exclude `website/docs` prefix from docs path and `.md` file extension.
        Also replace `/index.md` with `/` in the path.
      reference_base_url: https://docs.spiceai.org/<docs_path>
    params:
      file_format: md
      github_client_id: ${secrets:GITHUB_CLIENT_ID}
      github_private_key: ${secrets:GITHUB_PRIVATE_KEY}
      github_installation_id: ${secrets:GITHUB_INSTALLATION_ID}
      include: 'website/docs/**/*.md'
    acceleration:
      enabled: true
      refresh_check_interval: 4h
      refresh_jitter_enabled: true
      refresh_jitter_max: 30m
    columns:
      - name: content
        embeddings:
          - from: openai_embeddings
            row_id:
              - path
            chunking:
              enabled: true
              target_chunk_size: 512
              overlap_size: 128
              trim_whitespace: true

  - from: github:github.com/spiceai/cookbook/files/trunk
    name: spiceai.cookbook
    description: Spice.ai OSS cookbook recipes
    metadata:
      instructions: Documents are stored in Markdown. Always provide citations.
      reference_base_url: https://github.com/spiceai/cookbook/tree/trunk/<recipe_path>
    params:
      file_format: md
      github_client_id: ${secrets:GITHUB_CLIENT_ID}
      github_private_key: ${secrets:GITHUB_PRIVATE_KEY}
      github_installation_id: ${secrets:GITHUB_INSTALLATION_ID}
      include: '**/*.md'
    acceleration:
      enabled: true
      refresh_check_interval: 4h
      refresh_jitter_enabled: true
      refresh_jitter_max: 30m
    columns:
      - name: content
        embeddings:
          - from: openai_embeddings
            row_id:
              - path
            chunking:
              enabled: true
              target_chunk_size: 512
              overlap_size: 128
              trim_whitespace: true

  - from: github:github.com/spiceai/docs/files/trunk
    name: spiceai.releases
    description: Spice.ai OSS release notes
    metadata:
      instructions: |
        This dataset provides access to the Spice.ai OSS project release notes in Markdown format. The content is sourced from the Spice.ai OSS blog repository at https://github.com/spiceai/blog.
      reference_base_url: https://github.com/spiceai/docs/tree/trunk/website/releases/<post_path>
    params:
      file_format: md
      github_client_id: ${secrets:GITHUB_CLIENT_ID}
      github_private_key: ${secrets:GITHUB_PRIVATE_KEY}
      github_installation_id: ${secrets:GITHUB_INSTALLATION_ID}
      include: 'website/releases/**/*.md'
    acceleration:
      enabled: true
      refresh_check_interval: 4h
      refresh_jitter_enabled: true
      refresh_jitter_max: 30m
    columns:
      - name: content
        embeddings:
          - from: openai_embeddings
            row_id:
              - path
            chunking:
              enabled: true
              target_chunk_size: 512
              overlap_size: 128
              trim_whitespace: true

  - from: github:github.com/spiceai/spiceai/issues
    name: spiceai.issues
    description: Spice.ai OSS issues from https://github.com/spiceai/spiceai/issues
    params:
      github_client_id: ${secrets:GITHUB_CLIENT_ID}
      github_private_key: ${secrets:GITHUB_PRIVATE_KEY}
      github_installation_id: ${secrets:GITHUB_INSTALLATION_ID}
    acceleration:
      enabled: true
      refresh_check_interval: 4h
      refresh_jitter_enabled: true
      refresh_jitter_max: 30m

embeddings:
  - from: openai
    name: openai_embeddings
    params:
      openai_api_key: ${ secrets:OPENAI_API_KEY }

models:
  - name: assistant
    from: openai:gpt-4o
    params:
      tools: auto
      openai_api_key: ${secrets:OPENAI_API_KEY}
      system_prompt: |
        You are an AI assistant assisting engineers with the Spice.ai OSS Project.

        Always strive to be accurate, concise, and helpful in your responses.

        Apply instructions and reference_base_url metadata from the datasets to provide accurate and relevant information.

        Prefer "docs" dataset for documentation and reference information questions.

        Prefer "cookbook" recipe datasets for use cases, sample code, and configuration questions. Always include links to relevant recipes.

        Use the SQL tool (sql_query) when:
          1. The query involves precise numerical data, statistics, or aggregations.
          2. The user asks for specific counts, sums, averages, or other calculations.
          3. The query requires joining or comparing data from multiple related tables.

        If the SQL tool returns a query, syntax, or planning error, call the `list_datasets` tool to get the available tables and continue to refine and retry the query until it succeeds. If the query fails after 5 attempts, on each subsequent run `EXPLAIN <query>` to better understand what went wrong. If it continues to fail after 10 attempts, fall back to other available tools.

        When returning results from datasets, always provide citations and reference links if possible.

        Use the document search tool when:
          1. The query is about unstructured text information, such as policies, reports, or articles.
          2. The user is looking for qualitative information or explanations.
          3. The query requires understanding context or interpreting written content.

        General guidelines:
          1. If a query could be answered by either tool, prefer SQL for more precise, quantitative answers.

  - name: docs_writer
    from: openai:gpt-4o
    params:
      tools: auto
      openai_api_key: ${secrets:OPENAI_API_KEY}
      system_prompt: |
        You are an AI assistant helping contributors to the Spice.ai open-source project write documentation, release notes, and blog posts.

        **Write clearly, concisely, and precisely for a developer audience.**
        Use objective third-person tense. Do not use “I” or “we” unless explicitly quoting or summarizing subjective viewpoints. Avoid vague qualifiers and revise text to maximize clarity, structure, and factual accuracy. Every sentence should reflect critical thinking and organized reasoning.

        Ensure that all documentation adheres to the project's style guide and includes relevant examples where applicable.

        **Be specific. Prioritize detail without being verbose.**
        Use plain, direct language. Avoid jargon, exaggeration, and promotional tone.

        **Do not use the following words or their variants:**
        - delve
        - seamlessly
        - empower / empowering
        - supercharge
        - countless
        - enhance / enhancing
        - allow / allowing (Use “helps” or “enables” when appropriate.)

        **Always provide citations and references with links when applicable.**

        Your output should read like a well-edited technical paper: factual, sharp, and to the point.

        Always output Markdown in plain text for copy.