docs: add Synoppy tools integration (python) - #1
Open
Synoppy wants to merge 455 commits into
Open
Conversation
"is a AI-native open-source vector database" -> "is an AI-native open-source vector database". "AI" starts with a vowel sound, so the article should be "an". Docs only, no functional changes.
"on a Azure SQL vector store" -> "on an Azure SQL vector store". "Azure" starts with a vowel sound, so the article should be "an". Docs only, no functional changes.
"Setup a Ingest Pipeline" -> "Setup an Ingest Pipeline". "Ingest" starts with a vowel sound, so the article should be "an". Docs only, no functional changes.
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
…chain-ai#3735) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
…chain-ai#3974) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
…-huggingface URL rejection (langchain-ai#4726) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: KKKPJSKEY <kkkpjskey@KKKPJSKEYMacBook-Pro.local>
…#5232) Co-authored-by: markmeng0X <55173536+markmeng0X@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: renzhifei <renzhifei@pjlab.org.cn> Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
) ## Problem The SmithDB SDK migration guide documents the new v2 REST endpoints as `/v2/...`, but they are actually served under `/api/v2/...`. Confirmed against [`smith-backend/static/openapi.json`](https://github.com/langchain-ai/langchainplus/blob/main/smith-backend/static/openapi.json) on `main`, which lists `/api/v2/runs/query`, `/api/v2/runs/{run_id}`, `/api/v2/runs/{run_id}/url`, `/api/v2/runs/{run_id}/share`, `/api/v2/traces/query`, `/api/v2/traces/{trace_id}/runs`, `/api/v2/threads/query`, `/api/v2/threads/{thread_id}/traces`, `/api/v2/datasets/{dataset_id}/experiment-runs`, `/api/v2/public/{share_token}/run/{run_id}` and `/api/v2/public/{share_token}/runs/v2/query`. As written, every "after" cURL example in the guide returns a 404. ## Change Rewrote `/v2/` → `/api/v2/` in: - `src/snippets/langsmith/smithdb-migration/*.mdx` — the before/after endpoint mapping tables and prose - `src/snippets/code-samples/smithdb-migration/*-after-sh.mdx` — the cURL examples The trailing `runs/v2/query` segment of the public-runs query endpoint is part of the path itself, not the API prefix, so it is left unchanged (`/api/v2/public/{share_token}/runs/v2/query`). Every `/api/v2/...` path in the guide after this change matches a path in the OpenAPI spec.
## Overview <!-- Brief description of what documentation is being added/updated --> Creating feedback for a run now requires `session_id` / `sessionId`, the UUID of the tracing project (session) that owns the run. langchain-ai#5048 documented this in the SmithDB migration guide, but every feedback example in the regular docs still omits it, so anyone copying one gets a deprecation warning today and a hard error on SmithDB-only deployments. This updates the six pages that create run-level feedback, plus the feedback field reference. ## Type of change **Type:** Update existing documentation ## Related issues/PRs - Feature PR: langchain-ai#5048 (documented the same requirement in the SmithDB migration guide) - SDK: both the warning/error and the object-form `createFeedback` overload used here come from `langsmith-sdk` branch `emil/create-feedback-missing-session-warning-error`, which is **not released yet**. See "Release ordering" below <!-- For LangChain employees, if applicable: --> - Linear issue: - Slack thread: ## Checklist <!-- Put an 'x' in all boxes that apply --> - [x] I have read the [contributing guidelines](README.md), including the [language policy](https://docs.langchain.com/oss/python/contributing/overview#language-policy) - [x] I have tested my changes locally using `docs dev` - [x] All code examples have been tested and work correctly — every example was executed against a live workspace; see Verification - [x] I have used **root relative** paths for internal links - [x] I have updated navigation in `src/docs.json` if needed — no new pages, so no nav change ## Additional notes <!-- Any other information that would be helpful for reviewers --> ### How each page gets the project UUID Two cases, and the split matters for review: `RunTree.session_id` is declared `Optional[UUID] = None` (aliased to `project_id`) and nothing populates it client-side, and the JS `RunTree` has no such field at all. So a run traced by the app knows only its **project name** and has to resolve the UUID. Runs returned by the API do carry `session_id`, so those pages read it off the run instead. Name-based resolution uses `create_project(..., upsert=True)` / `createProject({ upsert: true })` rather than `read_project()`. A project is created on trace ingestion, so resolving it right after the first traced call can 404; `upsert` removes that race without a retry loop. Verified idempotent, and it returns the same UUID `read_project()` would for a project that already exists. | Page | How `session_id` is obtained | |---|---| | `attach-user-feedback.mdx` | `create_project(project_name=root_run.session_name, upsert=True).id`; TS resolves via `createProject()` | | `log-traces-to-project.mdx` | One resolution per replica, each against its own client, because the two replicas write to different projects under different API keys | | `observability-llm-tutorial.mdx` | Python reads `LANGSMITH_PROJECT` with a `"default"` fallback, matching `get_tracer_project()`; TS reads `runTree.project_name` | | `optimize-classifier.mdx` | The page already pins the project to `"classifier"`, so it resolves that by name | | `composite-evaluators-sdk.mdx` | `run.session_id`, straight off the run objects from `get_experiment_results()` | | `run-evals-api-only.mdx` | Adds `session_id` to the `select` list on both `/runs/query` calls, then passes `run["session_id"]` in the REST body | ### All TypeScript examples use the object-form overload Every `createFeedback` call in these docs (one on `attach-user-feedback.mdx`, two on `log-traces-to-project.mdx`, one on `observability-llm-tutorial.mdx`) now passes a single object: ```typescript await client.createFeedback({ runId, sessionId, key: "feedback-key", score: 1.0 }); ``` Two reasons, in order of importance: 1. `CreateFeedbackParams` declares `sessionId: string` as **required** when `runId` is present, so omitting it is a compile error. The three-argument overload declares `sessionId?: string`, where omitting it compiles cleanly and fails only at runtime. The type does the teaching. 2. The three-argument overload carries an `@deprecated` tag. `tsc` ignores that, but the TS language service does not, so a reader pasting a three-argument snippet into their editor sees `createFeedback` struck through. Shipping examples that an editor marks deprecated is not a good look. Property order is consistent across all four: `runId`, `sessionId`, then `key`, then the payload. ### Release ordering This is the one thing to get right before merging. The object-form overload does not exist in the published `langsmith` JS package yet, so until the SDK branch ships, these three TypeScript snippets do not compile against the released package. The Python snippets are fine either way, since `session_id` has always been an accepted keyword argument there. Merge after the SDK release, or accept a short window where the TS examples are ahead of the package. ### Other decisions worth a look - **`start_time` is not in any example.** It is accepted and improves performance, but it is not required, and threading it through six pages added noise for no teaching value. It stays documented as a row in `feedback-data-fields.mdx`. - **Pages deliberately untouched.** `presigned-feedback-tokens.mdx` and `agent-server-feedback.mdx` use the token endpoint, whose schema has no `session_id`; `annotation-queues-sdk.mdx` calls `create_feedback_config`, a different method; `audit-logs.mdx` only lists action names. ### Upstream follow-ups this PR cannot fix 1. The published `create_feedback` reference still describes `session_id` as optional ("Used to optimize feedback ingestion"), and its docstring example omits it. That example is what `attach-user-feedback.mdx` mirrors, so the two should stay in sync. 2. `langsmith-platform-openapi.json` still has `FeedbackCreateSchema.session_id` nullable, and describes the `feedback.<run_id>` multipart part as needing only `trace_id`. That file is auto-refreshed from the platform repo, so it needs an upstream change. ### Verification Every example was **executed against a live LangSmith workspace**, not just read. Each run asserted that the feedback row came back with `session_id` equal to the resolved project UUID. | Example | Result | |---|---| | `attach-user-feedback.mdx` (Python) | Both calls land; root-run and child-run feedback carry the resolved `session_id` | | `attach-user-feedback.mdx` (TypeScript) | Ran against a locally built SDK; feedback landed with the resolved `sessionId` | | `log-traces-to-project.mdx` | Two replicas resolved to two distinct project UUIDs; each feedback filed under its own project | | `observability-llm-tutorial.mdx` | Ran end to end including the OpenAI call, with a non-default `LANGSMITH_PROJECT` | | `optimize-classifier.mdx` | Ran end to end verbatim including the OpenAI call | | `composite-evaluators-sdk.mdx` | Full flow: dataset, `evaluate()` with 3 judges, then composite feedback on both runs via `run.session_id` | | `run-evals-api-only.mdx` | Both flows: single experiment (6 `correctness` rows) and pairwise (12 `ranked_preference` rows) | The assumption flagged in the previous revision is now **closed**: `get_experiment_results()` does return runs with `session_id` populated, matching the experiment's project UUID. Verified on three pre-existing experiments plus the one this PR's own run created. The TypeScript type-level claim is **verified** rather than asserted. All four documented snippets typecheck clean, and omitting `sessionId` fails to compile: ``` error TS2345: Property 'sessionId' is missing in type '{ runId: string; key: string; score: number; }' but required in type '{ runId: string; sessionId: string; projectId?: undefined; }' ``` Also verified: `session_id` comes back from `POST /runs/query`. That endpoint returned every field regardless of `select`, so adding `session_id` to the select list is explicitness rather than a strict requirement. Race fix re-verified after the switch to `upsert`: all four affected examples were re-run against **brand-new** projects that had never been traced to, with no retry loop anywhere. The replica example is the sharpest case, since it resolves two projects that the run itself has just created; it previously needed a 24-attempt retry loop in the harness and now succeeds first try. Rendering: `docs dev` (pipeline build plus `mint dev`) serves all six pages and `feedback-data-format` with HTTP 200. Spot-checked in a browser that the new `<Note>` renders as a callout, the Python tab shows the resolution line, and the imported field table shows the updated `session_id` row. Vale: 0 errors, 0 warnings, 0 suggestions across all changed files. ### TODO: pre-existing bugs found while executing (not fixed here) Both predate this PR, are unrelated to `session_id`, and reproduce on `main`. Need more investigation and fixing. - **The child-run example raises `IndexError`.** [`src/langsmith/attach-user-feedback.mdx:62`](https://github.com/langchain-ai/docs/blob/main/src/langsmith/attach-user-feedback.mdx#L62) — `foo_run_id = [run for run in child_runs if run.name == "foo"][0].id` indexes an empty list, because `child_runs` at [line 47](https://github.com/langchain-ai/docs/blob/main/src/langsmith/attach-user-feedback.mdx#L47) is always `[]`. `RunTree.child_runs` is only appended by `create_child()` (`langsmith-sdk` `python/langsmith/run_trees.py:658`), which `@traceable` no longer routes through. Confirmed by running the pre-change example straight off `main`. The same broken example is duplicated in the SDK docstring at `python/langsmith/client.py:8091` and `:8101`, so both should be fixed together. A working replacement is to fetch the child with `client.list_runs(project_name=..., trace_id=...)` after the trace is ingested. - **`from langsmith import uuid7` sits outside its code fence.** [`src/langsmith/run-evals-api-only.mdx:88`](https://github.com/langchain-ai/docs/blob/main/src/langsmith/run-evals-api-only.mdx#L88) — the fence closes at line 87 and the import lands in body prose, so it renders as a stray paragraph. A reader copying the code blocks in order hits `NameError: uuid7`, since `uuid7()` is called later at lines 154 and 158. Either move it into the block ending at line 87 or into the block that uses it. Written by Claude Opus 5 via Claude Code, under human direction and review.
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: chad gibson <chadgibson@chads-Mac-mini.local> Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: Pataridze Givi <pataridzegivi@gmail.com>
…i#4391) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
## Overview Updates the two places in the SmithDB SDK migration docs that hardcode the public shared-trace runs query URL, following the upstream path fix in langchain-ai/langchainplus#32541 (merged, not yet in production). The endpoint was served at `POST /api/v2/public/{share_token}/runs/v2/query` — `/v2` appeared twice because the route was registered under the `/v2` tree while keeping the versioned `runs/v2/query` suffix from the authenticated endpoint. The documented path is now: ``` POST /api/v2/public/{share_token}/runs/query ``` Changed: - `src/snippets/langsmith/smithdb-migration/public-runs.mdx` — the "Query public runs" row of the cURL endpoint table. - `src/snippets/code-samples/smithdb-migration/public-runs-after-sh.mdx` — the corresponding curl example. Nothing else in the repo referenced the old path. The Python, TypeScript, Java, and Go tabs call SDK methods (`client.public.runs.query()` and equivalents), whose names and request/response shapes are unchanged, so the URL is internal to the generated clients. ## Type of change **Type:** Update existing documentation ## Related issues/PRs - GitHub issue: - Feature PR: langchainplus#32541 ## Checklist <!-- Put an 'x' in all boxes that apply --> - [x] I have read the [contributing guidelines](README.md), including the [language policy](https://docs.langchain.com/oss/python/contributing/overview#language-policy) - [x] I have tested my changes locally using `docs dev` — not run; the change is two string literals inside existing snippets, with no structural or navigation change - [x] All code examples have been tested and work correctly — new path has been tested manually in preprod. - [x] I have used **root relative** paths for internal links — no links changed - [x] I have updated navigation in `src/docs.json` if needed — not needed, both files are existing snippets ## Additional notes Verified with `grep` that no other source file referenced the old path, and confirmed no page links to the generated API reference page for this endpoint. Its Mintlify slug derives from the operation summary ("Query public shared trace runs"), which the backend PR does not change, so no redirect is required. `make lint_prose` passes on both changed files. **Follow-up, after the backend PR reaches production:** regenerate the vendored spec with `python scripts/process_langsmith_openapi.py --write`. `src/langsmith/langsmith-platform-openapi.json` still carries the old path key, and the regeneration also drops the `**Alpha:** The request and response contract may change;` prefix from both public shared-trace handler descriptions. Kept out of this PR because the script fetches the live spec from `api.smith.langchain.com`. Drafted with Claude Code; updated by @emil-lc.
Co-authored-by: Bytaro <bytaro@mojobytes.ai> Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
## Summary - Document tracing direct Gemini Live WebSocket sessions with `wrap_gemini_live`. - Separate raw `google-genai` and Google ADK setup, threading, and audio guidance. - Keep existing application audio and tool handling unchanged behind the transparent wrapper. ## Why The page previously covered only Google ADK. LangSmith now also traces applications that own the Gemini Live WebSocket, parallel to the raw and framework-based OpenAI Realtime integrations. ## Testing - `make lint_prose VALE_BIN=/opt/homebrew/bin/vale FILES="src/langsmith/trace-gemini-live.mdx"` - `.venv/bin/docs build` - Parsed all six Python snippets with `ast.parse` - Validated raw Gemini Live and ADK imports against the local SDK environments ## AI assistance This PR was prepared with assistance from an AI coding agent.
…-ai#5197) ## Summary - Updates `src/langsmith/rules.mdx` to document the new per-action retention control feature for automation rules. - The old note stated "Other actions (add to dataset, add to annotation queue, trigger webhook) do not change trace retention." This is now incorrect. - Replaces the blanket statement with a per-action breakdown: - **Add to dataset** — opt-in (default: off) - **Add to annotation queue** — opt-out (default: on) - **Trigger webhook** — opt-in (default: off) - **Extend data retention** action and evaluators — unchanged - Also notes the admin-only `rules:configure-retention` RBAC gate. - Updates the introductory Note to remove the now-inaccurate "enabled by default for new rules" statement and point readers to the action-level details. ## Links - Slack: https://langchain.slack.com/archives/C09G1T60QV9/p1785357767841149 ## Verification Not run; docs-only copy change. ## Reviewers Requested review from: @katmayb, @fjmorris --------- Co-authored-by: Docs Writer <brace@langchain.dev> Co-authored-by: Kathryn May <44557882+katmayb@users.noreply.github.com> Co-authored-by: Kathryn May <kathryn@langchain.dev>
…embeddings) (langchain-ai#4438) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
…ex (Python) (langchain-ai#4456) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Package is under the 50K monthly downloads threshold, so remove the hosted tools page and surface Synoppy via partner docs, YAML, and the tools downloads table. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
20 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a tools integration page for Synoppy — it gives LangChain agents live web access without a separate scraping stack: read any URL to clean markdown, search the live web, crawl a site for RAG, and extract structured JSON. langchain-synoppy's get_synoppy_tools(api_key=...) returns all nine endpoints as StructuredTools. The page follows the tools TEMPLATE.mdx.