Merge branch 'main' into haystack-integration

Author: LeoRoccoBreedt

.github/pull_request_template.md

@@ -7,6 +7,8 @@ Closes #<!-- the tracking issue this PR implements; comment on it to claim it be
 ## Checklist
 
 <!-- See CONTRIBUTING.md for details. Tick what applies; delete rows that don't. -->
+<!-- Adding a community index entry (community/projects.yaml)? Only the rules in
+     community/CONTRIBUTING.md apply — delete this checklist. -->
 
 - [ ] Linked to its tracking issue (commented to claim it before starting)
 - [ ] Example is in the right bucket (`integrations` / `guides` / `use-cases` / `scripts`)

.github/workflows/community-check.yml

@@ -1,10 +1,11 @@
-name: Community Entry Check
-
-# Lightweight, non-executing gate for community showcase entries.
-# It does NOT run contributor code. It validates entry structure, scans for
-# committed secrets, and confirms hosted entries use Opik. Secrets-free, so it
-# runs on forks. The showcase index (community/README.md) is regenerated
-# separately on merge by community-index.yml — contributors run nothing.
+name: Community Projects Check
+
+# Lightweight, non-executing gate for the community index. Community projects
+# are links-only — code lives in the authors' repos — so this only validates
+# community/projects.yaml (required fields, valid repo URLs/handles, no
+# duplicates). Secrets-free, so it runs on forks. The index
+# (community/README.md) is regenerated separately on merge by
+# community-index.yml — contributors run nothing.
 #
 # Community entries are intentionally exempt from the verified-bucket workflows
 # (compliance / pr-test / test-notebooks / scheduled), which are path-scoped to
@@ -47,7 +48,7 @@ jobs:
           uv run ruff check .
           uv run ruff format --check .
 
-      - name: Validate all community entries
+      - name: Validate community projects
         run: |
           cd community/_ci
-          uv run python check_entry.py
+          uv run python check_projects.py

.github/workflows/community-index.yml

@@ -1,9 +1,9 @@
 name: Community Index
 
-# Regenerates the community showcase index (community/README.md) from every
-# entry's meta.yaml after changes land on main. This keeps the index current
-# with zero manual action — contributors never run the generator, and no one
-# hand-edits community/README.md.
+# Regenerates the community index (community/README.md) from
+# community/projects.yaml after changes land on main. This keeps the index
+# current with zero manual action — contributors never run the generator, and
+# no one hand-edits community/README.md.
 #
 # It runs build_index.py (which only parses YAML — it never executes contributor
 # code) and commits the result back to main only if it changed. The path filter
@@ -37,7 +37,7 @@ jobs:
           enable-cache: true
           python-version: "3.12"
 
-      - name: Regenerate showcase index
+      - name: Regenerate community index
         run: |
           cd community/_ci
           uv sync
@@ -49,8 +49,8 @@ jobs:
             git config user.name "github-actions[bot]"
             git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
             git add community/README.md
-            git commit -m "chore: regenerate community showcase index"
+            git commit -m "chore: regenerate community index"
             git push
           else
-            echo "Showcase index already up to date."
+            echo "Community index already up to date."
           fi

AGENTS.md

@@ -10,9 +10,15 @@ opik-examples/
 ├── guides/         # How-to patterns for Opik workflows
 ├── use-cases/      # End-to-end applications and domain workflows
 ├── scripts/        # Utility automations and API helpers
-└── templates/      # Starter templates (use-case-template, script-template)
+├── templates/      # Starter templates (use-case-template, script-template)
+└── community/      # Curated links-only index of community-built projects
 ```
 
+The `community/` folder is not a code bucket: it is a curated index
+(`community/projects.yaml` → generated `community/README.md`) of projects that
+live in their authors' repos. It is exempt from the `run.sh` / dry-run / litellm
+contract — see [community/CONTRIBUTING.md](community/CONTRIBUTING.md).
+
 **Which bucket does new code belong in?**
 
 | If you are… | Put it in |

CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers by opening an issue in this repository or through
+[Comet support](https://www.comet.com/site/about-us/contact-us/). All
+complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[FAQ]: https://www.contributor-covenant.org/faq

README.md

@@ -13,7 +13,8 @@ opik-examples/
 ├── guides/         # How-to examples for Opik workflows and patterns
 ├── use-cases/      # End-to-end applications and domain workflows
 ├── scripts/        # Utility automations and API helpers
-└── templates/      # Starter templates (use-case-template, script-template)
+├── templates/      # Starter templates (use-case-template, script-template)
+└── community/      # Curated index of community-built projects (links only)
 ```
 
 ## Integrations
@@ -56,15 +57,17 @@ Standalone scripts for automating and managing Opik resources.
 | [scripts/automate_annotation_queue](scripts/automate_annotation_queue/) | Route traces into annotation queues via batch or real-time assignment |
 | [scripts/usage_stats](scripts/usage_stats/) | Fetch trace and span counts per project and visualise trends |
 | [scripts/leaderboard_dashboard](scripts/leaderboard_dashboard/) | Create an Experiment Leaderboard dashboard via the REST API |
+| [scripts/score_traces](scripts/score_traces/) | Score existing production traces offline with stock SDK judges/metrics, logging feedback back under the same names an online rule would use |
 
 ## Community
 
-Work built with Opik by the open-source community. Unlike the buckets above,
-these entries are **community-contributed and not maintainer-verified** — they
-showcase what people are building. Standout real-world projects get hosted
-in-repo and spotlighted in our community forums.
+A curated index of projects the open-source community has built with Opik.
+It is links-only — each project lives in its author's repository. Unlike the
+buckets above, these entries are **community-contributed and not
+maintainer-verified**.
 
-Browse them in [community/](community/), or add your own via
+Browse the table in [community/](community/), or add your own project with a
+single block in `projects.yaml` — see
 [community/CONTRIBUTING.md](community/CONTRIBUTING.md).
 
 ## Contributing

community/CONTRIBUTING.md

@@ -1,48 +1,54 @@
-# Contributing to the Community folder
+# Contributing to the Community index
 
-This folder showcases work the open-source community has built with Opik. It is
-deliberately **lighter-weight than the main repo contract** — the strict
-`run.sh` / dry-run / litellm / CI rules in the root
+This folder is a **curated, links-only index** of projects the open-source
+community has built with [Opik](https://www.comet.com/site/products/opik/).
+Your code stays in your own repository — the index just points to it. That
+means no sync issues when you update your project, and contributing takes a
+couple of minutes.
+
+The strict `run.sh` / dry-run / litellm / CI rules in the root
 [CONTRIBUTING.md](../CONTRIBUTING.md) do **not** apply here. Community entries
-are not executed by CI; a maintainer reviews (and, for hosted entries, runs)
-them by hand.
+are not executed by CI; a maintainer reviews each submission by hand.
+
+## Add your project
 
-There is one thing we always require: **proof you actually logged with Opik** —
-either Comet cloud or the self-hosted open-source platform.
+1. Add one block to [`projects.yaml`](projects.yaml):
 
-## Two kinds of entry
+   ```yaml
+   - title: Your project title
+     description: One or two sentences on what you built and how it uses Opik.
+     author: your-github-handle
+     repo: https://github.com/your-handle/your-project
+   ```
 
-- **Listed** (default): a folder describing your work with links out to your own
-  repo/blog/notebook. No code needs to live here.
-- **Hosted**: standout, real-world projects we promote into this repo with their
-  code included. You submit as *listed*; a maintainer sets `hosted: true` and
-  moves your code in when promoting. We also spotlight promoted work in our
-  community forums.
+2. Open a PR. That's it — you don't need to run anything.
 
-## Add your entry
+All four fields are required. Keep `description` under 250 characters,
+`author` a bare GitHub handle (no `@`, no URL), and `repo` an http(s) link.
+Don't edit `README.md` — it is generated from `projects.yaml` automatically
+after your PR merges.
 
-1. Copy `templates/entry-template/` to `community/<your-handle>_<project>/`
-   (lowercase, underscores, e.g. `jane_support_agent`).
-2. Fill in `meta.yaml` (all fields) and `README.md` (all four sections).
-3. Replace `opik-proof.png` with a real screenshot of your Opik traces or
-   dashboard.
-4. If you want it considered for hosting, include your code in the folder — it
-   must genuinely use Opik (`import opik`, `@opik.track`, ...).
-5. Open a PR. A maintainer reviews it.
+## Review bar
 
-That's it — you don't need to run anything. The showcase index
-(`community/README.md`) is regenerated automatically when your entry merges, so
-your project appears there without any manual step on your part.
+A maintainer checks that the linked project genuinely uses Opik (e.g.
+`import opik`, `@opik.track`, or Opik dashboards in the docs) and that the
+description is accurate. Entries are **community-contributed and not
+maintainer-verified** — we curate the list, we don't maintain the projects.
 
 ## What the automated check enforces
 
-`community/_ci/check_entry.py` runs on your PR (a hard gate). It does **not**
-run your code. It checks:
+`community/_ci/check_projects.py` runs on your PR (a hard gate). It only
+validates `projects.yaml`:
+
+- Every entry has `title`, `description`, `author`, and `repo` (and no other
+  fields).
+- `repo` is an http(s) URL and `author` is a valid GitHub handle.
+- `description` is at most 250 characters.
+- No duplicate titles or repos.
+
+## Promotion
 
-- `meta.yaml` has all required fields, at least one link, and a valid
-  `opik_platform`.
-- `README.md` has all four sections filled in (no leftover `TODO`).
-- `opik-proof.png` exists and is referenced from your README.
-- No `.env` file or hardcoded API keys are committed.
-- Hosted entries contain code that uses Opik.
-- The folder name is `lowercase_with_underscores`.
+Standout projects that meet the standards of the verified buckets
+(`integrations/`, `guides/`, `use-cases/`, `scripts/`) may be invited into the
+main repo — the root [CONTRIBUTING.md](../CONTRIBUTING.md) contract applies
+there.

community/README.md

@@ -2,11 +2,15 @@
 
 <!-- This file is generated by community/_ci/build_index.py. Do not edit by hand. -->
 
-Work built with Opik by the open-source community. These entries are
+A curated index of projects the open-source community has built with Opik. It is
+links-only: each project lives in its author's repository, and entries are
 **community-contributed and not maintainer-verified** — they are showcased here
-to help people discover what others are building. Standout, real-world projects
-are hosted in-repo (see the Hosted column).
+to help people discover what others are building.
 
-To add your own, see [CONTRIBUTING.md](CONTRIBUTING.md).
+To add yours, see [CONTRIBUTING.md](CONTRIBUTING.md) — it's one small block in
+[projects.yaml](projects.yaml).
 
-_No community contributions yet — be the first!_
+| Project | Description | Author |
+|---|---|---|
+| [Building a Coding Agent from Scratch (course)](https://github.com/decodingai-magazine/building-a-coding-agent-from-scratch-course) | An open-source course that builds a terminal coding agent from scratch, using Opik for tracing and evals. | [@decodingai-magazine](https://github.com/decodingai-magazine) |
+| [Observable Job Agent](https://github.com/jamwithai/observable-job-agent) | An observability-first CV-to-job-matching agent, instrumented with Opik from run one. | [@jamwithai](https://github.com/jamwithai) |