Skip to main content

AllRatesToday × DeepSeek — allratestoday-deepseek

Give DeepSeek chat and agents real-time access to currency exchange rates and historical data, via function calling. Ships ready-to-use OpenAI-format tool schemas, a thin agent wrapper, and a CLI — for anyone building a DeepSeek app that must not hallucinate a rate.

Powered by AllRatesToday PyPI CI Python License API Status

English | 简体中文

DeepSeek's Chat Completions API is OpenAI-compatible, so the standard tools= mechanism works unchanged. This package wires four currency tools into that mechanism so DeepSeek can answer questions like:

  • "What's USD to EUR right now?"
  • "Convert 1000 GBP to JPY."
  • "How has USD/INR moved over the last 30 days?"
  • "List every supported currency."

Rates come from the AllRatesToday API — 160+ currencies, mid-market rates with no retail spread.

🚀 Features

  • 🧰 Four tool schemas — get_exchange_rate, convert_currency, get_historical_rates, list_currencies, in OpenAI/DeepSeek function-calling format (TOOLS)
  • 🤖 Agent wrapper — DeepSeekCurrencyAgent runs the full tool-call loop for you (up to max_tool_rounds, default 6)
  • 💻 CLI — allratestoday-deepseek for an interactive REPL or a one-shot --ask
  • 🔧 Bring your own loop — import TOOLS and dispatch_tool and drive the OpenAI SDK yourself
  • 🌍 160+ currencies — mid-market rates plus 1d / 7d / 30d / 1y history
  • 🪶 Two dependencies — openai and httpx, nothing else
  • 🚫 No hallucinated rates — the system prompt instructs the model to call a tool rather than guess

🔑 Get your API key

Two keys are involved:

Variable Required? Purpose
DEEPSEEK_API_KEY Yes Your DeepSeek key, from platform.deepseek.com/api_keys. Without it DeepSeekCurrencyAgent() raises RuntimeError.
ALLRATES_API_KEY Yes for rate lookups Your AllRatesToday key. Get a free one at allratestoday.com/register.
ALLRATES_BASE_URL No Override the API base URL (default https://allratestoday.com/api).

Only list_currencies (GET /api/v1/symbols) answers without an AllRatesToday key. Rate, conversion and historical lookups all return 401 unauthenticated, so set ALLRATES_API_KEY for any real use. Historical lookups (get_historical_rates, and get_rates with time) need a paid plan; free and trial keys get 403 historical_requires_paid_plan.

📦 Installation

pip install allratestoday-deepseek

Python 3.9+. From a checkout, pip install -e ".[dev]" also installs pytest and ruff.

🏁 Quick start

One-shot question:

export DEEPSEEK_API_KEY=sk-...
export ALLRATES_API_KEY=art_live_...
allratestoday-deepseek --ask "What is 2500 USD in EUR right now?"

Interactive chat (type :q, exit, quit or a blank line to leave):

allratestoday-deepseek
allratestoday-deepseek --model deepseek-reasoner

As a library:

from allratestoday_deepseek import DeepSeekCurrencyAgent

with DeepSeekCurrencyAgent() as agent:
    print(agent.ask("How many Japanese Yen is 500 Swiss Francs?"))

Multi-turn, keeping your own history:

from allratestoday_deepseek import DeepSeekCurrencyAgent

history = []
with DeepSeekCurrencyAgent(model="deepseek-chat") as agent:
    answer = agent.ask("What is USD to EUR?", history=history)
    history += [
        {"role": "user", "content": "What is USD to EUR?"},
        {"role": "assistant", "content": answer},
    ]
    print(agent.ask("And to GBP?", history=history))

Runnable examples live in examples/:

python examples/ask_once.py "What's USD to EUR right now?"   # one question, then exit
python examples/chat.py                                      # interactive REPL
python examples/raw_tool_call.py                             # drive the tool loop yourself

📚 API reference

Tools exposed to the model

Tool AllRatesToday key Parameters Description
get_exchange_rate Yes source, target Current mid-market rate for a pair.
convert_currency Yes source, target, amount Fetches the pair rate and multiplies — not a separate endpoint.
get_historical_rates Yes (paid plan) source, target, period (1d/7d/30d/1y, default 7d) Time series: 1d hourly, 7d/30d daily, 1y weekly.
list_currencies No — Every supported currency with code, name and symbol.

DeepSeekCurrencyAgent

DeepSeekCurrencyAgent(
    deepseek_api_key=None,       # falls back to $DEEPSEEK_API_KEY
    allrates_api_key=None,       # falls back to $ALLRATES_API_KEY
    model="deepseek-chat",
    base_url="https://api.deepseek.com",
    system_prompt=SYSTEM_PROMPT,
    max_tool_rounds=6,
)
Member Description
ask(question, history=None) Runs the tool-call loop and returns the final answer string.
close() Closes the underlying HTTP client. Also available via with.
run_chat(agent, stream_in) Module-level REPL helper over an iterable of user lines.

AllRatesTodayClient

Thin httpx wrapper over the REST API, usable on its own.

Method Endpoint Auth
get_rate(source, target) GET /rate Key required by the API
list_symbols() GET /v1/symbols None
get_historical_rates(source, target, period="7d") GET /historical-rates Bearer key, paid plan
get_rates(source, target, time=None, group=None) GET /v1/rates — comma-separated targets, group of hour/day/week/month Bearer key (time needs a paid plan)
convert(source, target, amount) Convenience — get_rate × amount, rounded to 4 dp Key required by the API

Tool plumbing

from allratestoday_deepseek import TOOLS, dispatch_tool, AllRatesTodayClient

client = AllRatesTodayClient()                       # reads $ALLRATES_API_KEY
result = dispatch_tool(client, "get_exchange_rate", '{"source":"USD","target":"EUR"}')

TOOLS is the list you pass as tools= to chat.completions.create. dispatch_tool accepts DeepSeek's raw JSON-string arguments or an already-parsed dict, and always returns a JSON string suitable for a role: "tool" message.

🗺️ Currencies covered

160+ currencies as returned by list_currencies, including 🇺🇸 USD · 🇪🇺 EUR · 🇬🇧 GBP · 🇯🇵 JPY · 🇨🇭 CHF · 🇨🇦 CAD · 🇦🇺 AUD · 🇳🇿 NZD · 🇮🇳 INR · 🇨🇳 CNY · 🇧🇷 BRL · 🇲🇽 MXN · 🇹🇷 TRY · 🇿🇦 ZAR · 🇸🇬 SGD · 🇭🇰 HKD · 🇰🇷 KRW · 🇦🇪 AED · 🇱🇰 LKR · 🇳🇬 NGN.

🛡️ Error handling

Tool failures are never raised into the model's face — dispatch_tool catches them and returns {"error": "..."} as the tool result, so DeepSeek can explain or retry.

from allratestoday_deepseek import AllRatesTodayClient, AllRatesTodayError

try:
    AllRatesTodayClient().get_historical_rates("USD", "EUR", "30d")
except AllRatesTodayError as err:
    print(err.status, err.body)
Raised When
RuntimeError No DeepSeek key found when constructing the agent.
RuntimeError The model kept calling tools past max_tool_rounds — raise the limit.
AllRatesTodayError Any non-2xx from the API; carries .status and .body.
AllRatesTodayError An authenticated endpoint was called with no AllRatesToday key.

Common API statuses: 401 missing or invalid key · 429 rate limit or plan quota exceeded (the free tier is 300 requests in total, not per month) · 5xx upstream error.

💡 Notes

How a question is answered

  1. You send DeepSeek a question through agent.ask().
  2. The agent calls chat.completions.create(..., tools=TOOLS, tool_choice="auto") — DeepSeek receives all four tool schemas.
  3. If it needs data, it emits a tool_call such as get_exchange_rate(source="USD", target="EUR").
  4. The agent runs that tool against the AllRatesToday API and appends the JSON result as a role: "tool" message.
  5. Steps 2–4 repeat until DeepSeek answers in natural language, citing the live rate — or max_tool_rounds is hit.

Compatibility — any DeepSeek model that supports function calling; deepseek-chat is the default and deepseek-reasoner is selectable with --model. CI exercises Python 3.9, 3.11 and 3.12 on Ubuntu.

Rate caching — every get_exchange_rate or convert_currency tool call is one API request, and each request counts toward your plan quota (the free tier is 300 lifetime requests that never reset). Cache aggressively if the same pair is asked for repeatedly.

📜 License

MIT — see LICENSE.

Metadata

Release files for allratestoday-deepseek 0.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for allratestoday-deepseek 0.2.4
File Size Uploaded Provenance Actions
allratestoday_deepseek-0.2.4.tar.gz 13.2 kB Without provenance Details for allratestoday_deepseek-0.2.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for allratestoday-deepseek 0.2.4
File Interpreter ABI Platform Actions
allratestoday_deepseek-0.2.4-py3-none-any.whl Python 3 none any Details for allratestoday_deepseek-0.2.4-py3-none-any.whl

Total release size: 26.3 kB

Release files / allratestoday_deepseek-0.2.4.tar.gz

Download URL allratestoday_deepseek-0.2.4.tar.gz
Size 13.2 kB
Tags Source
SHA-256 checksum
How to use checksums
fd6033ac71615450ea5fcd4468fcfdd9a09b9b1b459b1f11ec464fbba3d2027a
BLAKE2b-256 checksum
How to use checksums
884ed1f3c3be8aaf379ef35de7669ebf2ddf11b8aa9b99bc74fcdd4ef80ca3d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / allratestoday_deepseek-0.2.4-py3-none-any.whl

Download URL allratestoday_deepseek-0.2.4-py3-none-any.whl
Size 13.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
852d05fad77b89d51c60cfb35f1c3dd20245977d79c7ad6eb8ceee68526fd26c
BLAKE2b-256 checksum
How to use checksums
6ba565c24f67fc5d8914bb7d91b80f52fba214a789f0f0b013b9674429122c31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for allratestoday-deepseek 0.2.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page