Skip to content

Explanation

Background reading for the project. These pages explain why the code is shaped the way it is — useful when you're maintaining the project, doing a security review, or onboarding a new contributor.

For task-oriented recipes, see the how-to guides. For the auto-generated API surface, see the reference.

What's here

  • Architecture — the layer stack, the import-direction rule, and how a tool call flows from the LLM to Saldeo and back.
  • Request signing — the MD5 algorithm Saldeo requires, with a sequence diagram.
  • Concurrency — why every request goes through a single threading.Lock (Saldeo forbids concurrent requests per user).
  • Security & privacy — SecretStr tokens, URL redaction in logs, the read-only smoke-test policy, and the attack-surface assumptions.
  • Design decisions — a running log of the non-obvious choices: why FastMCP, why MD5 (Saldeo's spec, not our pick), why one Pydantic model per direction, why the _runtime/_builders helper split, and what we explicitly chose not to do.