Skip to content
PoktaCareDocs

Integrations and safe changes

Main integrations

Section titled “Main integrations”
Integration Use Expected failure behavior
Supabase Users, conversations, messages, state, and search Persistent chat can fail or degrade
S3-compatible storage Conversation files Text may parse while persistent upload is skipped
LLM providers Planning, tools, response, and evaluation resilientChatCompletion can fall back outside pinned study requests
PubMed Biomedical evidence and verified PMIDs Output should declare that no PMID was verified
Semantic Scholar / OpenScholar Additional literature Tool failure is logged and the pipeline may continue
Local knowledge / graph Specialized retrieval Another retrieval method or direct response may be used
BiobadamexAI study harness Calls stateless route with de-identified note 401 without valid bearer; 503 when key is unset
x402 Optional external API payment 402 or 429 depending on payment and limits

Behavior-defining variables

Section titled “Behavior-defining variables”

This list names configuration, never values:

  • Server: PORT, HOST, CORS_ORIGINS.
  • Study: RHEUMAI_STUDY_API_KEY, CORS_STUDY_ORIGINS, RHEUMAI_STUDY_TOOL_ALLOWLIST, RHEUMAI_STUDY_MAX_PAID_CALLS.
  • Models: REPLY_LLM_PROVIDER, REPLY_LLM_MODEL, HYP_LLM_PROVIDER, HYP_LLM_MODEL, STRUCTURED_LLM_MODEL.
  • ORVS: ORVS_ENABLED, ORVS_VERSION.
  • Storage and database: provider-specific variables; never copy values into docs.
  • x402: X402_ENABLED, environment, payment address, and facilitator credentials.

Invariants

Section titled “Invariants”
  1. The study route stays stateless and closed when its key is missing.
  2. Note bodies never enter logs or error responses.
  3. A study pin forces one provider/model and disables cross-model fallback.
  4. Cost-bearing tools are excluded by default and the default paid ceiling is zero.
  5. Published PMIDs come from the current turn’s retrieved set.
  6. Normal clinical chat resolves to REPLY unless an explicit protocol or research flow applies.
  7. A RheumAI failure never authorizes registry submission.
  8. Only a clinician authorizes final clinical data.

Change and test map

Section titled “Change and test map”
Change Review Minimum checks
Route mounting or CORS src/index.ts and Elysia plugins bun run build, non-mutating API smoke
Chat order or fallbacks src/routes/chat.ts, src/services/chat/* tool tests and synthetic smoke
Study route src/study/* bun test src/study/rheumaai-reply-route.test.ts src/study/tool-cap.test.ts
Providers/models src/llm/* bun test src/llm/resilient.test.ts and pin tests
ORVS or citations src/tools/verification/* and PMID gate unit tests, allowed and fabricated PMID cases
Files or labs src/tools/file-upload/*, src/tools/lab-interpretation/* lab tests with synthetic fixtures
Dynamic tools src/tools/index.ts start registry and inspect loaded/failed tools
Client client/src/* bun run check, bun run build
Section titled “Recommended local verification”
Ventana de terminal
bun install --frozen-lockfile
bun run check
bun run build
bun test src/study/rheumaai-reply-route.test.ts \
  src/study/tool-cap.test.ts \
  src/tools/lab-interpretation/lab-interpretation.test.ts \
  src/tools/knowledgeGraph/knowledgeGraph.test.ts

At the documented commit, the focused set above passed 26 tests with 0 failures after a frozen install. Tool registration also emitted warnings for unconfigured tools and a folder without index.ts; focused tests are not a complete server-health check.

Smoke tests that call external services require valid configuration. Routine changes must not run them against production or with real notes.

Code states

Section titled “Code states”
  • Active: imported by src/index.ts, chat, or a loaded tool and supported by observed tests.
  • Configurable: active only when a variable or provider is present.
  • Experimental: comparison modes, benchmarks, and non-default scripts.
  • Placeholder or broken: registered folder without an index.ts, failed import, or integration requiring missing credentials.
  • Legacy: retained for compatibility but not preferred.

Do not document a folder as working just because it exists. Confirm import, configuration, and tests.

Automated coverage does not include the main chat, deep research, authentication, community, Telegram, or x402 routes, and there are no client tests. Changes in those areas need synthetic smoke checks in addition to the existing tests.

Code evidence

Section titled “Code evidence”