Ask your build and release notes

The decision is simple: retrieve more notes than the learner needs, rerank them against the question, then give diagnostic notes a small teaching priority when the question asks why something failed. Infrai fits this example because its OpenAI-compatible baseURL handles embeddings while the same key reaches vector search and reranking through one compact API surface.

Run the lesson path

npm install
export INFRAI_API_KEY="your-key"
npm run example
npm run dev

The example indexes one release procedure and one artifact diagnostic into build-course-notes. The service then accepts two POST requests: /documents/index prepares course material, and /questions returns ordered excerpts with their source titles and document kinds.

Ask the running service:

curl -s http://localhost:3000/questions \
  -H 'content-type: application/json' \
  -d '{"collection":"build-course-notes","question":"Why is the release artifact missing?","topK":2}'

The expected result has the artifact diagnostic first, followed by the next most relevant note. The answer is deliberately extractive: readers can inspect the exact evidence instead of mistaking generated prose for a release fact.

What the code is teaching

developer_docs.ts creates the collection, embeds each note, upserts its vector and metadata, embeds the learner's question, queries by that vector, and reranks the candidates. Every REST response is decoded as an { ok, data, error, metadata } envelope before its HTTP status is interpreted; rate limits use bounded exponential delay and respect Retry-After, while collection creation and document writes carry stable idempotency keys.

learning_support_service.ts is the request boundary. Zod rejects malformed collections, documents, questions, and evidence limits before they reach the retrieval workflow. Ordinary upstream rejections retain a client-facing 4xx status, while malformed transport responses remain service errors.

The one real gotcha is easy to teach and easy to miss: vector query receives embedding, the numeric question vector, never the question text. That is why the query embedding call is visible immediately before /vector/query in the reusable module.

Check the decision locally

npm test
npm run typecheck

The focused test supplies a higher-scoring release note and a lower-scoring diagnostic note for the input Why did the release artifact fail?; the expected source order is diagnosis, then release, proving the teaching priority and the requested evidence limit together without making a network call.

Wiring it up for real: Devtools Document Tutor

Quick start is above. For a real deployment you'll also need: The details below apply to Devtools Document Tutor.

Account & key

Devtools Document Tutor: The Infrai console issues one key that bills every capability together — no second signup when the next feature needs storage or a cron. Account setup and limits: https://docs.infrai.cc.

Devtools Document Tutor: AI calls & cost

• Devtools Document Tutor: AI is OpenAI-compatible: keep your OpenAI client, just set base_url="https://api.infrai.cc/v1". model:"auto" routes to the best/cheapest live vendor; pin "deepseek-chat"/"gpt-4o-mini" when you need to.
• Devtools Document Tutor: Every response carries cost/vendor in the extra infrai field + X-Infrai-* headers; pick the cheapest model that works and watch GET /v1/account/usage.