{"id":31702282,"url":"https://github.com/tmhsdigital/deepseek-wrapper","last_synced_at":"2025-10-08T21:36:05.456Z","repository":{"id":293721994,"uuid":"961562743","full_name":"TMHSDigital/DeepSeek-Wrapper","owner":"TMHSDigital","description":"Async/sync Python client for DeepSeek LLM API. Supports completions, chat, streaming, function calling (tools), retries, and robust error handling. Easy API key management, pluggable logging, type hints, and Pydantic models. Built for scripts, web backends, CI/CD, and production.","archived":false,"fork":false,"pushed_at":"2025-08-23T02:06:42.000Z","size":345,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-23T02:50:30.622Z","etag":null,"topics":["css","deepseek","deepseek-wrapper","fastapi","function-calling","html","python","tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TMHSDigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-06T19:09:18.000Z","updated_at":"2025-08-23T02:06:46.000Z","dependencies_parsed_at":"2025-05-16T20:34:25.459Z","dependency_job_id":null,"html_url":"https://github.com/TMHSDigital/DeepSeek-Wrapper","commit_stats":null,"previous_names":["tmhsdigital/deepseek-wrapper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TMHSDigital/DeepSeek-Wrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TMHSDigital%2FDeepSeek-Wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TMHSDigital%2FDeepSeek-Wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TMHSDigital%2FDeepSeek-Wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TMHSDigital%2FDeepSeek-Wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TMHSDigital","download_url":"https://codeload.github.com/TMHSDigital/DeepSeek-Wrapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TMHSDigital%2FDeepSeek-Wrapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000709,"owners_count":26082838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","deepseek","deepseek-wrapper","fastapi","function-calling","html","python","tools"],"created_at":"2025-10-08T21:35:55.993Z","updated_at":"2025-10-08T21:36:05.450Z","avatar_url":"https://github.com/TMHSDigital.png","language":"Python","readme":"# DeepSeek Wrapper\n\n---\n\n[![CI](https://github.com/TMHSDigital/DeepSeek-Wrapper/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TMHSDigital/DeepSeek-Wrapper/actions)\n[![codecov](https://codecov.io/gh/TMHSDigital/DeepSeek-Wrapper/branch/main/graph/badge.svg)](https://codecov.io/gh/TMHSDigital/DeepSeek-Wrapper)\n[![License](https://img.shields.io/github/license/TMHSDigital/DeepSeek-Wrapper)](docs/LICENSE)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/TMHSDigital/DeepSeek-Wrapper/main.svg)](https://results.pre-commit.ci/latest/github/TMHSDigital/DeepSeek-Wrapper/main)\n[![Latest Release](https://img.shields.io/github/v/release/TMHSDigital/DeepSeek-Wrapper?logo=github)](https://github.com/TMHSDigital/DeepSeek-Wrapper/releases)\n\n[![Issues](https://img.shields.io/github/issues/TMHSDigital/DeepSeek-Wrapper)](https://github.com/TMHSDigital/DeepSeek-Wrapper/issues)\n[![Pull Requests](https://img.shields.io/github/issues-pr/TMHSDigital/DeepSeek-Wrapper)](https://github.com/TMHSDigital/DeepSeek-Wrapper/pulls)\n[![GitHub stars](https://img.shields.io/github/stars/TMHSDigital/DeepSeek-Wrapper)](https://github.com/TMHSDigital/DeepSeek-Wrapper/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/TMHSDigital/DeepSeek-Wrapper)](https://github.com/TMHSDigital/DeepSeek-Wrapper/network)\n[![Last Commit](https://img.shields.io/github/last-commit/TMHSDigital/DeepSeek-Wrapper)](https://github.com/TMHSDigital/DeepSeek-Wrapper/commits/main)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com/)\n\n---\n\n\u003e A modern, async/sync Python client for the DeepSeek LLM API. Supports completions, chat, retries, and robust error handling. Built for local dev, CI, and production.\n\n![DeepSeek Wrapper UI](docs/images/ui-overview.png)\n\n## Documentation\n\n| Doc | Description |\n| --- | --- |\n| [Getting Started](docs/getting-started.md) | Quick setup guide |\n| [Web UI Guide](docs/web-ui-guide.md) | Guide to using the web interface |\n| [Features](docs/features.md) | Detailed feature list |\n| [API Reference](docs/api-reference.md) | API documentation for developers |\n| [Deployment Guide](docs/deployment.md) | Deployment options and configurations |\n| [FAQ](docs/faq.md) | Frequently asked questions |\n\nFor DeepSeek AI model capabilities, see [DeepSeek documentation](docs/deepseek-docs.md).\n\n## Version Progress\n\nBelow are screenshots showing the evolution of the DeepSeek Wrapper web UI and features over time:\n\n**Pre-release**\n\n![Pre-release UI](versions/pre-release.png)\n\n_Initial UI and feature set before public release._\n\n\u003c!-- Add more screenshots here as you add new versions, e.g.:\n\u003cp align=\"center\"\u003e\n  \u003cstrong style=\"font-size:1.2em;\"\u003ev0.2.0\u003c/strong\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"versions/v0.2.0.png\" alt=\"v0.2.0 UI\" style=\"max-width: 600px; border-radius: 8px; box-shadow: 0 2px 8px #0002;\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\" style=\"font-size: 0.95em; color: #666;\"\u003e\n  \u003cem\u003eAdded async endpoints and improved chat history.\u003c/em\u003e\n\u003c/p\u003e\n--\u003e\n\n**Tool Status \u0026 Caching Panel**\n\n![Tool status and caching panel](docs/images/tool-status-panel.png)\n\n_See per-tool status, cache stats, and manage tool caches directly from the UI._\n\n## Features\n\n### Features\n\n#### Modern API\n- Sync \u0026 async support\n- Type hints throughout\n- Clean error handling\n\n#### Advanced Web UI\n- Session-based chat history\n- Markdown rendering\n- File uploads \u0026 processing\n\n#### Real-Time Awareness\n- Current date \u0026 time info\n- Multiple formats (ISO, US, EU)\n- No external API required\n\n#### Production Ready\n- Automatic retries with backoff\n- 94%+ test coverage\n- Environment variable config\n\n#### Function Calling\n- Tool integration framework\n- Built-in tools (Weather, Calculator)\n- Custom tool creation system\n- Tool status dashboard: visualize tool health, API key status, and cache performance in real time\n\n#### API Key Management\n- Integrated settings panel\n- Secure API key storage in .env\n- Tool configuration UI\n\n## Web UI (FastAPI)\n\nA modern, session-based chat interface for DeepSeek, built with FastAPI and Jinja2.\n\n**To run locally:**\n```bash\nuvicorn src.deepseek_wrapper.web:app --reload\n```\nThen open [http://localhost:8000](http://localhost:8000) in your browser.\n\n**Web UI Features:**\n- Chat with DeepSeek LLM (session-based history)\n- Async backend for fast, non-blocking responses\n- Reset conversation button\n- Timestamps, avatars, and chat bubbles\n- **Markdown rendering in assistant responses**\n- Loading indicator while waiting for LLM\n- **Non‑flashing \"Thinking…\" indicator with progress bar and optional expandable live details (accessibility-friendly)**\n- Error banner for API issues\n- **Tool configuration in settings panel with API key management**\n\nFor a comprehensive guide to using the web interface, see the [Web UI Guide](docs/web-ui-guide.md).\n\n## Installation\n\n```bash\npip install -r requirements.txt\npip install -e .  # for local development\n```\n\n### Quickstart (Web UI)\n\n```powershell\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npip install -r requirements.txt\n\"DEEPSEEK_API_KEY=sk-your-key\" | Out-File -FilePath .env -Encoding ascii\nuvicorn src.deepseek_wrapper.web:app --reload\n```\n\nFor detailed installation instructions, see the [Getting Started Guide](docs/getting-started.md).\n\n## Usage (Python)\n\n```python\nfrom deepseek_wrapper import DeepSeekClient\nclient = DeepSeekClient()\nresult = client.generate_text(\"Hello world!\", max_tokens=32)\nprint(result)\n\n# Async usage\nimport asyncio\nasync def main():\n    result = await client.async_generate_text(\"Hello async world!\", max_tokens=32)\n    print(result)\n# asyncio.run(main())\n```\n\n### Real-Time Date Awareness\n\n```python\nfrom deepseek_wrapper import DeepSeekClient\nfrom deepseek_wrapper.utils import get_realtime_info\n\n# Get real-time date information as JSON\nrealtime_data = get_realtime_info()\nprint(realtime_data)  # Prints current date in multiple formats\n\n# Create a client with real-time awareness\nclient = DeepSeekClient()\n\n# Use in a system prompt\nsystem_prompt = f\"\"\"You are a helpful assistant with real-time awareness.\nCurrent date and time information:\n{realtime_data}\n\"\"\"\n\n# Send a message with the real-time-aware system prompt\nmessages = [\n    {\"role\": \"system\", \"content\": system_prompt},\n    {\"role\": \"user\", \"content\": \"What's today's date?\"}\n]\n\nresponse = client.chat_completion(messages)\nprint(response)  # Will include the current date\n```\n\n### Function Calling with Tools\n\n```python\nfrom deepseek_wrapper import DeepSeekClient, DateTimeTool, WeatherTool, CalculatorTool\n\n# Create a client and register tools\nclient = DeepSeekClient()\nclient.register_tool(DateTimeTool())\nclient.register_tool(WeatherTool())\nclient.register_tool(CalculatorTool())\n\n# Create a conversation\nmessages = [\n    {\"role\": \"user\", \"content\": \"What's the weather in London today? Also, what's the square root of 144?\"}\n]\n\n# Get a response with tool usage\nresponse, tool_usage = client.chat_completion_with_tools(messages)\n\n# Print the final response\nprint(response)\n\n# See which tools were used\nfor tool in tool_usage:\n    print(f\"Used {tool['tool']} with args: {tool['arguments']}\")\n```\n\nFor a complete API reference and advanced usage, see the [API Reference](docs/api-reference.md).\n\n## Configuration\n- Set `DEEPSEEK_API_KEY` in your `.env` or environment\n- Optionally set `DEEPSEEK_BASE_URL`, `timeout`, `max_retries`\n- See `.env.example`\n\n**Default model:** `deepseek-chat` (per DeepSeek docs)\n\nFor deployment options and environment configurations, see the [Deployment Guide](docs/deployment.md).\n\n## API Reference\nAll methods accept extra keyword args for model parameters (e.g., `temperature`, `top_p`, etc).\n\n## Testing\n\n```bash\npytest --cov=src/deepseek_wrapper\n```\n\n## Contributing\n\n- Run `pre-commit install` to enable hooks\n\n## Links\n- [DeepSeek API Docs](https://platform.deepseek.com/docs)\n- [OpenAI API Reference](https://platform.openai.com/docs/api-reference)\n- [GitHub Repo](https://github.com/TMHSDigital/DeepSeek-Wrapper)\n\n## License\n\nLicensed under the Apache-2.0 license. See [docs/LICENSE](docs/LICENSE).\n\n## Model Selection (Coming Soon)\n\n\u003e **Note:** The model selection feature is currently under development and **IS NOT functional yet**. \n\nThe DeepSeek Wrapper will soon support switching between different DeepSeek models:\n- deepseek-chat\n- deepseek-coder\n- deepseek-llm-67b-chat\n- deepseek-llm-7b-chat\n- deepseek-reasoner\n\nWhen complete, users will be able to:\n1. Select different models through the settings panel\n2. See the currently active model in the UI\n3. Configure model-specific settings, such as extracting only final answers from reasoning models\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmhsdigital%2Fdeepseek-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmhsdigital%2Fdeepseek-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmhsdigital%2Fdeepseek-wrapper/lists"}