Add agent integration guide (md.mdx)

[Aadil-5122]

Adds the comprehensive HydraDB agent integration guide at /md. This is a single, self-contained MDX file (~57 KB, 1,800 lines) designed for AI coding agents to autonomously install, configure, and integrate HydraDB into any project.

Covers all 7 HydraDB products: Python SDK, TypeScript SDK, CLI, MCP server, Claude Code plugin, OpenClaw plugin, and REST API. Includes 15 sections spanning installation, core concepts, integration playbooks, ingestion/querying workflows, agent decision logic, error handling, and end-to-end examples. All code snippets verified against actual SDK source code.

Changes addressing Greptile review

P1: Infrastructure polling (Python + TypeScript E2E examples)

• Replaced time.sleep(5) / setTimeout(5000) with proper polling loops using client.tenant.get_infra_status() / client.tenant.getInfraStatus()
• Greptile's suggested fix compared graph_status == "ready" but the actual SDK types are bool (graph_status) and List[Any] / unknown[] (vectorstore_status), not strings
• Polling checks: graph_status is True, vectorstore_status has length > 0 and all elements are truthy, with a 5-minute timeout

P1: TypeScript SDK field names (all code examples)

• Fixed all TypeScript code examples throughout the entire guide to use snake_case field names matching the actual SDK types (tenant_id, file_metadata, success_count, user_name, relevancy_score, source_title, chunk_content, graph_context, max_results, recency_bias, etc.)
• Updated the SDK method reference table (Section 14) to show correct snake_case parameter names
• Corrected the naming convention note: both SDKs use snake_case for fields; only method names differ (snake_case in Python, camelCase in TypeScript)

P2: File naming (md.mdx)

• No change -- the /md path is an intentional product requirement for a short, agent-referenceable URL

P2: MCP environment variable naming

• Added a <Warning> callout after the MCP env var table documenting naming differences across all tools:
  • MCP server / Python SDK: HYDRA_DB_API_KEY, HYDRA_DB_TENANT_ID
  • TypeScript SDK README: HYDRA_DB_API_KEY but HYDRA_TENANT_ID (inconsistent within the SDK)
  • OpenClaw plugin: HYDRA_OPENCLAW_API_KEY, HYDRA_OPENCLAW_TENANT_ID
  • CLI: HYDRADB_API_KEY

[greptile-apps]

Greptile Summary

Adds a comprehensive 1,803-line HydraDB agent integration guide (md.mdx) covering all 7 products with installation, E2E examples, CLI reference, REST API, and SDK method tables. All previously flagged P1 issues have been resolved: infrastructure waits now use proper polling loops (not fixed sleeps), TypeScript examples consistently use snake_case field names, processing timeouts now raise TimeoutError via for/else, and env-var naming differences are documented with a <Warning> callout.

• One P1 remains: when a file reaches errored indexing status (a documented terminal state), the processing verification loops in both E2E examples — Python (lines 1526–1536) and TypeScript (lines 1632–1641) — continue polling for the full 5-minute window before raising a misleading TimeoutError. A fast-fail guard for errored status is missing.

Confidence Score: 4/5

Safe to merge after addressing the errored-status fast-fail gap in both E2E processing loops; all prior P1s are resolved

The three previously flagged P1s (fixed sleep for infra wait, TypeScript camelCase fields, silent processing timeout) are all correctly addressed. One new P1 remains: a documented terminal errored status in the processing verification loop is not caught, causing a 5-minute busy-wait and a misleading TimeoutError in both the Python and TypeScript E2E examples. No security or data-integrity issues found elsewhere in the guide.

md.mdx — processing verification loop in Section 13 (Python ~line 1526, TypeScript ~line 1632)

Important Files Changed

Filename	Overview
md.mdx	1,803-line agent integration guide covering all 7 HydraDB products; prior P1 issues (infra polling, TS snake_case fields, processing timeout) are resolved; one remaining P1 where an errored indexing status in the E2E processing wait loops causes a 5-minute busy-wait and a misleading TimeoutError instead of a fast-fail

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Install SDK] --> B[Initialize Client]
    B --> C[Create Tenant]
    C --> D{Poll getInfraStatus}
    D -- "graph_status=true\nvectorstore ready" --> E[Ingest Documents / Memories]
    D -- "not ready, i<60" --> D
    D -- "i=60 timeout" --> ERR1[TimeoutError: infra not ready]
    E --> F{Poll verifyProcessing}
    F -- "all completed/success" --> G[Recall Context]
    F -- "errored not detected" --> F
    F -- "timeout i=30" --> ERR2[TimeoutError: misleading message]
    G --> H[Inject into LLM prompt]
    H --> I[Return response to user]

    style ERR2 fill:#ffcccc,stroke:#cc0000

Loading

_{Reviews (3): Last reviewed commit: "Add timeout guards to processing verific..." | Re-trigger Greptile}

[Aadil-5122]

@greptile

[Aadil-5122]

@greptile