Skip to content

docs(oracle): correct experiments.mdx paths + add oracle-deployed.mdx#56

Merged
mangrove-one merged 1 commit into
mainfrom
docs/oracle-corrections
May 31, 2026
Merged

docs(oracle): correct experiments.mdx paths + add oracle-deployed.mdx#56
mangrove-one merged 1 commit into
mainfrom
docs/oracle-corrections

Conversation

@mangrove-one

Copy link
Copy Markdown
Member

Summary

Closes the doc-drift half of MangroveAI gh #576 (issues #1, #2, #4). The KB was claiming Oracle endpoints that don't exist at the documented paths, leaving customers staring at SPA index.html responses (issues #1 and #2) or expecting a strategy-ranking response that's actually a persona roster (#4).

Changes

docs/api-reference/experiments.mdx — endpoint table corrections:

  • POST /api/v1/oracle/simulatePOST /api/v1/oracle/simulate/run (plus new rows for /simulate/generate, /simulate/presets, /simulate/history)
  • GET /api/v1/oracle/exec-configGET /api/v1/oracle/exec-config/defaults
  • GET /api/v1/oracle/leaderboard description reworded: "Curated persona roster — wrappers for the deployed strategies on the public dashboard. See Deployed strategies for live execution state."
  • GET /api/v1/oracle/results annotated to clarify experiment_id is optional (cross-experiment view when omitted).
  • New row for GET /api/v1/oracle/deployed/strategies linking to the new page.
  • "Related" section updated to point to the new deployed page and to mention SDK v1.4.0 coverage.

docs/api-reference/oracle-deployed.mdx (NEW) — ~60-line page covering:

  • GET /oracle/deployed/strategies (list with live state)
  • GET /oracle/deployed/{id}/state (per-strategy execution snapshot)
  • GET /oracle/deployed/{id}/events (recent trade history)
  • GET /oracle/deployed/stream (SSE)
  • Curl + SDK example per route.
  • A "why leaderboard returns personas, not strategies" section so customers don't fall into the same trap.

docs/mint.json — insert \"api-reference/oracle-deployed\" after experiments (Oracle endpoints group together).

Test plan

  • python -m json.tool docs/mint.json → valid JSON
  • `npx mintlify dev` → render check
  • Post-merge: cut v1.0.6 tag via release workflow

Sibling PRs closing the rest of #576

🤖 Generated with Claude Code

Closes the doc-drift half of gh #576 (issues #1, #2, #4):

experiments.mdx endpoints table fixes:
- /api/v1/oracle/simulate          -> /api/v1/oracle/simulate/run
  (plus new rows for /simulate/generate, /simulate/presets, /simulate/history)
- /api/v1/oracle/exec-config       -> /api/v1/oracle/exec-config/defaults
  (the bare path was always a server SPA fallback, not a JSON endpoint)
- /api/v1/oracle/leaderboard        -> reworded to "curated persona
  roster" with a pointer to the new deployed page; the previous
  description ("best-performing strategies across recent experiments")
  was incorrect after Oracle's persona restructure.
- /api/v1/oracle/results            -> annotated that experiment_id is
  optional, and the unfiltered path returns the cross-experiment view.
- New row for /api/v1/oracle/deployed/strategies linking to the new
  oracle-deployed page.

New oracle-deployed.mdx documents the live execution-state surface
(strategies, state, events, SSE stream) that replaces the old
leaderboard-as-ranking shape. Includes curl + SDK examples for each
endpoint and a "why leaderboard returns personas" section so
customers don't fall into the same trap.

mint.json: insert "api-reference/oracle-deployed" after experiments
(Oracle endpoints group together).

Sibling PRs closing the rest of #576:
- MangroveOracle PR #237 (BQ ORDER BY fix — issue #3)
- MangroveAI PR #580 (proxy allowlist for /oracle/deployed/*)
- MangroveAI-SDK PR (incoming — 9 new typed methods + live example)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mangrove-one

Copy link
Copy Markdown
Member Author

Ship instructions — step 5 of 6

Status: CI green (test 3.10/3.11/3.12 + CodeQL all pass), MERGEABLE, blocked only on review approval.

Safe to merge any time independently — the SDK v1.4.0 references in the doc will become accurate once SDK PR #14 ships, but a customer reading the doc today against SDK v1.3.0 won't be misled because the new method calls are wrapped in code blocks that reference the upcoming version explicitly.

After clicking merge:

# KB uses the workflow per memory feedback_kb_release_must_use_workflow — never manual tag.
gh workflow run release.yml --repo MangroveTechnologies/MangroveKnowledgeBase --ref main -f version=v1.0.6

The release workflow:

  1. Publishes mangrove-kb to PyPI.
  2. Builds the Mintlify docs container.
  3. Deploys to mangrove-docs-prod (= docs.mangrovedeveloper.ai).

Verify the new page is live:

curl -sS https://docs.mangrovedeveloper.ai/api-reference/oracle-deployed | head -3
# Expect MDX content, not 404.

Next: mangrove-agent #82 (pin bump after SDK v1.4.0 hits PyPI).

@mangrove-one mangrove-one self-assigned this May 31, 2026
@mangrove-one mangrove-one merged commit 3c997ce into main May 31, 2026
5 checks passed
@mangrove-one mangrove-one deleted the docs/oracle-corrections branch June 5, 2026 01:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant