initial commit

2026-05-14 18:38:09 +03:00
commit f41d64f39b
32 changed files with 1469 additions and 0 deletions
@@ -0,0 +1,224 @@
+# Python DeepSeek R1 API
+
+A Python port of the DeepSeek R1 API wrapper (OpenAI-compatible).
+
+## Architecture
+
+```
+python/
+├── api/                  # DeepSeek API client
+│   ├── client.py        # Main HTTP client
+│   ├── models.py        # Data models and response types
+│   └── utils.py         # Utilities
+├── dto/                 # Data transfer objects
+│   ├── models.py        # Request/response models
+│   └── utils.py         # Utilities
+├── kv/                  # Cache/KV storage
+│   └── cache.py         # Redis cache implementation
+├── solver/              # WASM proof-of-work solver
+│   └── instance.py      # Solver wrapper
+├── application/         # Flask application
+│   └── app.py           # Main Flask app with routes
+├── main.py              # Entry point
+└── requirements.txt     # Python dependencies
+```
+
+## Requirements
+
+- Python 3.8+
+- Redis server (for chat session caching)
+- WASM binary from Go implementation (`sha3_wasm_bg.7b9ca65ddd.wasm`)
+
+## Installation
+
+### Using pip
+
+```bash
+pip install -r requirements.txt
+```
+
+### Using Docker
+
+```bash
+docker-compose up
+```
+
+## Configuration
+
+Create a `.env` file from the template:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your settings:
+
+```
+REDIS_ADDR=localhost:6379
+```
+
+## Running
+
+### Local Python
+
+```bash
+python main.py
+```
+
+### Docker
+
+```bash
+docker-compose up
+```
+
+The server will start on `http://localhost:8080`
+
+## API Endpoints
+
+- `GET /` - Health check (returns "started")
+- `GET /models` - List available models (returns r1 model)
+- `POST /chat/completions` - OpenAI-compatible chat completions
+
+## API Usage
+
+### Non-streaming Request
+
+```bash
+curl -X POST http://localhost:8080/chat/completions \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "r1",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ],
+    "stream": false
+  }'
+```
+
+### Streaming Request
+
+```bash
+curl -X POST http://localhost:8080/chat/completions \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "r1",
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ],
+    "stream": true
+  }'
+```
+
+### Python Example
+
+```python
+import requests
+
+headers = {
+    "Authorization": "Bearer YOUR_API_KEY",
+    "Content-Type": "application/json"
+}
+
+data = {
+    "model": "r1",
+    "messages": [
+        {"role": "user", "content": "What is Python?"}
+    ],
+    "stream": False
+}
+
+response = requests.post(
+    "http://localhost:8080/chat/completions",
+    json=data,
+    headers=headers
+)
+
+print(response.json())
+```
+
+## Key Components
+
+### API Client (`api/client.py`)
+
+The main HTTP client that communicates with DeepSeek's API servers. Features:
+- Chat creation and management
+- Message completion with streaming
+- Proof-of-Work (PoW) challenge handling
+- Authentication and authorization
+- Server-Sent Events (SSE) parsing for streaming responses
+
+### Cache (`kv/cache.py`)
+
+Redis-based caching system for:
+- Chat session persistence
+- Message ID tracking
+- FNV-1a hash-based key generation
+
+### WASM Solver (`solver/instance.py`)
+
+Wraps the WASM SHA3 proof-of-work solver:
+- Memory management via Wasmtime
+- Hash calculation for PoW challenges
+- Compatibility with Go WASM binary
+
+### Flask Application (`application/app.py`)
+
+Web framework providing:
+- REST API endpoints
+- Request/response handling
+- Streaming support
+- Error handling and logging
+
+## Design Differences from Go
+
+1. **HTTP Client**: Uses `requests` library instead of Go's `net/http`
+2. **Concurrency**: Python's threading vs Go's goroutines
+3. **JSON Serialization**: `json` module instead of `sonic` (Go's fast JSON library)
+4. **Logging**: Python's `logging` instead of `zap`
+5. **Server**: Flask instead of Echo web framework
+6. **WASM Runtime**: `wasmtime-py` instead of `wasmtime-go`
+
+## Troubleshooting
+
+### WASM Binary Not Found
+
+Make sure the WASM binary file exists at:
+```
+deepseek4free/pkg/solver/sha3_wasm_bg.7b9ca65ddd.wasm
+```
+
+### Redis Connection Error
+
+Ensure Redis is running:
+```bash
+redis-server
+# or with Docker
+docker run -d -p 6379:6379 redis:7-alpine
+```
+
+### Import Errors
+
+Make sure you're running from the python directory and have set PYTHONPATH:
+```bash
+export PYTHONPATH=/path/to/python:$PYTHONPATH
+python main.py
+```
+
+## Performance Notes
+
+- Python is generally slower than Go for this workload
+- For production use, consider using Gunicorn:
+  ```bash
+  pip install gunicorn
+  gunicorn -w 4 -b 0.0.0.0:8080 "application.app:Application(solver, cache).app"
+  ```
+
+- WASM solver performance is comparable between Go and Python
+- Network I/O is the primary bottleneck
+
+## License
+
+Same as the original Go implementation
+