Repository: rungalileo/docs-official
Pull request #100: docs: Annotations page with Overview and Guide
Author: login: EvanGottschalk
Created: 2025-04-18T13:18:04Z | Merged: 2025-05-13T16:11:29Z

PREVIEW

More to come:
3. API reference for annotations and endpoint documentation
4. Best practices
5. Common use case examples (e.g. integration)
6. Troubleshooting guide


Diff:
diff --git a/concepts/annotations.mdx b/concepts/annotations.mdx
deleted file mode 100644
index d22838ed0..000000000
--- a/concepts/annotations.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
----
-title: Annotations
----
diff --git a/concepts/annotations/annotations-walkthrough.mdx b/concepts/annotations/annotations-walkthrough.mdx
new file mode 100644
index 000000000..f701f35eb
--- /dev/null
+++ b/concepts/annotations/annotations-walkthrough.mdx
@@ -0,0 +1,166 @@
+---
+title: Adding Annotations
+---
+
+import SnippetAnnotationsWalkthroughPython1 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-1.mdx';
+import SnippetAnnotationsWalkthroughPython2 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-2.mdx';
+import SnippetAnnotationsWalkthroughPython3 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-3.mdx';
+import SnippetAnnotationsWalkthroughPython4 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-4.mdx';
+import SnippetAnnotationsWalkthroughPython5 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-5.mdx';
+import SnippetAnnotationsWalkthroughPython6 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-6.mdx';
+import SnippetAnnotationsWalkthroughPython7 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-7.mdx';
+import SnippetAnnotationsWalkthroughPython8 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-8.mdx';
+import SnippetAnnotationsWalkthroughTypeScript1 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx';
+import SnippetAnnotationsWalkthroughTypeScript2 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-2.mdx';
+import SnippetAnnotationsWalkthroughTypeScript3 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-3.mdx';
+import SnippetAnnotationsWalkthroughTypeScript4 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-4.mdx';
+import SnippetAnnotationsWalkthroughTypeScript5 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-5.mdx';
+import SnippetAnnotationsWalkthroughTypeScript6 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-6.mdx';
+import SnippetAnnotationsWalkthroughTypeScript7 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx';
+import SnippetAnnotationsWalkthroughTypeScript8 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-8.mdx';
+
+Follow this step-by-step guide to get started using **Annotations** in your AI projects.
+
+### Prerequisites
+
+First, follow the [Getting Started with Galileo](/getting-started/quickstart) guide if you don't already have a Galileo Project set up.
+
+Then, use the following steps to add annotations to your Project.
+
+### Step 1: Open Your Galileo App
+
+Open your Galileo application in your code editor.
+
+In this guide, we are using the **finished demo application** from the [Getting Started](/getting-started/quickstart) guide.
+
+Each code snippet in the following steps will be added to the end of the [Getting Started](/getting-started/quickstart) demo code.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython1 />
+<SnippetAnnotationsWalkthroughTypeScript1 />
+</CodeGroup>
+
+### Step 2: Define Tags and Metadata
+
+Create **descriptive tags and metadata** to be attached to your logs. Both [Spans](/concepts/spans) and [Traces](/concepts/traces) can have their own tags and metadata.
+
+Define `tags` as a list of relevant labels, and `metadata` as a dictionary of label types and their values. The individual tag and metadata values must be strings.
+
+- **NOTE** : The `answer` variable is set to the raw text output of the model so that it can be used later.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython2 />
+<SnippetAnnotationsWalkthroughTypeScript2 />
+</CodeGroup>
+
+### Step 3: Initialize Galileo Logger
+
+Initialize logging by importing and calling the **Galileo Logger**.
+
+The **Project name** and **Log Stream name** are used as inputs to define in which Galileo Project and log stream the logs will be created.
+
+After running our application, the logs will appear in the chosen Project's log stream in the [Galileo Console](https://app.galileo.ai/).
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython3 />
+<SnippetAnnotationsWalkthroughTypeScript3 />
+</CodeGroup>
+
+### Step 4: Initialize New Trace
+
+Initialize a new [Trace](/concepts/traces) to start listening for data to log.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Trace.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython4 />
+<SnippetAnnotationsWalkthroughTypeScript4 />
+</CodeGroup>
+
+### Step 5: Create New Span
+
+Create a new [Span](/concepts/spans) containing the data created by running the LLM.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Span.
+
+**NOTE** : In this guide, the tags and metadata used for the Span and the Trace are identical. But, they don't have to be. You can use different tags and metadata for Spans and the Traces they're attached to.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython5 />
+<SnippetAnnotationsWalkthroughTypeScript5 />
+</CodeGroup>
+
+### Step 6: Close Trace & Push Logs
+
+To close the new Trace and **complete the logging session**, we use `logger.conclude()` with the LLM's raw text output as the input.
+
+Then, `logger.flush()` pushes the logs to the selected Project's [Log Stream](/concepts/logstreams).
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython6 />
+<SnippetAnnotationsWalkthroughTypeScript6 />
+</CodeGroup>
+
+### Step 7: Review Your Code
+
+By adding each previous code snippet to your Galileo application, it is ready to run and create annotated logs.
+
+Below is the **final combined application code** for the [Getting Started](/getting-started/quickstart) demo application, with our annotated log functionality added to it. 
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython7 />
+<SnippetAnnotationsWalkthroughTypeScript7 />
+</CodeGroup>
+
+### Step 8: Run Your Application
+
+Run your Galileo application.
+
+If your application file is named `app` (as in the [Getting Started](/getting-started/quickstart) demo), you can run it by using the following command in your terminal.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython8 />
+<SnippetAnnotationsWalkthroughTypeScript8 />
+</CodeGroup>
+
+### Step 9: Open Project in Galileo Console
+
+In the [Galileo Console](https://app.galileo.ai/), select your Project and Log Stream in the top-left corner.
+
+For **each time you run your application**, you will see a new Trace entry in your Log Stream.
+
+Each metadata key-value pair is displayed in its own column, which can be used for sorting and filtering.
+
+![Annotated Log Stream](/images/console-ui/annotated-log-stream.png)
+
+### Step 10: View Trace Annotations
+
+Click on an entry in the list.
+
+You will see the data logged to the Trace. This includes:
+- The raw text input (because we initialized the Trace with `input=prompt`)
+- The raw text output from the LLM (because we closed the Trace with `logger.conclude(answer)`)
+- The tags and metadata we created (found in the **Parameters** section in the top-right)
+
+![Annotated Trace](/images/console-ui/annotated-trace.png)
+
+### Step 11: View Span Annotations
+
+With the Trace open, click the `llm` button below `Trace` in the data map on the left.
+
+You will see the data logged to the Span. This includes:
+- The complete JSON LLM input (because we created the Span with `input=[{"role": "system", "content": prompt}]`)
+- The complete JSON LLM output (because we created the Span with `output=response.choices[0].message.content`)
+- The tags and metadata we created (found in the **Parameters** section in the top-right)
+
+![Annotated Span](/images/console-ui/annotated-span.png)
+
+## Next Steps:
+
+Continue testing, customizing, and incorporating tags and metadata into your AI project development process and implementation.
+
+Use **Annotations** to:
+- Keep your [experimentation](/getting-started/experiments/overview) process organized.
+- Coordinate with your team and track development.
+- Track individual steps in your AI project with [Traces](/concepts/traces) containing multiple [Spans](/concepts/spans) that each have their own distinct annotations.
+- Use the tag and metadata values in your code to automate alerts and improvements.
diff --git a/concepts/annotations/overview.mdx b/concepts/annotations/overview.mdx
new file mode 100644
index 000000000..d736ef502
--- /dev/null
+++ b/concepts/annotations/overview.mdx
@@ -0,0 +1,92 @@
+---
+title: Annotations Overview
+---
+
+import SnippetAnnotationsOverviewPython1 from '/snippets/code/python/annotations/overview/overview-py-1.mdx';
+import SnippetAnnotationsOverviewPython2 from '/snippets/code/python/annotations/overview/overview-py-2.mdx';
+import SnippetAnnotationsOverviewTypeScript1 from '/snippets/code/typescript/annotations/overview/overview-ts-1.mdx';
+import SnippetAnnotationsOverviewTypeScript2 from '/snippets/code/typescript/annotations/overview/overview-ts-2.mdx';
+
+Galileo's **Annotations** feature helps teams label, categorize, and analyze model outputs more effectively. Annotations provide a structured way to add human-in-the-loop feedback, highlight model behavior patterns, and guide future improvements to datasets and models.
+
+## Overview: What Are Annotations?
+
+**Annotations** are tags and metadata that can be used to label predictions, inputs, or other artifacts during model development and evaluation. They help **organize, classify, and track model behavior** during experimentation and production.
+
+You can see the tags and metadata in the [Log Streams](/concepts/logstreams) section of the [Galileo Console](https://app.galileo.ai/).
+
+These labels can represent:
+
+- Model issues (e.g., `label_mismatch`, `low_confidence`)
+- Observations from human reviewers (e.g., `grammar_error`, `ambiguous_input`)
+- Dataset quality notes (e.g., `duplicate_sample`, `out_of_distribution`)
+- Business-specific labels (e.g., `escalation_required`, `VIP_customer`)
+
+## Why Use Annotations?
+
+Annotations are particularly useful for:
+
+- **Team collaboration**: Share insights across teams with consistent tagging systems.
+- **Tracking model behavior**: Label samples where the model fails or performs below expectations.
+- **Data quality analysis**: Flag problematic or noisy inputs for later review or exclusion.
+- **Model evaluation**: Filter and analyze annotated data to evaluate model performance on specific slices.
+- **Automated improvement**: Create feedback loops between model outputs and annotation-guided dataset refinement.
+
+## Tags & Metadata
+
+Annotations are added to logged Traces and Spans in the form of **tags** and **metadata**.
+
+**Tags** - short, flat labels (strings) you assign to a trace or span to make them easy to group and filter.
+* Unlimited number of tags per trace/span (practical limit ≈ 50)
+* Case‑sensitive strings ≤ 50 chars each
+* Ideal for boolean‑style filters (e.g., “show me all traces tagged physics”)
+
+**Metadata** - key‑value dictionaries that travel with a trace or a span, perfect for structured information like user IDs, experiment hashes, timestamps, or numeric metrics.
+* Keys and values are strings ≤ 256 chars
+* Appears in Log Streams as new columns
+* Ideal for structured attributes you can filter, group, and aggregate
+
+
+## Adding Annotations to Traces
+
+To add annotations to your [Traces](/concepts/traces), initialize the Galileo Logger, and then include tags and metadata when you start your Trace.
+
+<CodeGroup>
+<SnippetAnnotationsOverviewPython1 />
+<SnippetAnnotationsOverviewTypeScript1 />
+</CodeGroup>
+
+
+## Adding Annotations to Spans
+
+Attach annotations to your [Spans](/concepts/spans) by including tags and metadata when you add your Span.
+
+<CodeGroup>
+<SnippetAnnotationsOverviewPython2 />
+<SnippetAnnotationsOverviewTypeScript2 />
+</CodeGroup>
+
+
+## Annotations in the Galileo Console
+
+Tags and metadata appear within the selected Project and Log Stream in the [Galileo Console](https://app.galileo.ai/).
+
+You can view the tags and metadata attached to Traces and Spans in their **"Parameters"** section.
+
+![Annotated Log Stream](/images/console-ui/annotations-and-parameters-in-trace.png)
+
+Additionally, metadata appears as **new columns in the Log Stream**.
+
+![Annotations in Parameters](/images/console-ui/annotated-log-stream.png)
+
+## Best Practices
+
+* Tag early. Start the trace yourself and pass tags before the first LLM call; otherwise auto‑spans may end up in an untagged trace.
+* Keep tags coarse‑grained. A handful of well‑chosen tags beat hundreds of one‑offs.
+* Standardise metadata keys. Stick to a naming convention (experiment, user_id, etc.) so dashboards stay tidy.
+* Avoid sensitive data. Never put PII or keys in either tags or metadata; they become queryable in the UI.
+
+
+## Next Steps:
+
+Get started using **Annotations** with the [Adding Annotations](/concepts/annotations/annotations-walkthrough) step-by-step guide.
\ No newline at end of file
diff --git a/docs.json b/docs.json
index 8088170a6..27a1d1861 100644
--- a/docs.json
+++ b/docs.json
@@ -207,8 +207,15 @@
           "concepts/logstreams",
           "concepts/traces",
           "concepts/spans",
+          {  
+          "group": "Annotations",
+            "pages": [
+              "concepts/annotations/overview",
+              "concepts/annotations/annotations-walkthrough"
+            ]
+          },
           {
-            "group": "Experiments",
+          "group": "Experiments",
             "pages": [
               "concepts/experiments/overview",
               "concepts/experiments/datasets",
@@ -216,7 +223,8 @@
               "concepts/experiments/running-experiments"
             ]
           },
-          "concepts/playground"
+          "concepts/playground",
+          "concepts/datasets"
         ]
       },
       {
diff --git a/images/console-ui/annotated-log-stream.png b/images/console-ui/annotated-log-stream.png
new file mode 100644
index 000000000..b373bf136
Binary files /dev/null and b/images/console-ui/annotated-log-stream.png differ
diff --git a/images/console-ui/annotated-span.png b/images/console-ui/annotated-span.png
new file mode 100644
index 000000000..73e027076
Binary files /dev/null and b/images/console-ui/annotated-span.png differ
diff --git a/images/console-ui/annotated-trace.png b/images/console-ui/annotated-trace.png
new file mode 100644
index 000000000..3839470b6
Binary files /dev/null and b/images/console-ui/annotated-trace.png differ
diff --git a/images/console-ui/annotations-and-parameters-in-trace.png b/images/console-ui/annotations-and-parameters-in-trace.png
new file mode 100644
index 000000000..979254bec
Binary files /dev/null and b/images/console-ui/annotations-and-parameters-in-trace.png differ
diff --git a/snippets/code/python/annotations/overview/overview-py-1.mdx b/snippets/code/python/annotations/overview/overview-py-1.mdx
new file mode 100644
index 000000000..468c40324
--- /dev/null
+++ b/snippets/code/python/annotations/overview/overview-py-1.mdx
@@ -0,0 +1,16 @@
+```python Python
+# Include GalileoLogger in imports
+from galileo import GalileoLogger
+
+# Initialize logger
+logger = GalileoLogger()
+
+# Initialize a new Trace with tags and metadata
+trace = logger.start_trace(
+    input="Explain the following topic succinctly: Newton's First Law",
+    tags=["newton", "test", "new-version"],
+    metadata={"experimentNumber": "1",
+              "promptVersion": "0.0.1",
+              "field": "physics"}
+)
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/overview/overview-py-2.mdx b/snippets/code/python/annotations/overview/overview-py-2.mdx
new file mode 100644
index 000000000..8cf027019
--- /dev/null
+++ b/snippets/code/python/annotations/overview/overview-py-2.mdx
@@ -0,0 +1,12 @@
+```python Python
+# Include tags and metadata when adding a new Span
+logger.add_llm_span(
+    input=[{"role": "system", "content": prompt}],
+    output="Model response",
+    model="gpt-4o",
+    tags=["newton", "test", "new-version"],
+    metadata={"experimentNumber": "1",
+              "promptVersion": "0.0.1",
+              "field": "physics"}
+)
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-1.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-1.mdx
new file mode 100644
index 000000000..85b58343d
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-1.mdx
@@ -0,0 +1,15 @@
+```python Python
+import openai
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client
+client = openai.OpenAI()
+
+prompt = f"Explain the following topic succinctly: Newton's First Law"
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "system", "content": prompt}],
+)
+print(response.choices[0].message.content.strip())
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-2.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-2.mdx
new file mode 100644
index 000000000..23d1169e7
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-2.mdx
@@ -0,0 +1,9 @@
+```python Python
+answer = response.choices[0].message.content.strip()
+    
+# Define tags and metadata
+tags = ["newton", "test", "new-version"]
+metadata = {"experimentNumber": "1",
+            "promptVersion": "0.0.1",
+            "field": "physics"}
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-3.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-3.mdx
new file mode 100644
index 000000000..c78f38123
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-3.mdx
@@ -0,0 +1,9 @@
+```python Python
+# Include GalileoLogger in imports
+from galileo import GalileoLogger
+
+...application code...
+
+# Initialize logger
+logger = GalileoLogger()
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-4.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-4.mdx
new file mode 100644
index 000000000..90ba2cdc9
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-4.mdx
@@ -0,0 +1,8 @@
+```python Python
+# Initialize a new Trace and start listening for logs to add to it
+trace = logger.start_trace(
+    input=prompt,
+    tags=tags,
+    metadata=metadata
+)
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-5.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-5.mdx
new file mode 100644
index 000000000..5ca0fab31
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-5.mdx
@@ -0,0 +1,10 @@
+```python Python
+# Create a Span to log LLM outputs. This is captured by the Trace
+logger.add_llm_span(
+    input=[{"role": "system", "content": prompt}],
+    output=response.choices[0].message.content,
+    model="gpt-4o",
+    tags=tags,
+    metadata=metadata
+)
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-6.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-6.mdx
new file mode 100644
index 000000000..230689cf2
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-6.mdx
@@ -0,0 +1,5 @@
+```python Python
+# Close the Trace and push captured logs to it
+logger.conclude(answer)
+logger.flush()
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-7.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-7.mdx
new file mode 100644
index 000000000..3bb205fac
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-7.mdx
@@ -0,0 +1,47 @@
+```python Python
+from galileo import GalileoLogger
+import openai
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client
+client = openai.OpenAI()
+
+prompt = f"Explain the following topic succinctly: Newton's First Law"
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "system", "content": prompt}],
+)
+print(response.choices[0].message.content.strip())
+
+answer = response.choices[0].message.content.strip()
+
+# Define tags and metadata
+tags = ["newton", "test", "new-version"]
+metadata = {"experimentNumber": "1",
+            "promptVersion": "0.0.1",
+            "field": "physics"}
+
+# Initialize logger
+logger = GalileoLogger()
+
+# Initialize a new Trace and start listening for logs to add to it
+trace = logger.start_trace(
+    input=prompt,
+    tags=tags,
+    metadata=metadata
+)
+
+# Create a span to log LLM outputs. This is captured by the Trace
+logger.add_llm_span(
+    input=[{"role": "system", "content": prompt}],
+    output=response.choices[0].message.content,
+    model="gpt-4o",
+    tags=tags,
+    metadata=metadata
+)
+
+# Close the Trace and push captured logs to it
+logger.conclude(answer)
+logger.flush()
+```
\ No newline at end of file
diff --git a/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-8.mdx b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-8.mdx
new file mode 100644
index 000000000..238a2d0f9
--- /dev/null
+++ b/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-8.mdx
@@ -0,0 +1,3 @@
+```bash Python
+python app.py
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/overview/overview-ts-1.mdx b/snippets/code/typescript/annotations/overview/overview-ts-1.mdx
new file mode 100644
index 000000000..2b1b59ee6
--- /dev/null
+++ b/snippets/code/typescript/annotations/overview/overview-ts-1.mdx
@@ -0,0 +1,16 @@
+```typescript TypeScript
+// Include GalileoLogger in imports
+import { GalileoLogger } from "galileo";
+
+// Initialize logger
+const logger = new GalileoLogger();
+
+// Initialize a new Trace with tags and metadata
+const trace = logger.startTrace({
+    input: "Explain the following topic succinctly: Newton's First Law",
+    tags: ["newton", "test", "new-version"],
+    metadata: {experimentNumber: "1",
+              promptVersion: "0.0.1",
+              field: "physics"}
+});
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/overview/overview-ts-2.mdx b/snippets/code/typescript/annotations/overview/overview-ts-2.mdx
new file mode 100644
index 000000000..b2546da9a
--- /dev/null
+++ b/snippets/code/typescript/annotations/overview/overview-ts-2.mdx
@@ -0,0 +1,12 @@
+```typescript TypeScript
+// Include tags and metadata when adding a new Span
+logger.addLlmSpan({
+    input: [{ role: "system", content: prompt }],
+    output: "Model response",
+    model: "gpt-4o",
+    tags: ["newton", "test", "new-version"],
+    metadata: {"experimentNumber": "1",
+              "promptVersion": "0.0.1",
+              "field": "physics"}
+});
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx
new file mode 100644
index 000000000..b0df7e164
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx
@@ -0,0 +1,14 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client
+const openai = new OpenAI();
+
+const prompt = "Explain the following topic succinctly: Newton's First Law";
+const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: [{ content: prompt, role: "system" }],
+});
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-2.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-2.mdx
new file mode 100644
index 000000000..ae335baa9
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-2.mdx
@@ -0,0 +1,11 @@
+```typescript TypeScript
+const answer: string = response.choices[0].message.content.trim();
+
+// Define tags and metadata
+const tags = ["newton", "test", "new-version"];
+const metadata = {
+    experimentNumber: "1",
+    promptVersion: "0.0.1",
+    field: "physics"
+};
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-3.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-3.mdx
new file mode 100644
index 000000000..ecd2a0a9d
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-3.mdx
@@ -0,0 +1,9 @@
+```typescript TypeScript
+// Include GalileoLogger in imports
+import { GalileoLogger } from "galileo";
+
+...application code...
+
+// Initialize logger
+const logger = new GalileoLogger();
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-4.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-4.mdx
new file mode 100644
index 000000000..c70a97b17
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-4.mdx
@@ -0,0 +1,8 @@
+```typescript TypeScript
+// Initialize a new Trace and start listening for logs to add to it
+const trace = logger.startTrace({
+    input: prompt,
+    tags: tags,
+    metadata: metadata
+});
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-5.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-5.mdx
new file mode 100644
index 000000000..6a94d9a3c
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-5.mdx
@@ -0,0 +1,10 @@
+```typescript TypeScript
+// Create a Span to log LLM outputs. This is captured by the Trace
+logger.addLlmSpan({
+    input: [{ role: "system", content: prompt }],
+    output: response.choices[0].message.content,
+    model: "gpt-4o",
+    tags: tags,
+    metadata: metadata
+});
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-6.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-6.mdx
new file mode 100644
index 000000000..00f12ed16
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-6.mdx
@@ -0,0 +1,5 @@
+```typescript TypeScript
+// Close the Trace and push captured logs to it
+logger.conclude({output: answer});
+logger.flush();
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
new file mode 100644
index 000000000..38a949c7c
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
@@ -0,0 +1,48 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { GalileoLogger } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client
+const openai = new OpenAI();
+
+const prompt = "Explain the following topic succinctly: Newton's First Law";
+const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: [{ content: prompt, role: "system" }],
+});
+
+const answer: string = response.choices[0].message.content.trim();
+
+// Define tags and metadata
+const tags = ["newton", "test", "new-version"];
+const metadata = {
+    experimentNumber: "1",
+    promptVersion: "0.0.1",
+    field: "physics"
+};
+
+// Initialize logger
+const logger = new GalileoLogger();
+
+// Initialize a new Trace and start listening for logs to add to it
+const trace = logger.startTrace({
+    input: prompt,
+    tags: tags,
+    metadata: metadata
+});
+
+// Create a span to log LLM outputs. This is captured by the Trace
+logger.addLlmSpan({
+    input: [{ role: "system", content: prompt }],
+    output: response.choices[0].message.content,
+    model: "gpt-4o",
+    tags: tags,
+    metadata: metadata
+});
+
+// Close the Trace and push captured logs to it
+logger.conclude({output: answer});
+logger.flush();
+```
\ No newline at end of file
diff --git a/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-8.mdx b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-8.mdx
new file mode 100644
index 000000000..1828f4934
--- /dev/null
+++ b/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-8.mdx
@@ -0,0 +1,4 @@
+```bash TypeScript
+npm install tsx
+npx tsx app.ts
+```
\ No newline at end of file


Reviews:
user: login: rschwabco
body: Need to fix the language for all the code snippets in this PR.
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-28T17:10:19Z
user: login: rschwabco
body: And also resolve conflicts. 
state: DISMISSED
author_association: CONTRIBUTOR
submitted_at: 2025-04-28T17:10:33Z
user: login: jimbobbennett
body: Images are broken in the deployment

![image](https://github.com/user-attachments/assets/39ce346a-4a4e-4d09-81fb-b9ea5c2e0f21)

state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-06T19:46:24Z
user: login: jimbobbennett
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-07T22:33:27Z
user: login: jimbobbennett
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-08T01:44:31Z
user: login: jimbobbennett
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-12T17:09:59Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:28:21Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:28:26Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:28:32Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:28:39Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:29:03Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:29:12Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:29:22Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:29:28Z
user: login: EvanGottschalk
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T05:29:37Z
user: login: jimbobbennett
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T15:47:47Z

Review comments:
diff_hunk: @@ -0,0 +1,44 @@
+```bash Python
path: snippets/code/multilingual/annotations/annotations-1.mdx
user: login: rschwabco
body: 
```suggestion
```python Python
```
created_at: 2025-04-28T17:08:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,44 @@
+```bash Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+# The Galileo context manager will automatically create a trace and flush the logs when exiting
+with galileo_context():
+    prompt = f"Explain the following topic succinctly: Newton's First Law"
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "system", "content": prompt}],
+    )
+    print(response.choices[0].message.content.strip())
+```
+
+```bash Typescript
path: snippets/code/multilingual/annotations/annotations-1.mdx
user: login: rschwabco
body: 
```suggestion
```typescript Typescript
```
created_at: 2025-04-28T17:09:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,44 @@
+```bash Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+# The Galileo context manager will automatically create a trace and flush the logs when exiting
+with galileo_context():
+    prompt = f"Explain the following topic succinctly: Newton's First Law"
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "system", "content": prompt}],
+    )
+    print(response.choices[0].message.content.strip())
+```
+
+```bash Typescript
+TYPESCRIPT_CODEimport { OpenAI } from "openai";
path: snippets/code/multilingual/annotations/annotations-1.mdx
user: login: rschwabco
body: 
```suggestion
import { OpenAI } from "openai";
```
created_at: 2025-04-28T17:09:29Z
author_association: CONTRIBUTOR
path: images/console-ui/annotated-span.PNG
user: login: jimbobbennett
body: lowercase .png - this image is broken otherwise
created_at: 2025-05-06T19:45:15Z
author_association: CONTRIBUTOR
path: images/console-ui/annotated-trace.PNG
user: login: jimbobbennett
body: lower case .png - this image is broken otherwise
created_at: 2025-05-06T19:45:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -2,4 +2,190 @@
 title: Annotations
 ---
 
+import { Screenshot } from '/snippets/Screenshot.mdx';
path: concepts/annotations.mdx
user: login: jimbobbennett
body: I removed screenshot as this is what was causing the broken images. Can you remove this and change all references to it to just use images in markdown
created_at: 2025-05-07T22:33:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,109 @@
+```bash Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+# The Galileo context manager will automatically create a Trace and flush the logs when exiting
+with galileo_context():
+    prompt = f"Explain the following topic succinctly: Newton's First Law"
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "system", "content": prompt}],
+    )
+    print(response.choices[0].message.content.strip())
+
+    answer = response.choices[0].message.content.strip()
+    
+    ## Define tags and metadata
+    tags = ["newton", "test", "new-version"]
+    metadata = {"experimentNumber": "1", \
+                "promptVersion": "0.0.1", \
+                "field": "physics"}
+
+    ## Initialize logger and select project and log stream
+    logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
+
+    ## Initialize a new Trace and start listening for logs to add to it
+    trace = logger.start_trace(
+        input=prompt,
+        tags=tags,
+        metadata=metadata
+    )
+
+    ## Create a span to log LLM outputs. This is captured by the Trace
+    logger.add_llm_span(
+        input=[{"role": "system", "content": prompt}],
+        output=response.choices[0].message.content,
+        model="gpt-4o",
+        tags=tags,
+        metadata=metadata
+    )
+
+    ## Close the Trace and push captured logs to it
+    logger.conclude(answer)
+    logger.flush()
+```
+
+```bash Typescript
path: snippets/code/multilingual/annotations/annotations-7.mdx
user: login: jimbobbennett
body: ```suggestion
```typescript Typescript
```
created_at: 2025-05-07T23:46:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,109 @@
+```bash Python
path: snippets/code/multilingual/annotations/annotations-7.mdx
user: login: jimbobbennett
body: ```suggestion
```python Python
```
created_at: 2025-05-07T23:46:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,11 @@
+```bash Python
+## Close the Trace and push captured logs to it
+logger.conclude(answer)
+logger.flush()
+```
+
+```bash Typescript
path: snippets/code/multilingual/annotations/annotations-6.mdx
user: login: jimbobbennett
body: ```suggestion
```typescript Typescript
```
created_at: 2025-05-07T23:47:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,11 @@
+```bash Python
path: snippets/code/multilingual/annotations/annotations-6.mdx
user: login: jimbobbennett
body: ```suggestion
```python Python
```
created_at: 2025-05-07T23:47:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,21 @@
+```bash Python
+## Create a Span to log LLM outputs. This is captured by the Trace
+logger.add_llm_span(
+    input=[{"role": "system", "content": prompt}],
+    output=response.choices[0].message.content,
+    model="gpt-4o",
+    tags=tags,
+    metadata=metadata
+)
+```
+
+```bash Typescript
path: snippets/code/multilingual/annotations/annotations-5.mdx
user: login: jimbobbennett
body: ```suggestion
```typescript Typescript
```
created_at: 2025-05-07T23:47:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,21 @@
+```bash Python
path: snippets/code/multilingual/annotations/annotations-5.mdx
user: login: jimbobbennett
body: ```suggestion
```python Python
```
created_at: 2025-05-07T23:47:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,17 @@
+```bash Python
+## Initialize a new Trace and start listening for logs to add to it
+trace = logger.start_trace(
+    input=prompt,
+    tags=tags,
+    metadata=metadata
+)
+```
+
+```bash Typescript
path: snippets/code/multilingual/annotations/annotations-4.mdx
user: login: jimbobbennett
body: ```suggestion
```typescript Typescript
```
created_at: 2025-05-07T23:48:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,17 @@
+```bash Python
path: snippets/code/multilingual/annotations/annotations-4.mdx
user: login: jimbobbennett
body: ```suggestion
```python Python
```
created_at: 2025-05-07T23:48:13Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,22 @@
+```bash Python
path: snippets/code/multilingual/annotations/annotations-3.mdx
user: login: jimbobbennett
body: ```suggestion
```python Python
```
created_at: 2025-05-07T23:48:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,21 @@
+```bash Python
path: snippets/code/multilingual/annotations/annotations-2.mdx
user: login: jimbobbennett
body: ```suggestion
```python Python
```
created_at: 2025-05-07T23:48:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -1,3 +1,191 @@
 ---
 title: Annotations
 ---
+
+import { Screenshot } from '/snippets/Screenshot.mdx';
+import SnippetAnnotations1 from '/snippets/code/multilingual/annotations/annotations-1.mdx';
+import SnippetAnnotations2 from '/snippets/code/multilingual/annotations/annotations-2.mdx';
+import SnippetAnnotations3 from '/snippets/code/multilingual/annotations/annotations-3.mdx';
+import SnippetAnnotations4 from '/snippets/code/multilingual/annotations/annotations-4.mdx';
+import SnippetAnnotations5 from '/snippets/code/multilingual/annotations/annotations-5.mdx';
+import SnippetAnnotations6 from '/snippets/code/multilingual/annotations/annotations-6.mdx';
+import SnippetAnnotations7 from '/snippets/code/multilingual/annotations/annotations-7.mdx';
+import SnippetAnnotations8 from '/snippets/code/multilingual/annotations/annotations-8.mdx';
+
+Galileo's **Annotations** feature helps teams label, categorize, and analyze model outputs more effectively. Annotations provide a structured way to add human-in-the-loop feedback, highlight model behavior patterns, and guide future improvements to datasets and models.
+
+## Overview: What Are Annotations?
+
+**Annotations** are tags and metadata that can be used to label predictions, inputs, or other artifacts during model development and evaluation. They help **organize, classify, and track model behavior** during experimentation and production.
+
+You can see the tags and metadata in the [Log Streams](/concepts/logstreams) section of the [Galileo Console](https://app.galileo.ai/).
+
+These labels can represent:
+
+- Model issues (e.g., `label_mismatch`, `low_confidence`)
+- Observations from human reviewers (e.g., `grammar_error`, `ambiguous_input`)
+- Dataset quality notes (e.g., `duplicate_sample`, `out_of_distribution`)
+- Business-specific labels (e.g., `escalation_required`, `VIP_customer`)
+
+### Why Use Annotations?
+
+Annotations are particularly useful for:
+
+- **Team collaboration**: Share insights across teams with consistent tagging systems.
+- **Tracking model behavior**: Label samples where the model fails or performs below expectations.
+- **Data quality analysis**: Flag problematic or noisy inputs for later review or exclusion.
+- **Model evaluation**: Filter and analyze annotated data to evaluate model performance on specific slices.
+- **Automated improvement**: Create feedback loops between model outputs and annotation-guided dataset refinement.
+
+---
+
+## Getting Started with Annotations
+
+Follow this step-by-step guide to get started using **Annotations** in your AI projects.
+
+### Prerequisites
+
+First, follow the [Getting Started with Galileo](/getting-started/quickstart) guide if you don't already have a Galileo Project set up.
+
+Then, use the following steps to add annotations to your Project.
+
+### Step 1: Open Your Galileo App
+
+Open your Galileo application in your code editor.
+
+In this guide, we are using the **finished demo application** from the [Getting Started](/getting-started/quickstart) guide.
+
+Each code snippet in the following steps will be added to the end of the [Getting Started](/getting-started/quickstart) demo code.
+
+<CodeGroup>
+<SnippetAnnotations1 />
+</CodeGroup>
+
+### Step 2: Define Tags and Metadata
+
+Create **descriptive tags and metadata** to be attached to your logs. Both [Spans](/concepts/spans) and [Traces](/concepts/traces) can have their own tags and metadata.
+
+Define `tags` as a list of relevant labels, and `metadata` as a dictionary of label types and their values. The individual tag and metadata values must be strings.
+
+- **NOTE** : The `answer` variable is set to the raw text output of the model so that it can be used later.
+
+<CodeGroup>
+<SnippetAnnotations2 />
+</CodeGroup>
+
+### Step 3: Initialize Galileo Logger
+
+Initialize logging by importing and calling the **Galileo Logger**.
+
+The **Project name** and **Log Stream name** are used as inputs to define in which Galileo Project and log stream the logs will be created.
+
+After running our application, the logs will appear in the chosen Project's log stream in the [Galileo Console](https://app.galileo.ai/).
+
+<CodeGroup>
+<SnippetAnnotations3 />
+</CodeGroup>
+
+### Step 4: Initialize New Trace
+
+Initialize a new [Trace](/concepts/traces) to start listening for data to log.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Trace.
+
+_From your terminal, execute (replace placeholders with real values):_
+
+<CodeGroup>
+<SnippetAnnotations4 />
+</CodeGroup>
+
+### Step 5: Create New Span
+
+Create a new [Span](/concepts/spans) containing the data created by running the LLM.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Span.
+
+**NOTE** : In this guide, the tags and metadata used for the Span and the Trace are identical. But, they don't have to be. You can use different tags and metadata for Spans and the Traces they're attached to.
+
+<CodeGroup>
+<SnippetAnnotations5 />
+</CodeGroup>
+
+### Step 6: Close Trace & Push Logs
+
+To close the new Trace and **complete the logging session**, we use `logger.conclude()` with the LLM's raw text output as the input.
+
+Then, `logger.flush()` pushes the logs to the selected Project's [Log Stream](/concepts/logstreams).
+
+<CodeGroup>
+<SnippetAnnotations6 />
+</CodeGroup>
+
+### Step 7: Review Your Code
+
+By adding each previous code snippet to your Galileo application, it is ready to run and create annotated logs.
+
+Below is the **final combined application code** for the [Getting Started](/getting-started/quickstart) demo application, with our annotated log functionality added to it. 
+
+<CodeGroup>
+<SnippetAnnotations7 />
+</CodeGroup>
+
+### Step 8: Run Your Application
+
+Run your Galileo application.
+
+If your application file is named `app` (as in the [Getting Started](/getting-started/quickstart) demo), you can run it by using the following command in your terminal.
+
+<CodeGroup>
+<SnippetAnnotations8 />
+</CodeGroup>
+
+### Step 9: Open Project in Galileo Console
+
+In the [Galileo Console](https://app.galileo.ai/), select your Project and Log Stream in the top-left corner.
+
+For **each time you run your application**, you will see a new Trace entry in your Log Stream.
+
+Each metadata key-value pair is displayed in its own column, which can be used for sorting and filtering.
+
+<Screenshot
+  alt="Log Stream"
+  imageUrl="/images/console-ui/annotated-log-stream.png"
+/>
path: concepts/annotations.mdx
user: login: jimbobbennett
body: ```suggestion
![Log Stream](/images/console-ui/annotated-log-stream.png)
```
created_at: 2025-05-07T23:52:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -1,3 +1,191 @@
 ---
 title: Annotations
 ---
+
+import { Screenshot } from '/snippets/Screenshot.mdx';
+import SnippetAnnotations1 from '/snippets/code/multilingual/annotations/annotations-1.mdx';
+import SnippetAnnotations2 from '/snippets/code/multilingual/annotations/annotations-2.mdx';
+import SnippetAnnotations3 from '/snippets/code/multilingual/annotations/annotations-3.mdx';
+import SnippetAnnotations4 from '/snippets/code/multilingual/annotations/annotations-4.mdx';
+import SnippetAnnotations5 from '/snippets/code/multilingual/annotations/annotations-5.mdx';
+import SnippetAnnotations6 from '/snippets/code/multilingual/annotations/annotations-6.mdx';
+import SnippetAnnotations7 from '/snippets/code/multilingual/annotations/annotations-7.mdx';
+import SnippetAnnotations8 from '/snippets/code/multilingual/annotations/annotations-8.mdx';
+
+Galileo's **Annotations** feature helps teams label, categorize, and analyze model outputs more effectively. Annotations provide a structured way to add human-in-the-loop feedback, highlight model behavior patterns, and guide future improvements to datasets and models.
+
+## Overview: What Are Annotations?
+
+**Annotations** are tags and metadata that can be used to label predictions, inputs, or other artifacts during model development and evaluation. They help **organize, classify, and track model behavior** during experimentation and production.
+
+You can see the tags and metadata in the [Log Streams](/concepts/logstreams) section of the [Galileo Console](https://app.galileo.ai/).
+
+These labels can represent:
+
+- Model issues (e.g., `label_mismatch`, `low_confidence`)
+- Observations from human reviewers (e.g., `grammar_error`, `ambiguous_input`)
+- Dataset quality notes (e.g., `duplicate_sample`, `out_of_distribution`)
+- Business-specific labels (e.g., `escalation_required`, `VIP_customer`)
+
+### Why Use Annotations?
+
+Annotations are particularly useful for:
+
+- **Team collaboration**: Share insights across teams with consistent tagging systems.
+- **Tracking model behavior**: Label samples where the model fails or performs below expectations.
+- **Data quality analysis**: Flag problematic or noisy inputs for later review or exclusion.
+- **Model evaluation**: Filter and analyze annotated data to evaluate model performance on specific slices.
+- **Automated improvement**: Create feedback loops between model outputs and annotation-guided dataset refinement.
+
+---
+
+## Getting Started with Annotations
+
+Follow this step-by-step guide to get started using **Annotations** in your AI projects.
+
+### Prerequisites
+
+First, follow the [Getting Started with Galileo](/getting-started/quickstart) guide if you don't already have a Galileo Project set up.
+
+Then, use the following steps to add annotations to your Project.
+
+### Step 1: Open Your Galileo App
+
+Open your Galileo application in your code editor.
+
+In this guide, we are using the **finished demo application** from the [Getting Started](/getting-started/quickstart) guide.
+
+Each code snippet in the following steps will be added to the end of the [Getting Started](/getting-started/quickstart) demo code.
+
+<CodeGroup>
+<SnippetAnnotations1 />
+</CodeGroup>
+
+### Step 2: Define Tags and Metadata
+
+Create **descriptive tags and metadata** to be attached to your logs. Both [Spans](/concepts/spans) and [Traces](/concepts/traces) can have their own tags and metadata.
+
+Define `tags` as a list of relevant labels, and `metadata` as a dictionary of label types and their values. The individual tag and metadata values must be strings.
+
+- **NOTE** : The `answer` variable is set to the raw text output of the model so that it can be used later.
+
+<CodeGroup>
+<SnippetAnnotations2 />
+</CodeGroup>
+
+### Step 3: Initialize Galileo Logger
+
+Initialize logging by importing and calling the **Galileo Logger**.
+
+The **Project name** and **Log Stream name** are used as inputs to define in which Galileo Project and log stream the logs will be created.
+
+After running our application, the logs will appear in the chosen Project's log stream in the [Galileo Console](https://app.galileo.ai/).
+
+<CodeGroup>
+<SnippetAnnotations3 />
+</CodeGroup>
+
+### Step 4: Initialize New Trace
+
+Initialize a new [Trace](/concepts/traces) to start listening for data to log.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Trace.
+
+_From your terminal, execute (replace placeholders with real values):_
+
+<CodeGroup>
+<SnippetAnnotations4 />
+</CodeGroup>
+
+### Step 5: Create New Span
+
+Create a new [Span](/concepts/spans) containing the data created by running the LLM.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Span.
+
+**NOTE** : In this guide, the tags and metadata used for the Span and the Trace are identical. But, they don't have to be. You can use different tags and metadata for Spans and the Traces they're attached to.
+
+<CodeGroup>
+<SnippetAnnotations5 />
+</CodeGroup>
+
+### Step 6: Close Trace & Push Logs
+
+To close the new Trace and **complete the logging session**, we use `logger.conclude()` with the LLM's raw text output as the input.
+
+Then, `logger.flush()` pushes the logs to the selected Project's [Log Stream](/concepts/logstreams).
+
+<CodeGroup>
+<SnippetAnnotations6 />
+</CodeGroup>
+
+### Step 7: Review Your Code
+
+By adding each previous code snippet to your Galileo application, it is ready to run and create annotated logs.
+
+Below is the **final combined application code** for the [Getting Started](/getting-started/quickstart) demo application, with our annotated log functionality added to it. 
+
+<CodeGroup>
+<SnippetAnnotations7 />
+</CodeGroup>
+
+### Step 8: Run Your Application
+
+Run your Galileo application.
+
+If your application file is named `app` (as in the [Getting Started](/getting-started/quickstart) demo), you can run it by using the following command in your terminal.
+
+<CodeGroup>
+<SnippetAnnotations8 />
+</CodeGroup>
+
+### Step 9: Open Project in Galileo Console
+
+In the [Galileo Console](https://app.galileo.ai/), select your Project and Log Stream in the top-left corner.
+
+For **each time you run your application**, you will see a new Trace entry in your Log Stream.
+
+Each metadata key-value pair is displayed in its own column, which can be used for sorting and filtering.
+
+<Screenshot
+  alt="Log Stream"
+  imageUrl="/images/console-ui/annotated-log-stream.png"
+/>
+
+### Step 10: View Trace Annotations
+
+Click on an entry in the list.
+
+You will see the data logged to the Trace. This includes:
+- The raw text input (because we initialized the Trace with `input=prompt`)
+- The raw text output from the LLM (because we closed the Trace with `logger.conclude(answer)`)
+- The tags and metadata we created (found in the **Parameters** section in the top-right)
+
+<Screenshot
+  alt="Annotated Trace"
+  imageUrl="/images/console-ui/annotated-trace.png"
+/>
path: concepts/annotations.mdx
user: login: jimbobbennett
body: ```suggestion
![Annotated Trace](/images/console-ui/annotated-trace.png)
```
created_at: 2025-05-07T23:52:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -1,3 +1,191 @@
 ---
 title: Annotations
 ---
+
+import { Screenshot } from '/snippets/Screenshot.mdx';
+import SnippetAnnotations1 from '/snippets/code/multilingual/annotations/annotations-1.mdx';
+import SnippetAnnotations2 from '/snippets/code/multilingual/annotations/annotations-2.mdx';
+import SnippetAnnotations3 from '/snippets/code/multilingual/annotations/annotations-3.mdx';
+import SnippetAnnotations4 from '/snippets/code/multilingual/annotations/annotations-4.mdx';
+import SnippetAnnotations5 from '/snippets/code/multilingual/annotations/annotations-5.mdx';
+import SnippetAnnotations6 from '/snippets/code/multilingual/annotations/annotations-6.mdx';
+import SnippetAnnotations7 from '/snippets/code/multilingual/annotations/annotations-7.mdx';
+import SnippetAnnotations8 from '/snippets/code/multilingual/annotations/annotations-8.mdx';
+
+Galileo's **Annotations** feature helps teams label, categorize, and analyze model outputs more effectively. Annotations provide a structured way to add human-in-the-loop feedback, highlight model behavior patterns, and guide future improvements to datasets and models.
+
+## Overview: What Are Annotations?
+
+**Annotations** are tags and metadata that can be used to label predictions, inputs, or other artifacts during model development and evaluation. They help **organize, classify, and track model behavior** during experimentation and production.
+
+You can see the tags and metadata in the [Log Streams](/concepts/logstreams) section of the [Galileo Console](https://app.galileo.ai/).
+
+These labels can represent:
+
+- Model issues (e.g., `label_mismatch`, `low_confidence`)
+- Observations from human reviewers (e.g., `grammar_error`, `ambiguous_input`)
+- Dataset quality notes (e.g., `duplicate_sample`, `out_of_distribution`)
+- Business-specific labels (e.g., `escalation_required`, `VIP_customer`)
+
+### Why Use Annotations?
+
+Annotations are particularly useful for:
+
+- **Team collaboration**: Share insights across teams with consistent tagging systems.
+- **Tracking model behavior**: Label samples where the model fails or performs below expectations.
+- **Data quality analysis**: Flag problematic or noisy inputs for later review or exclusion.
+- **Model evaluation**: Filter and analyze annotated data to evaluate model performance on specific slices.
+- **Automated improvement**: Create feedback loops between model outputs and annotation-guided dataset refinement.
+
+---
+
+## Getting Started with Annotations
+
+Follow this step-by-step guide to get started using **Annotations** in your AI projects.
+
+### Prerequisites
+
+First, follow the [Getting Started with Galileo](/getting-started/quickstart) guide if you don't already have a Galileo Project set up.
+
+Then, use the following steps to add annotations to your Project.
+
+### Step 1: Open Your Galileo App
+
+Open your Galileo application in your code editor.
+
+In this guide, we are using the **finished demo application** from the [Getting Started](/getting-started/quickstart) guide.
+
+Each code snippet in the following steps will be added to the end of the [Getting Started](/getting-started/quickstart) demo code.
+
+<CodeGroup>
+<SnippetAnnotations1 />
+</CodeGroup>
+
+### Step 2: Define Tags and Metadata
+
+Create **descriptive tags and metadata** to be attached to your logs. Both [Spans](/concepts/spans) and [Traces](/concepts/traces) can have their own tags and metadata.
+
+Define `tags` as a list of relevant labels, and `metadata` as a dictionary of label types and their values. The individual tag and metadata values must be strings.
+
+- **NOTE** : The `answer` variable is set to the raw text output of the model so that it can be used later.
+
+<CodeGroup>
+<SnippetAnnotations2 />
+</CodeGroup>
+
+### Step 3: Initialize Galileo Logger
+
+Initialize logging by importing and calling the **Galileo Logger**.
+
+The **Project name** and **Log Stream name** are used as inputs to define in which Galileo Project and log stream the logs will be created.
+
+After running our application, the logs will appear in the chosen Project's log stream in the [Galileo Console](https://app.galileo.ai/).
+
+<CodeGroup>
+<SnippetAnnotations3 />
+</CodeGroup>
+
+### Step 4: Initialize New Trace
+
+Initialize a new [Trace](/concepts/traces) to start listening for data to log.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Trace.
+
+_From your terminal, execute (replace placeholders with real values):_
+
+<CodeGroup>
+<SnippetAnnotations4 />
+</CodeGroup>
+
+### Step 5: Create New Span
+
+Create a new [Span](/concepts/spans) containing the data created by running the LLM.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Span.
+
+**NOTE** : In this guide, the tags and metadata used for the Span and the Trace are identical. But, they don't have to be. You can use different tags and metadata for Spans and the Traces they're attached to.
+
+<CodeGroup>
+<SnippetAnnotations5 />
+</CodeGroup>
+
+### Step 6: Close Trace & Push Logs
+
+To close the new Trace and **complete the logging session**, we use `logger.conclude()` with the LLM's raw text output as the input.
+
+Then, `logger.flush()` pushes the logs to the selected Project's [Log Stream](/concepts/logstreams).
+
+<CodeGroup>
+<SnippetAnnotations6 />
+</CodeGroup>
+
+### Step 7: Review Your Code
+
+By adding each previous code snippet to your Galileo application, it is ready to run and create annotated logs.
+
+Below is the **final combined application code** for the [Getting Started](/getting-started/quickstart) demo application, with our annotated log functionality added to it. 
+
+<CodeGroup>
+<SnippetAnnotations7 />
+</CodeGroup>
+
+### Step 8: Run Your Application
+
+Run your Galileo application.
+
+If your application file is named `app` (as in the [Getting Started](/getting-started/quickstart) demo), you can run it by using the following command in your terminal.
+
+<CodeGroup>
+<SnippetAnnotations8 />
+</CodeGroup>
+
+### Step 9: Open Project in Galileo Console
+
+In the [Galileo Console](https://app.galileo.ai/), select your Project and Log Stream in the top-left corner.
+
+For **each time you run your application**, you will see a new Trace entry in your Log Stream.
+
+Each metadata key-value pair is displayed in its own column, which can be used for sorting and filtering.
+
+<Screenshot
+  alt="Log Stream"
+  imageUrl="/images/console-ui/annotated-log-stream.png"
+/>
+
+### Step 10: View Trace Annotations
+
+Click on an entry in the list.
+
+You will see the data logged to the Trace. This includes:
+- The raw text input (because we initialized the Trace with `input=prompt`)
+- The raw text output from the LLM (because we closed the Trace with `logger.conclude(answer)`)
+- The tags and metadata we created (found in the **Parameters** section in the top-right)
+
+<Screenshot
+  alt="Annotated Trace"
+  imageUrl="/images/console-ui/annotated-trace.png"
+/>
+
+### Step 11: View Span Annotations
+
+With the Trace open, click the `llm` button below `Trace` in the data map on the left.
+
+You will see the data logged to the Span. This includes:
+- The complete JSON LLM input (because we created the Span with `input=[{"role": "system", "content": prompt}]`)
+- The complete JSON LLM output (because we created the Span with `output=response.choices[0].message.content`)
+- The tags and metadata we created (found in the **Parameters** section in the top-right)
+
+<Screenshot
+  alt="Annotated Span"
+  imageUrl="/images/console-ui/annotated-span.png"
+/>
path: concepts/annotations.mdx
user: login: jimbobbennett
body: ```suggestion
![Annotated Span](/images/console-ui/annotated-span.png)
```
created_at: 2025-05-07T23:53:20Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,44 @@
+```bash Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+# The Galileo context manager will automatically create a trace and flush the logs when exiting
+with galileo_context():
+    prompt = f"Explain the following topic succinctly: Newton's First Law"
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "system", "content": prompt}],
+    )
+    print(response.choices[0].message.content.strip())
+```
+
+```bash Typescript
+TYPESCRIPT_CODEimport { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+# The Galileo context manager will automatically create a trace and flush the logs when exiting
+init({
+  projectName: "my-project",
+  logStreamName: "development"
path: snippets/code/multilingual/annotations/annotations-1.mdx
user: login: jimbobbennett
body: ```suggestion
  projectName: process.env.GALILEO_PROJECT,
  logStreamName: process.env.GALILEO_LOG_STREAM
```
created_at: 2025-05-07T23:55:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,22 @@
+```bash Python
+## Include GalileoLogger in imports
+from galileo import galileo_context, GalileoLogger
+
+...application code...
+
+## Initialize logger and select project and log stream
+logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
+```
+
+```bash Typescript
+// Include GalileoLogger in imports
+import { GalileoLogger } from "galileo";
+
+...application code...
+
+// Initialize logger and select project and log stream
+const logger = new GalileoLogger({
+  project: "Science Exploration",
+  logStream: "laws-of-science"
path: snippets/code/multilingual/annotations/annotations-3.mdx
user: login: jimbobbennett
body: ```suggestion
  project: process.env.GALILEO_PROJECT,
  logStream: process.env.GALILEO_LOG_STREAM
```
created_at: 2025-05-07T23:57:12Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,22 @@
+```bash Python
+## Include GalileoLogger in imports
+from galileo import galileo_context, GalileoLogger
+
+...application code...
+
+## Initialize logger and select project and log stream
+logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
path: snippets/code/multilingual/annotations/annotations-3.mdx
user: login: jimbobbennett
body: ```suggestion
logger = GalileoLogger(project=os.environ.get("GALILEO_PROJECT"), 
                                        log_stream=os.environ.get("GALILEO_LOG_STREAM"))
```
created_at: 2025-05-07T23:58:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,109 @@
+```bash Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+# The Galileo context manager will automatically create a Trace and flush the logs when exiting
+with galileo_context():
+    prompt = f"Explain the following topic succinctly: Newton's First Law"
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "system", "content": prompt}],
+    )
+    print(response.choices[0].message.content.strip())
+
+    answer = response.choices[0].message.content.strip()
+    
+    ## Define tags and metadata
+    tags = ["newton", "test", "new-version"]
+    metadata = {"experimentNumber": "1", \
+                "promptVersion": "0.0.1", \
+                "field": "physics"}
+
+    ## Initialize logger and select project and log stream
+    logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
+
+    ## Initialize a new Trace and start listening for logs to add to it
+    trace = logger.start_trace(
+        input=prompt,
+        tags=tags,
+        metadata=metadata
+    )
+
+    ## Create a span to log LLM outputs. This is captured by the Trace
+    logger.add_llm_span(
+        input=[{"role": "system", "content": prompt}],
+        output=response.choices[0].message.content,
+        model="gpt-4o",
+        tags=tags,
+        metadata=metadata
+    )
+
+    ## Close the Trace and push captured logs to it
+    logger.conclude(answer)
+    logger.flush()
+```
+
+```bash Typescript
+import * as dotenv from "dotenv";
+dotenv.config();
+
+import { withGalileo, GalileoLogger } from "galileo";
+import { OpenAI } from "openai";
+import { wrapOpenAI } from "galileo/wrappers";
+
+const client = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY ?? "" }));
+
+await withGalileo(
+  { project: "Science Exploration", logStream: "laws-of-science" },
+  async () => {
+    const prompt = `Explain the following topic succinctly: Newton's First Law`;
+
+    const response = await client.chat.completions.create({
+      model: "gpt-4o",
+      messages: [{ role: "system", content: prompt }]
+    });
+
+    const answer: string = response.choices[0].message.content.trim();
+
+    // Define tags and metadata
+    const tags = ["newton", "test", "new-version"];
+    const metadata = {
+      experimentNumber: "1",
+      promptVersion: "0.0.1",
+      field: "physics"
+    };
+
+    // Initialize logger and select project and log stream
+    const logger = new GalileoLogger({
+      project: "Science Exploration",
+      logStream: "laws-of-science"
path: snippets/code/multilingual/annotations/annotations-7.mdx
user: login: jimbobbennett
body: ```suggestion
        project: process.env.GALILEO_PROJECT,
        logStream: process.env.GALILEO_LOG_STREAM
```
created_at: 2025-05-07T23:59:36Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,109 @@
+```bash Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+# The Galileo context manager will automatically create a Trace and flush the logs when exiting
+with galileo_context():
+    prompt = f"Explain the following topic succinctly: Newton's First Law"
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "system", "content": prompt}],
+    )
+    print(response.choices[0].message.content.strip())
+
+    answer = response.choices[0].message.content.strip()
+    
+    ## Define tags and metadata
+    tags = ["newton", "test", "new-version"]
+    metadata = {"experimentNumber": "1", \
+                "promptVersion": "0.0.1", \
+                "field": "physics"}
+
+    ## Initialize logger and select project and log stream
+    logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
path: snippets/code/multilingual/annotations/annotations-7.mdx
user: login: jimbobbennett
body: ```suggestion
    logger = GalileoLogger(project=os.environ.get("GALILEO_PROJECT"), 
                                            log_stream=os.environ.get("GALILEO_LOG_STREAM"))
```
created_at: 2025-05-08T00:00:23Z
author_association: CONTRIBUTOR
path: concepts/annotations.mdx
user: login: jimbobbennett
body: There's a lot of steps here for a concept document. I'd strip back a lot of the steps, and just show a code example of adding tags and metadata to a trace. If you want to keep the detailed steps, then you could always create a how to guide with them.
created_at: 2025-05-08T01:44:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -207,16 +207,16 @@
           "concepts/logstreams",
           "concepts/traces",
           "concepts/spans",
-          {
-            "group": "Experiments",
path: docs.json
user: login: jimbobbennett
body: This removes the experiments group. Can you put this all back please.
created_at: 2025-05-12T13:56:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,92 @@
+---
+title: Annotations Overview
+---
+
+import SnippetAnnotationsOverviewPython1 from '/snippets/code/python/annotations/overview/overview-py-1.mdx';
+import SnippetAnnotationsOverviewPython2 from '/snippets/code/python/annotations/overview/overview-py-2.mdx';
+import SnippetAnnotationsOverviewTypeScript1 from '/snippets/code/typescript/annotations/overview/overview-ts-1.mdx';
+import SnippetAnnotationsOverviewTypeScript2 from '/snippets/code/typescript/annotations/overview/overview-ts-2.mdx';
+
+Galileo's **Annotations** feature helps teams label, categorize, and analyze model outputs more effectively. Annotations provide a structured way to add human-in-the-loop feedback, highlight model behavior patterns, and guide future improvements to datasets and models.
+
+## Overview: What Are Annotations?
+
+**Annotations** are tags and metadata that can be used to label predictions, inputs, or other artifacts during model development and evaluation. They help **organize, classify, and track model behavior** during experimentation and production.
+
+You can see the tags and metadata in the [Log Streams](/concepts/logstreams) section of the [Galileo Console](https://app.galileo.ai/).
+
+These labels can represent:
+
+- Model issues (e.g., `label_mismatch`, `low_confidence`)
+- Observations from human reviewers (e.g., `grammar_error`, `ambiguous_input`)
+- Dataset quality notes (e.g., `duplicate_sample`, `out_of_distribution`)
+- Business-specific labels (e.g., `escalation_required`, `VIP_customer`)
+
+## Why Use Annotations?
+
+Annotations are particularly useful for:
+
+- **Team collaboration**: Share insights across teams with consistent tagging systems.
+- **Tracking model behavior**: Label samples where the model fails or performs below expectations.
+- **Data quality analysis**: Flag problematic or noisy inputs for later review or exclusion.
+- **Model evaluation**: Filter and analyze annotated data to evaluate model performance on specific slices.
+- **Automated improvement**: Create feedback loops between model outputs and annotation-guided dataset refinement.
+
+## Tags & Metadata
+
+Annotations are added to logged Traces and Spans in the form of **tags** and **metadata**.
+
+**Tags** - short, flat labels (strings) you assign to a trace or span to make them easy to group and filter.
+* Unlimited number of tags per trace/span (practical limit ≈ 50)
+* Case‑sensitive strings ≤ 50 chars each (v2docs.galileo.ai)
path: concepts/annotations/overview.mdx
user: login: jimbobbennett
body: Why do we have the URL of the docs here?
created_at: 2025-05-12T16:36:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,92 @@
+---
+title: Annotations Overview
+---
+
+import SnippetAnnotationsOverviewPython1 from '/snippets/code/python/annotations/overview/overview-py-1.mdx';
+import SnippetAnnotationsOverviewPython2 from '/snippets/code/python/annotations/overview/overview-py-2.mdx';
+import SnippetAnnotationsOverviewTypeScript1 from '/snippets/code/typescript/annotations/overview/overview-ts-1.mdx';
+import SnippetAnnotationsOverviewTypeScript2 from '/snippets/code/typescript/annotations/overview/overview-ts-2.mdx';
+
+Galileo's **Annotations** feature helps teams label, categorize, and analyze model outputs more effectively. Annotations provide a structured way to add human-in-the-loop feedback, highlight model behavior patterns, and guide future improvements to datasets and models.
+
+## Overview: What Are Annotations?
+
+**Annotations** are tags and metadata that can be used to label predictions, inputs, or other artifacts during model development and evaluation. They help **organize, classify, and track model behavior** during experimentation and production.
+
+You can see the tags and metadata in the [Log Streams](/concepts/logstreams) section of the [Galileo Console](https://app.galileo.ai/).
+
+These labels can represent:
+
+- Model issues (e.g., `label_mismatch`, `low_confidence`)
+- Observations from human reviewers (e.g., `grammar_error`, `ambiguous_input`)
+- Dataset quality notes (e.g., `duplicate_sample`, `out_of_distribution`)
+- Business-specific labels (e.g., `escalation_required`, `VIP_customer`)
+
+## Why Use Annotations?
+
+Annotations are particularly useful for:
+
+- **Team collaboration**: Share insights across teams with consistent tagging systems.
+- **Tracking model behavior**: Label samples where the model fails or performs below expectations.
+- **Data quality analysis**: Flag problematic or noisy inputs for later review or exclusion.
+- **Model evaluation**: Filter and analyze annotated data to evaluate model performance on specific slices.
+- **Automated improvement**: Create feedback loops between model outputs and annotation-guided dataset refinement.
+
+## Tags & Metadata
+
+Annotations are added to logged Traces and Spans in the form of **tags** and **metadata**.
+
+**Tags** - short, flat labels (strings) you assign to a trace or span to make them easy to group and filter.
+* Unlimited number of tags per trace/span (practical limit ≈ 50)
+* Case‑sensitive strings ≤ 50 chars each (v2docs.galileo.ai)
+* Ideal for boolean‑style filters (e.g., “show me all traces tagged physics”)
+
+**Metadata** - key‑value dictionaries that travel with a trace or a span, perfect for structured information like user IDs, experiment hashes, timestamps, or numeric metrics.
+* Keys and values are strings ≤ 256 chars
+* Appears in Log Streams as new columns
+* Ideal for structured attributes you can filter, group, and aggregate
+
+
+## Adding Annotations to Traces
+
+To add annotations to your [Traces](/concepts/traces), initialize the Galileo Logger, and then include tags and metadata when you start your Trace.
+
+<CodeGroup>
+<SnippetAnnotationsOverviewPython1 />
+<SnippetAnnotationsOverviewTypeScript1 />
+</CodeGroup>
+
+
+## Adding Annotations to Spans
+
+Attach annotations to your [Spans](/concepts/spans) by including tags and metadata when you add your Span.
+
+<CodeGroup>
+<SnippetAnnotationsOverviewPython2 />
+<SnippetAnnotationsOverviewTypeScript2 />
+</CodeGroup>
+
+
+## Annotations in the Galileo Console
+
+Tags and metadata appear within the selected Project and Log Stream in the [Galileo Console](https://app.galileo.ai/).
+
+You can view the tags and metadata attached to Traces and Spans in their **"Parameters"** section.
+
+![Annotated Log Stream](/images/console-ui/annotations-and-parameters-in-trace.png)
+
+Additionally, metadata appears as **new columns in the Log Stream**.
+
+![Annotations in Parameters](/images/console-ui/annotated-log-stream.png)
+
+## Best Practices
+
+* Tag early. Start the trace yourself and pass tags before the first LLM call; otherwise auto‑spans may end up in an untagged trace. (v2docs.galileo.ai)
path: concepts/annotations/overview.mdx
user: login: jimbobbennett
body: Again - why is the docs URL here?
created_at: 2025-05-12T16:38:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,21 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+// The Galileo context manager will automatically create a trace and flush the logs when exiting
+init({
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx
user: login: jimbobbennett
body: Do we need these? Don't they get loaded from the .env automatically? If not, we should load the env vars instead of hard coding.
created_at: 2025-05-12T16:39:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,12 @@
+```typescript TypeScript
+// Include GalileoLogger in imports
+import { GalileoLogger } from "galileo";
+
+...application code...
+
+// Initialize logger and select project and log stream
+const logger = new GalileoLogger({
+    project: "Science Exploration",
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-3.mdx
user: login: jimbobbennett
body: Again - shouldn't this come from the .env?
created_at: 2025-05-12T16:40:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,57 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
user: login: jimbobbennett
body: Do we need to use the wrapped version? We are added the LLM span manually, so won't this create a duplicate span?
created_at: 2025-05-12T16:41:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,21 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx
user: login: jimbobbennett
body: Do we need to use the wrapped version? We are added the LLM span manually, so won't this create a duplicate span?
created_at: 2025-05-12T16:41:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,166 @@
+---
+title: Adding Annotations
+---
+
+import SnippetAnnotationsWalkthroughPython1 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-1.mdx';
+import SnippetAnnotationsWalkthroughPython2 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-2.mdx';
+import SnippetAnnotationsWalkthroughPython3 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-3.mdx';
+import SnippetAnnotationsWalkthroughPython4 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-4.mdx';
+import SnippetAnnotationsWalkthroughPython5 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-5.mdx';
+import SnippetAnnotationsWalkthroughPython6 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-6.mdx';
+import SnippetAnnotationsWalkthroughPython7 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-7.mdx';
+import SnippetAnnotationsWalkthroughPython8 from '/snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-8.mdx';
+import SnippetAnnotationsWalkthroughTypeScript1 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx';
+import SnippetAnnotationsWalkthroughTypeScript2 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-2.mdx';
+import SnippetAnnotationsWalkthroughTypeScript3 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-3.mdx';
+import SnippetAnnotationsWalkthroughTypeScript4 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-4.mdx';
+import SnippetAnnotationsWalkthroughTypeScript5 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-5.mdx';
+import SnippetAnnotationsWalkthroughTypeScript6 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-6.mdx';
+import SnippetAnnotationsWalkthroughTypeScript7 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx';
+import SnippetAnnotationsWalkthroughTypeScript8 from '/snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-8.mdx';
+
+Follow this step-by-step guide to get started using **Annotations** in your AI projects.
+
+### Prerequisites
+
+First, follow the [Getting Started with Galileo](/getting-started/quickstart) guide if you don't already have a Galileo Project set up.
+
+Then, use the following steps to add annotations to your Project.
+
+### Step 1: Open Your Galileo App
+
+Open your Galileo application in your code editor.
+
+In this guide, we are using the **finished demo application** from the [Getting Started](/getting-started/quickstart) guide.
+
+Each code snippet in the following steps will be added to the end of the [Getting Started](/getting-started/quickstart) demo code.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython1 />
+<SnippetAnnotationsWalkthroughTypeScript1 />
+</CodeGroup>
+
+### Step 2: Define Tags and Metadata
+
+Create **descriptive tags and metadata** to be attached to your logs. Both [Spans](/concepts/spans) and [Traces](/concepts/traces) can have their own tags and metadata.
+
+Define `tags` as a list of relevant labels, and `metadata` as a dictionary of label types and their values. The individual tag and metadata values must be strings.
+
+- **NOTE** : The `answer` variable is set to the raw text output of the model so that it can be used later.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython2 />
+<SnippetAnnotationsWalkthroughTypeScript2 />
+</CodeGroup>
+
+### Step 3: Initialize Galileo Logger
+
+Initialize logging by importing and calling the **Galileo Logger**.
+
+The **Project name** and **Log Stream name** are used as inputs to define in which Galileo Project and log stream the logs will be created.
+
+After running our application, the logs will appear in the chosen Project's log stream in the [Galileo Console](https://app.galileo.ai/).
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython3 />
+<SnippetAnnotationsWalkthroughTypeScript3 />
+</CodeGroup>
+
+### Step 4: Initialize New Trace
+
+Initialize a new [Trace](/concepts/traces) to start listening for data to log.
+
+By using the `tags` and `metadata` inputs, our annotations are attached to the Trace.
+
+<CodeGroup>
+<SnippetAnnotationsWalkthroughPython4 />
+<SnippetAnnotationsWalkthroughTypeScript4 />
+</CodeGroup>
+
+### Step 5: Create New Span
+
+Create a new [Span](/concepts/spans) containing the data created by running the LLM.
path: concepts/annotations/annotations-walkthrough.mdx
user: login: jimbobbennett
body: Don't we also need to change this example to not use the wrapped version? Otherwise we get duplicated LLM spans
created_at: 2025-05-12T16:42:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,19 @@
+```python Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
path: snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-1.mdx
user: login: jimbobbennett
body: Don't we need to change this to not use the wrapped version? Otherwise we'll get duplicated LLM spans
created_at: 2025-05-12T16:42:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,50 @@
+```python Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
path: snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-7.mdx
user: login: jimbobbennett
body: Don't we need to change this to not use the wrapped version? Otherwise we'll get duplicated LLM spans
created_at: 2025-05-12T16:43:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,9 @@
+```python Python
+# Include GalileoLogger in imports
+from galileo import galileo_context, GalileoLogger
+
+...application code...
+
+# Initialize logger and select project and log stream
+logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
path: snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-3.mdx
user: login: jimbobbennett
body: These should come from the .env
created_at: 2025-05-12T16:47:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,50 @@
+```python Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
+
+# The Galileo context manager will automatically create a Trace and flush the logs when exiting
+with galileo_context():
+    prompt = f"Explain the following topic succinctly: Newton's First Law"
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "system", "content": prompt}],
+    )
+    print(response.choices[0].message.content.strip())
+
+    answer = response.choices[0].message.content.strip()
+    
+    # Define tags and metadata
+    tags = ["newton", "test", "new-version"]
+    metadata = {"experimentNumber": "1",
+                "promptVersion": "0.0.1",
+                "field": "physics"}
+
+    # Initialize logger and select project and log stream
+    logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
path: snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-7.mdx
user: login: jimbobbennett
body: These should come from the .env
created_at: 2025-05-12T16:47:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,57 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+// The Galileo context manager will automatically create a trace and flush the logs when exiting
+init({
+    project: "Science Exploration",
+    logStream: "laws-of-science"
+});
+
+const prompt = "Explain the following topic succinctly: Newton's First Law";
+const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: [{ content: prompt, role: "system" }],
+});
+
+const answer: string = response.choices[0].message.content.trim();
+
+// Define tags and metadata
+const tags = ["newton", "test", "new-version"];
+const metadata = {
+    experimentNumber: "1",
+    promptVersion: "0.0.1",
+    field: "physics"
+};
+
+// Initialize logger and select project and log stream
+const logger = new GalileoLogger({
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
user: login: jimbobbennett
body: This isn't defined:

```
/Users/jimbobbennett/github/first-AI-evaluation/app.ts:32
const logger = new GalileoLogger({
               ^


ReferenceError: GalileoLogger is not defined
    at <anonymous> (/Users/jimbobbennett/github/first-AI-evaluation/app.ts:32:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
```
created_at: 2025-05-12T16:59:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,5 @@
+```typescript TypeScript
+// Close the Trace and push captured logs to it
+logger.conclude(answer);
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-6.mdx
user: login: jimbobbennett
body: Is this right? Shouldn't this take an object with an output field?
created_at: 2025-05-12T17:08:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,57 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+// The Galileo context manager will automatically create a trace and flush the logs when exiting
+init({
+    project: "Science Exploration",
+    logStream: "laws-of-science"
+});
+
+const prompt = "Explain the following topic succinctly: Newton's First Law";
+const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: [{ content: prompt, role: "system" }],
+});
+
+const answer: string = response.choices[0].message.content.trim();
+
+// Define tags and metadata
+const tags = ["newton", "test", "new-version"];
+const metadata = {
+    experimentNumber: "1",
+    promptVersion: "0.0.1",
+    field: "physics"
+};
+
+// Initialize logger and select project and log stream
+const logger = new GalileoLogger({
+    project: "Science Exploration",
+    logStream: "laws-of-science"
+});
+
+// Initialize a new Trace and start listening for logs to add to it
+const trace = logger.startTrace({
+    input: prompt,
+    tags: tags,
+    metadata: metadata
+});
+
+// Create a span to log LLM outputs. This is captured by the Trace
+logger.addLlmSpan({
+    input: [{ role: "system", content: prompt }],
+    output: response.choices[0].message.content,
+    model: "gpt-4o",
+    tags: tags,
+    metadata: metadata
+});
+
+// Close the Trace and push captured logs to it
+logger.conclude(answer);
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
user: login: jimbobbennett
body: Again - is this the right syntax?
created_at: 2025-05-12T17:09:08Z
author_association: CONTRIBUTOR
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
user: login: jimbobbennett
body: I cannot get this to trace. Not sure if it is an issue with the TypeScript SDK or this code. Please check and if it is an SDK issue, raise it in shortcut.
created_at: 2025-05-12T17:09:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -207,16 +207,16 @@
           "concepts/logstreams",
           "concepts/traces",
           "concepts/spans",
-          {
-            "group": "Experiments",
path: docs.json
user: login: EvanGottschalk
body: Woah, good catch!! Sorry about that.
created_at: 2025-05-13T05:28:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,92 @@
+---
+title: Annotations Overview
+---
+
+import SnippetAnnotationsOverviewPython1 from '/snippets/code/python/annotations/overview/overview-py-1.mdx';
+import SnippetAnnotationsOverviewPython2 from '/snippets/code/python/annotations/overview/overview-py-2.mdx';
+import SnippetAnnotationsOverviewTypeScript1 from '/snippets/code/typescript/annotations/overview/overview-ts-1.mdx';
+import SnippetAnnotationsOverviewTypeScript2 from '/snippets/code/typescript/annotations/overview/overview-ts-2.mdx';
+
+Galileo's **Annotations** feature helps teams label, categorize, and analyze model outputs more effectively. Annotations provide a structured way to add human-in-the-loop feedback, highlight model behavior patterns, and guide future improvements to datasets and models.
+
+## Overview: What Are Annotations?
+
+**Annotations** are tags and metadata that can be used to label predictions, inputs, or other artifacts during model development and evaluation. They help **organize, classify, and track model behavior** during experimentation and production.
+
+You can see the tags and metadata in the [Log Streams](/concepts/logstreams) section of the [Galileo Console](https://app.galileo.ai/).
+
+These labels can represent:
+
+- Model issues (e.g., `label_mismatch`, `low_confidence`)
+- Observations from human reviewers (e.g., `grammar_error`, `ambiguous_input`)
+- Dataset quality notes (e.g., `duplicate_sample`, `out_of_distribution`)
+- Business-specific labels (e.g., `escalation_required`, `VIP_customer`)
+
+## Why Use Annotations?
+
+Annotations are particularly useful for:
+
+- **Team collaboration**: Share insights across teams with consistent tagging systems.
+- **Tracking model behavior**: Label samples where the model fails or performs below expectations.
+- **Data quality analysis**: Flag problematic or noisy inputs for later review or exclusion.
+- **Model evaluation**: Filter and analyze annotated data to evaluate model performance on specific slices.
+- **Automated improvement**: Create feedback loops between model outputs and annotation-guided dataset refinement.
+
+## Tags & Metadata
+
+Annotations are added to logged Traces and Spans in the form of **tags** and **metadata**.
+
+**Tags** - short, flat labels (strings) you assign to a trace or span to make them easy to group and filter.
+* Unlimited number of tags per trace/span (practical limit ≈ 50)
+* Case‑sensitive strings ≤ 50 chars each (v2docs.galileo.ai)
path: concepts/annotations/overview.mdx
user: login: EvanGottschalk
body: Erroneous miss-paste. Thanks, Jim!
created_at: 2025-05-13T05:28:26Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,21 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+// The Galileo context manager will automatically create a trace and flush the logs when exiting
+init({
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-1.mdx
user: login: EvanGottschalk
body: You are correct! With the .env, all of the keys and names are automatically utilized.
created_at: 2025-05-13T05:28:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,57 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
user: login: EvanGottschalk
body: I wasn't getting a duplicate span with TypeScript. But, either way, I removed the wrapper - it's unnecessary, as you've said.
created_at: 2025-05-13T05:28:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,19 @@
+```python Python
+import os
+from galileo import galileo_context, GalileoLogger # The Galileo context manager
+from galileo.openai import openai # The Galileo OpenAI client wrapper
+from dotenv import load_dotenv
+load_dotenv()
+
+# Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+client = openai.OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
path: snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-1.mdx
user: login: EvanGottschalk
body: You are spot on. I've removed this wrapper.
created_at: 2025-05-13T05:29:03Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,9 @@
+```python Python
+# Include GalileoLogger in imports
+from galileo import galileo_context, GalileoLogger
+
+...application code...
+
+# Initialize logger and select project and log stream
+logger = GalileoLogger(project="Science Exploration", log_stream="laws-of-science")
path: snippets/code/python/annotations/walkthrough/annotations-walkthrough-py-3.mdx
user: login: EvanGottschalk
body: Absolutely! I have removed them.
created_at: 2025-05-13T05:29:12Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,57 @@
+```typescript TypeScript
+import { OpenAI } from "openai";
+import { init, flush, wrapOpenAI } from "galileo";
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Initialize the OpenAI client using the Galileo wrapper and your OpenAI API key
+const openai = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+
+// The Galileo context manager will automatically create a trace and flush the logs when exiting
+init({
+    project: "Science Exploration",
+    logStream: "laws-of-science"
+});
+
+const prompt = "Explain the following topic succinctly: Newton's First Law";
+const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: [{ content: prompt, role: "system" }],
+});
+
+const answer: string = response.choices[0].message.content.trim();
+
+// Define tags and metadata
+const tags = ["newton", "test", "new-version"];
+const metadata = {
+    experimentNumber: "1",
+    promptVersion: "0.0.1",
+    field: "physics"
+};
+
+// Initialize logger and select project and log stream
+const logger = new GalileoLogger({
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
user: login: EvanGottschalk
body: Good find - the import of GalileoLogger made it into an earlier step, but got missed here. Now, with the GalileoLogger imported, there should be no errors.
created_at: 2025-05-13T05:29:22Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,5 @@
+```typescript TypeScript
+// Close the Trace and push captured logs to it
+logger.conclude(answer);
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-6.mdx
user: login: EvanGottschalk
body: That's right. The `output` field is necessary in TypeScript. I've added it to the snippets.
created_at: 2025-05-13T05:29:28Z
author_association: CONTRIBUTOR
path: snippets/code/typescript/annotations/walkthrough/annotations-walkthrough-ts-7.mdx
user: login: EvanGottschalk
body: It's all because the Galileo Logger got left out of the complete code snippet. I've added it back in, and she's running just fine now.
created_at: 2025-05-13T05:29:37Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-05-11T23:12:20Z
body: ✅ Mintlify Dev Server Started Successfully!

The documentation can be served without errors.
<!-- Sticky Pull Request Commentmintlify-dev -->
author_association: NONE
user: login: EvanGottschalk
created_at: 2025-05-11T23:39:48Z
body: Conflicts are resolved. Should be ready to merge.
author_association: CONTRIBUTOR
user: login: EvanGottschalk
created_at: 2025-05-13T05:30:39Z
body: @jimbobbennett I've addressed your latest comments. Let me know what you think now.

Thanks for all your help! ^__^
author_association: CONTRIBUTOR