🛰️ deepseek-chat-sdk
A thin, battle-tested Python wrapper around the DeepSeek /chat/completions API
with built-in conversation-tree persistence.
- Drop-in call style – mirrors
openai-python(messages=[…]) - Two storage back-ends
MongoDB (default) or ultra-light JSON file – same API, switch in one flag - Tree-structured memory – each reply is a node; fork, branch & query whole tree
- Token-budget guard – automatic context trimming (or raise)
- 100 % sync code – keep dependencies minimal, trivially pluggable into any code-base
pip install deepseek_chat # from PyPI (or pip install -e .)
export DEEPSEEK_API_KEY=sk-...
⭐ Quick Start
from deepseek_chat import create_session, continue_chat, get_tree
# --- root turn --------------------------------------------------------
answer, sess_id, root_id = create_session(
system_prompt="你好,我是助手。",
question="帮我推荐一部电影。",
api_key="sk-...", # or rely on $DEEPSEEK_API_KEY
)
print(answer)
# --- branch off the same parent --------------------------------------
continue_chat(session_id=sess_id, parent_node_id=root_id,
question="有没有同类型但评分更高的?")
# --- show the whole tree --------------------------------------------
print(get_tree(sess_id))
Switch to local file storage (no Mongo)
answer, sid, nid = create_session(
system_prompt="你好!",
question="今天杭州天气如何?",
api_key="sk-...",
store_backend="file", # ← key flag
json_path="./history.json", # optional; default ~/.deepseek_chat/history.json
)
Custom Mongo URI (user/pass, replica set …)
import os
os.environ["DEEPSEEK_API_KEY"] = "sk-..."
answer, sid, nid = create_session(
system_prompt="You are helpful.",
question="Tell me a joke.",
mongo_uri="mongodb://dbUser:dbPwd@mongo-1:27017,mongo-2:27017/?replicaSet=rs0",
)
🔧 Installation
# bare minimum
pip install deepseek_chat
# dev / tests / ruff
pip install "deepseek_chat"
pytest -q
| Dependency | Used for | Optional? |
|---|---|---|
requests |
REST calls | ❌ |
pymongo |
Mongo back-end | ✅ (not imported if you choose file) |
tiktoken |
token counting | ✅ (falls back to word count) |
🗺️ API Surface
Functional helpers (one-liners)
| function | returns | must pass |
|---|---|---|
create_session(system_prompt, question, …) |
(answer, session_id, node_id) |
system_prompt, question |
continue_chat(session_id, parent_node_id, question, …) |
(answer, new_node_id) |
session_id, parent_node_id, question |
get_tree(session_id, …) |
nested dict |
session_id |
All take the same optional kwargs:
api_key DeepSeek API key (fallback $DEEPSEEK_API_KEY)
base_url custom gateway (fallback $DEEPSEEK_BASE_URL)
model deepseek-chat / deepseek-coder / …
store_backend "mongo" | "file" (default "mongo")
mongo_uri mongodb connection string
json_path path for file store
Class-level control
Need multiple clients or stores side-by-side? Use the OOP facade:
from deepseek_chat import ChatService, DeepSeekClient, FileStore
svc = ChatService(
client=DeepSeekClient(api_key="sk-..."),
store=FileStore("/tmp/ds_history.json"),
)
ans, sid, nid = svc.create_session(
system_prompt="You are GPT-5",
question="What's new in 2025?",
)
⚙️ Configuration matrix
| config source | DeepSeek | Mongo | File |
|---|---|---|---|
| ENV var (default singleton) | DEEPSEEK_API_KEY DEEPSEEK_BASE_URL |
MONGO_URI MONGO_DB |
— |
| per-call kwargs | api_key= base_url= |
mongo_uri= |
json_path= |
| programmatic | build your own DeepSeekClient + ChatStore/FileStore and pass into ChatService |
📚 Advanced features
JSON Output & Function Calling
Simply forward the native OpenAI-style params:
client = DeepSeekClient(api_key="sk-...")
resp = client.chat(
messages=[...],
response_format={"type": "json_object"},
)
resp_tool = client.chat(
messages=[...],
tools=[{ "type": "function", "function": {...} }],
)
The higher-level helpers (create_session/continue_chat) accept any extra
kwargs and pass them straight to DeepSeekClient.chat().
Token-budget enforcement
ensure_token_budget() truncates eldest user/assistant pairs once total tokens
exceed the limit (default 32 k). Raise TokenLimitExceeded if only the
system prompt already exceeds the model context.
Set a custom limit:
export TOKEN_LIMIT=16000
🛠️ Project layout
deepseek_chat/
├── client.py # DeepSeek REST wrapper
├── service.py # high-level orchestration
├── store.py # Mongo persistence
├── filestore.py # JSON persistence
├── utils.py # token helpers
└── __init__.py # facade + functional helpers
Unit tests live under tests/, demo scripts under examples/.
🪄 Roadmap
- async variant (
httpx.AsyncClient,motor) - automatic summarisation for ultra-long histories
- plug-in hooks (on_new_message, on_error)
Contributions welcome – just open an issue or PR.
Metadata
Release files for deepseek-chat 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| deepseek_chat-0.1.1.tar.gz | 16.2 kB | Without provenance | Details for deepseek_chat-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| deepseek_chat-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for deepseek_chat-0.1.1-py3-none-any.whl |
Total release size: 33.1 kB
Release files / deepseek_chat-0.1.1.tar.gz
| Download URL | deepseek_chat-0.1.1.tar.gz |
|---|---|
| Size | 16.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
22f03ac7f6c66aa67b9a154aff26a1b40b3b319e678d2ea47576eea42b52c63b
|
|
BLAKE2b-256 checksum How to use checksums |
0f767b69d250ab0703cac908c1f679574a91f486d2cb389fe0568d167fd2ac0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.10
|
Release files / deepseek_chat-0.1.1-py3-none-any.whl
| Download URL | deepseek_chat-0.1.1-py3-none-any.whl |
|---|---|
| Size | 16.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d3d6a0a00cee4c0fdca008df68e7b5de09cf64b1dc165faee23ad06aebb27591
|
|
BLAKE2b-256 checksum How to use checksums |
c555abb704e160f010c66e178be0eaf32fa1c72afc08d0ff60589ee80eae2c69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.10
|
Security for deepseek-chat 0.1.1
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.