@gsa-tts/graymatter-ui 0.3.13 → 0.3.15

package/src/content/api/endpoints.mdx

@@ -0,0 +1,174 @@
+---
+title: 'Endpoints'
+description: ''
+sortOrder: 20
+---
+
+API endpoints will be available when you login.
+
+### 1. Models
+
+GET /api/v1/models
+
+To reach models the documented endpoint is `<base url>/api/v1/models`, which will allow you to retrieve available model information.  
+
+**Example Request**
+
+```bash
+curl -X 'GET' \
+'<base url>/api/v1/models' \
+-H 'accept: application/json' \
+-H 'Authorization: Bearer <Your API Key>'
+```
+**Example Response**
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "claude_3_5_sonnet",
+      "created": 1718841600,
+      "object": "model",
+      "owned_by": "Anthropic"
+    },
+    {
+      "id": "llama3211b",
+      "created": 1727222400,
+      "object": "model",
+      "owned_by": "Meta"
+    },
+    {
+      "id": "cohere_english_v3",
+      "created": 1698883200,
+      "object": "model",
+      "owned_by": "Cohere"
+    }
+  ]
+}
+```
+### 2. Chat Completions
+
+POST /api/v1/chat/completions
+
+To reach chat completions the documented endpoint is `<base url>/api/v1/chat/completions`, which will allow you to retrieve chat completion information. 
+
+**Request Body**
+
+* **model**: The model ID (e.g: gemini-2.0-flash, claude_3_haiku)
+* **messages**: An array of of message items consisting of User message, Image Content, Document Content, Assistant Message
+* **max_tokens**: Maximum response length (optional)
+* **temperature**: Response creativity (0.0-2.0, optional)
+
+| **Models** | **Range** | **Default value** |
+| :------- | :------: | -------: |
+| Google models | 0.0 - 2.0 | 1.0 |
+| Anthropic models | 0.0 - 1.0 | 0.5 |
+| Meta models | 0.0 - 1.0 | 0.5 |
+
+* **top_p**: An alternative to sampling with temperature, called nucleus sampling (optional)
+* **stream**: a boolean indicating whether to send partials responses as available (optional)
+
+**Example Request**
+
+```bash
+curl -X 'POST' \
+'<base url>/api/v1/chat/completions' \
+-H 'accept: application/json' \
+-H 'Authorization: Bearer <Your API Key>' \
+-H 'Content-Type: application/json' \
+-d '{
+  "messages": [
+    {
+      "content": "You speak only pirate",
+      "role": "system"
+    },
+    {
+      "content": "Hello!",
+      "role": "user"
+    }
+  ],
+  "model": "gemini-2.0-flash"
+}'
+```
+
+**Example Response**
+
+```json
+{
+   "object": "chat.completion",
+   "created": 1748517745,
+   "model": "gemini-2.0-flash",
+   "choices": [
+      {
+        "index": 0,
+        "message": {
+           "role": "assistant",
+           "content": "Ahoy there, matey! What brings ye to me waters?\n"
+        },
+       "finish_reason": "stop"
+    }
+  ],
+  "usage": {
+       "prompt_tokens": 14,
+       "completion_tokens": 15,
+      "total_tokens": 29
+  }
+}
+
+```
+
+### 3. Embeddings
+
+POST /api/v1/embeddings
+
+To reach embeddings the documented endpoint is `<base url>/api/v1/embeddings`, which will allow you to retrieve embeddings information.  
+
+**Request Body**
+
+* **model:** The model ID (e.g: cohere_english_v3)
+* **input:** Input text to embed, encoded as a string or array of strings. Each input must not exceed the max input tokens for the model.
+dimensions: The number of dimensions the resulting output embeddings should have. Only supported in some models (Optional)
+* **input_type:** (Note: this is not part of the OpenAI specification but is useful on some models). Specify the kind of input to allow the model to optimize for specific uses. Options are: "search_document", "search_query",   "classification", "clustering", "semantic_similarity" (Optional)
+
+**Example Request**
+
+```bash
+curl -X 'POST' \
+'<base url>/api/v1/embeddings' \
+-H 'accept: application/json' \
+-H 'Authorization: Bearer <Your API Key>\
+-H 'Content-Type: application/json' \
+-d '{
+    "encodingFormat": "float",
+    "input": "A mighty woman with a torch, whose flame / Is the imprisoned lightning",
+    "input_type": "search_document",
+    "model": "cohere_english_v3"
+}
+```
+**Example Response**
+
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "embedding",
+      "embedding": [
+        0.06933594,
+        -0.030883789,
+        0.054351807,
+        -0.0018196106,
+       …
+        0.013938904
+      ],
+      "index": 0
+    }
+  ],
+  "model": "cohere.embed-english-v3",
+  "usage": {
+    "promptTokens": 12,
+    "totalTokens": 12
+  }
+}
+```

package/src/content/api/getting-started.mdx

@@ -0,0 +1,84 @@
+---
+title: 'Getting Started'
+description: ''
+sortOrder: 10
+---
+
+### Introduction
+
+USAi API provides programmatic access to AI services for government users and approved partners. It currently supports Chat Completions (model inference) and Embeddings (used for RAG and other applications). 
+
+Our API has resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses HTTP response codes to indicate API errors, authentication messaging, and verbs. 
+
+### Models and endpoints 
+
+USAi API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) and provides access to the large language models (LLMs):
+
+**Google AI models**
+- [Gemini 2.5 Flash](https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash)
+- [Gemini 2.5 Pro](https://ai.google.dev/gemini-api/docs/models#gemini-2.5-pro)
+
+**Anthropic models**
+- [Claude Haiku 3.5](https://docs.claude.com/en/docs/overview)
+- [Claude Sonnet 3.7](https://docs.claude.com/en/docs/overview)
+- [Claude Sonnet 4](https://docs.claude.com/en/docs/overview)
+- [Claude Opus 4](https://docs.claude.com/en/docs/overview)
+
+**Meta models**
+- [Llama 3.2 11B](https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_2/)
+- [Llama 4 Maverick](https://www.llama.com/docs/model-cards-and-prompt-formats/llama4/)
+
+The interface is modeled after the [OpenAI Chat Completion API](https://platform.openai.com/docs/guides/text?api-mode=responses). We will continue to add more models over time; we may also remove models if they are found to not meet our standards. You will be notified if a model is removed. 
+
+Each model we draw on has unique capabilities. Models may also respond differently to the same API request. Below is a summary of each endpoint’s functionality:
+
+- **Chat Completions:** The ability to send prompts and receive a response from the LLM models.
+- **Embedding:** Converts input into numeric vectors representing semantic meaning. The vectors are used for tasks like retrieving information from documents, document analysis, and building Retrieval Augmented Generation (RAG) systems.
+- **Models:** A list of models and IDs used to specify LLM models in requests.
+
+#### Content types
+
+The models USAi API draws on support multiple types of inputs; text, image, and file content types. However, each model has different input capabilities: for example, Claude Sonnet supports Optical Character Recognition (OCR) and recognizes image-only PDFs, while Claude Haiku and Llama currently do not. For additional detail about how we handle these content types, reference [OpenAI’s API documentation](https://platform.openai.com/docs/api-reference/chat/create). 
+
+### Authentication
+
+All API requests require an API key. Upon authentication, your agency-specific instructions for requesting an API key, and the API endpoint, will be available.
+
+### Limitations
+
+#### Rate limitations
+
+We currently have a rate limit of 3 calls / second / API key. If you hit a rate limit, you should expect a 429 error code. If you need additional capacity, please contact us at [support@usai.gov](mailto:support@usai.gov). We can work with our infrastructure providers to secure higher model limits.
+
+#### Feature limitations
+
+Because the underlying platforms have different capabilities and interfaces, not all features of the Chat Completions API are available at this time. Current known limitations include:
+
+- Audio
+- Structured output
+
+#### Guardrail limitations
+
+We do not have guardrails beyond those provided by our model providers; this means that an API user has full control over what inputs and outputs are allowed when using the API. We expect API users to interact with the API ethically and deliberately, and add their own guardrails and system prompts as needed. We recommend implementing system prompts when using the API in situations where you do not know what inputs the model will receive. 
+
+System prompts should address your needs and concerns. Some of the system prompts in USAi Chat include:
+- You are a helpful assistant that works for a government agency. 
+- You help users with general knowledge, problem-solving, coding, and interactive tasks.
+- You maintain a friendly, helpful, professional, and empathetic tone at all times.  
+- You want to understand the user's intent, and apply your knowledge and background to formulate the most helpful response possible.  
+- Redirect conversations that veer into inappropriate, illegal, or explicit territory.  
+- You're not an expert in government policies, security, safety, health, procurement, contracts, or law. Provide general guidance only and advise users to reference appropriate material.
+- Prioritize historical accuracy, scientific inquiry, and objectivity in all responses.
+- Break down complex questions and walk users through solutions step-by-step.
+- Use real-world analogies to simplify complex concepts.  
+- When the user's request is unclear, ask for more details to help refine your response.  
+- Ask users for feedback on the answer that can help you respond more accurately.
+- Never knowingly make false statements or deceive users.  
+- Avoid generating explicit, hateful, dangerous, or illegal content. 
+- Protect privacy and do not share personal information about individuals.  
+- Redirect users' requests around potentially controversial or polarizing topics quickly.  
+- You do not prefer or recommend specific political views, groups, religions, companies, products, or enterprise.
+
+### Code demo
+
+To see an example of how to implement features using Python, visit our [HTML example notebook](https://www.usai.gov/assets/files/jupyter_example.html). If you would like to run this file in a Jupyter environment, you can download the <a href="https://www.usai.gov/assets/files/jupyter_example.ipynb" download>notebook ipynb file</a>.

package/src/content/api/support.mdx

@@ -0,0 +1,10 @@
+---
+title: 'Support'
+description: ''
+sortOrder: 30
+---
+
+You may encounter issues while working with the USAi API, as it is under active development. We may not be able to fix all issues immediately, but will add them to our backlog for future releases. If you have any questions, hit rate limits, or otherwise need assistance, please contact us at [support@usai.gov](mailto:support@usai.gov).
+
+
+

package/src/layouts/BaseLayout.astro

@@ -18,3 +18,20 @@ const { title, description, openGraphImage, gtmID } = Astro.props;
     <slot />
   </body>
 </html>
+
+<script>
+  // Enhanced mobile focus handling - centralized for all layouts
+  if (typeof window !== 'undefined') {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Tab') {
+        document.body.classList.add('keyboard-user');
+        document.body.classList.remove('touch-user');
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+
+    // Initial state - assume touch user until Tab is pressed
+    document.body.classList.add('touch-user');
+  }
+</script>

package/src/layouts/DocsLayout.astro

@@ -0,0 +1,178 @@
+---
+import GlobalAppLayout from './GlobalAppLayout.astro';
+import ApiDocSubNavMenu from '../components/ApiDocSubNavMenu.svelte';
+import NavigationInitializer from '../components/NavigationInitializer.svelte';
+import { getBaseUrl } from '../helpers';
+
+const gtmID = import.meta.env.PUBLIC_GTM_ID;
+const {
+  navigationItem = 'api',
+  title,
+  description,
+  openGraphImage,
+  showAppIcons = false,
+  subNavData = null,
+  disableCodeCopyButtons = false,
+  postItems = null,
+  profileMenuData = null,
+} = Astro.props;
+---
+
+<GlobalAppLayout
+  ssrSelectedItem={navigationItem}
+  gtmID={gtmID}
+  {showAppIcons}
+  {profileMenuData}
+  logoLinkUrl={getBaseUrl()}
+  logoLinkLabel="Homepage"
+  title={title}
+  {description}
+  {openGraphImage}
+>
+  <!-- Initialize navigation state and auto-expand submenu for section pages -->
+  <NavigationInitializer
+    item={navigationItem}
+    autoExpand={true}
+    client:only="svelte"
+  />
+
+  <!-- Documentation Sub Navigation -->
+  {
+    subNavData && (
+      <ApiDocSubNavMenu
+        data={subNavData}
+        selectedId={null}
+        slot="sub-nav"
+        client:load
+      />
+    )
+  }
+
+  <!-- Main content area -->
+  <div class="docs-content">
+    <article class="article-body">
+      <h1 class="page-title">API Documentation</h1>
+
+      <!-- Render postItems if provided -->
+      {
+        postItems &&
+          postItems.map((post: any) => (
+            <div>
+              <h2 class="title" id={post.id}>
+                {post.data.title}
+              </h2>
+              <post.ContentComponent />
+            </div>
+          ))
+      }
+    </article>
+  </div>
+</GlobalAppLayout>
+
+<!-- Add copy button to all code blocks -->
+{
+  !disableCodeCopyButtons && (
+    <script>
+      import {setupCopyButtons} from '../utils/copyButtonScript.js';
+      setupCopyButtons();
+    </script>
+  )
+}
+
+<style>
+  body {
+    color: var(--ai-color-steel-900);
+    line-height: var(--ai-font-lineheight-prose);
+  }
+
+  :is(h1, h2, h3, h4, h5, h6) {
+    color: var(--ai-color-black);
+  }
+
+  .docs-content {
+    padding: 0;
+  }
+
+  .article-body {
+    max-width: 84ch;
+  }
+
+  :global(.ai-copy-btn) {
+    width: var(--ai-size-32);
+    height: var(--ai-size-32);
+    position: absolute;
+    top: var(--ai-size-8);
+    right: var(--ai-size-8);
+    background: none;
+    border-radius: var(--ai-size-4);
+    border: none;
+    padding: 0;
+    cursor: pointer;
+    box-shadow: 0 var(--ai-size-2) var(--ai-size-8) rgba(0, 0, 0, 0.08);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition:
+      background var(--ai-duration-fast),
+      border var(--ai-duration-fast);
+    z-index: var(--ai-layer-2);
+    overflow: hidden;
+  }
+  :global(.ai-copy-btn:hover),
+  :global(.ai-copy-btn:focus) {
+    background: var(--ai-color-steel-800);
+  }
+  :global(.ai-copy-btn svg) {
+    display: block;
+    position: relative;
+  }
+  :global(.ai-code-block-wrapper) {
+    position: relative;
+    display: block;
+  }
+  :global(pre) {
+    font-family: var(--ai-font-family-monospace);
+    font-size: var(--ai-size-13);
+    font-weight: var(--ai-font-weight-normal);
+  }
+
+  /* Table styling - only for documentation pages */
+  :global(.docs-content table) {
+    width: 100%;
+    border-collapse: collapse;
+    margin: var(--ai-size-24) 0;
+  }
+
+  :global(.docs-content table th),
+  :global(.docs-content table td) {
+    padding: var(--ai-size-12) var(--ai-size-16);
+    text-align: left;
+    border-bottom: 1px solid var(--ai-color-neutral-200);
+  }
+
+  :global(.docs-content table th) {
+    background-color: var(--ai-color-neutral-50);
+    font-weight: var(--ai-font-weight-semibold);
+    color: var(--ai-color-black);
+  }
+
+  :global(.docs-content table tbody tr:hover) {
+    background-color: var(--ai-color-neutral-25);
+  }
+
+  :global(.docs-content table tbody tr:last-child td) {
+    border-bottom: none;
+  }
+
+  @media (--ai-size-breakpoint-tablet) {
+    .docs-content {
+      padding: 2rem 0;
+    }
+  }
+
+  @media (--ai-size-breakpoint-desktop) {
+    .docs-content {
+      padding: 2rem;
+    }
+  }
+</style>

package/src/types/subnav.ts

@@ -0,0 +1,15 @@
+export interface SubNavItem {
+  id: string;
+  title: string;
+  href?: string;
+  children?: SubNavItem[];
+}
+
+export interface SubNavSection {
+  header: string;
+  items: SubNavItem[];
+}
+
+export interface SubNavData {
+  sections: SubNavSection[];
+}

package/src/utils/copyButtonScript.ts

@@ -0,0 +1,107 @@
+interface CopyButtonConfig {
+  buttonClass?: string;
+  copyIconClass?: string;
+  checkIconClass?: string;
+  timeout?: number;
+}
+
+export function initializeCopyButtons(config: CopyButtonConfig = {}) {
+  const {
+    buttonClass = 'ai-copy-btn',
+    copyIconClass = 'ai-copy-icon',
+    checkIconClass = 'ai-check-icon',
+    timeout = 1200,
+  } = config;
+
+  // Function to add a button to a visible code block
+  function addCopyButton(pre: HTMLPreElement) {
+    const codeBlock = pre.querySelector('code');
+    if (!codeBlock || pre.querySelector(`.${buttonClass}`)) return;
+
+    const wrapper = codeBlock.closest('.ai-code-block-wrapper');
+    if (!wrapper) return;
+
+    const button = document.createElement('button');
+    button.className = buttonClass;
+    button.type = 'button';
+    button.setAttribute('aria-label', 'Copy code to clipboard');
+
+    button.innerHTML = `
+      <!-- Inline Copy Icon -->
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
+        stroke-width="1.5" stroke="#f2f4f7"
+        class="usai-icon ${copyIconClass} size-6"
+        aria-hidden="true" focusable="false" role="img"
+        style="width:1.25em;height:1.25em;">
+        <path stroke-linecap="round" stroke-linejoin="round"
+          d="M15.75 17.25v3.375c0 .621-.504 1.125-1.125 1.125h-9.75a1.125 1.125 0 0 1-1.125-1.125V7.875c0-.621.504-1.125 1.125-1.125H6.75a9.06 9.06 0 0 1 1.5.124m7.5 10.376h3.375c.621 0 1.125-.504 1.125-1.125V11.25c0-4.46-3.243-8.161-7.5-8.876a9.06 9.06 0 0 0-1.5-.124H9.375c-.621 0-1.125.504-1.125 1.125v3.5m7.5 10.375H9.375a1.125 1.125 0 0 1-1.125-1.125v-9.25m12 6.625v-1.875a3.375 3.375 0 0 0-3.375-3.375h-1.5a1.125 1.125 0 0 1-1.125-1.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H9.75" />
+      </svg>
+
+      <!-- Inline Check Icon -->
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
+        stroke-width="1.5" stroke="#f2f4f7"
+        class="usai-icon ${checkIconClass} size-6"
+        aria-hidden="true" focusable="false" role="img"
+        style="display:none; position:absolute; top:50%; left:50%; transform:translate(-50%,-50%); width:1.25em; height:1.25em;">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m4.5 12.75 6 6 9-13.5" />
+      </svg>
+    `;
+
+    button.onclick = () => {
+      const lines = codeBlock.querySelectorAll('.line');
+      const textToCopy =
+        lines.length > 0
+          ? Array.from(lines)
+              .map(line => line.textContent ?? '')
+              .join('\n')
+          : (codeBlock.textContent ?? '');
+
+      navigator.clipboard.writeText(textToCopy);
+
+      const copyIcon = button.querySelector(
+        `.${copyIconClass}`
+      ) as SVGElement | null;
+      const checkIcon = button.querySelector(
+        `.${checkIconClass}`
+      ) as SVGElement | null;
+
+      if (copyIcon && checkIcon) {
+        copyIcon.style.display = 'none';
+        checkIcon.style.display = '';
+        button.setAttribute('aria-label', 'Copied!');
+        setTimeout(() => {
+          copyIcon.style.display = '';
+          checkIcon.style.display = 'none';
+          button.setAttribute('aria-label', 'Copy code to clipboard');
+        }, timeout);
+      }
+    };
+
+    wrapper.appendChild(button);
+  }
+
+  const observer = new IntersectionObserver(
+    (entries, obs) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          const pre = entry.target as HTMLPreElement;
+          addCopyButton(pre);
+          obs.unobserve(pre);
+        }
+      }
+    },
+    { rootMargin: '200px' }
+  );
+
+  document.querySelectorAll('pre').forEach(pre => {
+    observer.observe(pre);
+  });
+}
+
+export function setupCopyButtons() {
+  if (typeof window !== 'undefined') {
+    window.addEventListener('DOMContentLoaded', () => {
+      initializeCopyButtons();
+    });
+  }
+}