Add OpenAI-compatible API server for AI agent integration

[falcga]

Summary

Add full OpenAI API v1 compatibility to dskpp, enabling the service to be used as a drop-in replacement for OpenAI's API in AI agents and tools like Cline, LangChain, OpenAI Python SDK, and more.

Motivation

dskpp currently provides an async Python client for DeepSeek chat, but there was no way to use it as an API server that AI agents could connect to. By implementing the OpenAI API format, dskpp can now serve as a local proxy that translates standard OpenAI requests into DeepSeek's internal WebSocket protocol.

Changes

New Files

• openai_compat.py — OpenAI API compatibility layer
  • Pydantic models: ChatCompletionRequest, ChatMessage, ModelList, ModelObject
  • Message conversion: OpenAI messages array → DeepSeek prompt string
  • Model mapping: deepseek-chat (standard), deepseek-reasoner (thinking enabled)
  • Helpers: generate_id(), estimate_tokens(), make_error_response()

Modified Files

• server.py — Major expansion from bypass server to full API server

  • New endpoints: GET /v1/models, POST /v1/chat/completions, GET /health
  • Bearer token authentication (Authorization: Bearer <key> header + ?key= query param)
  • WebSocket proxy to upstream DeepSeek API for chat completions
  • SSE streaming in OpenAI format (data: prefix, chat.completion.chunk objects, [DONE] terminator)
  • Non-streaming responses with usage token estimation
  • OpenAI-format error responses (error.message, error.type, error.code)
  • Code cleanup: bare except → specific exceptions, unused imports removed, f-string fixes

• README.md — Complete rewrite

  • Added OpenAI-compatible API section with full documentation
  • Added Cline, LangChain, OpenAI SDK integration examples
  • Added curl examples for all endpoints
  • Added environment variable reference table
  • Updated project structure and architecture sections

• requirements.txt — Added websockets>=12.0 dependency

• .gitignore — Added goal.md/GOAL.md

New API Endpoints

Method	Path	Description
GET	/v1/models	List available DeepSeek models
POST	/v1/chat/completions	Chat completion (streaming + non-streaming)
GET	/health	Health check

All existing endpoints (/cookies, /html) remain unchanged and functional.

Environment Variables

Variable	Default	Description
AUTH_KEY	(empty)	API key for Bearer auth. If not set, auth is disabled
MODEL_NAME	deepseek-chat	Default model name
SERVER_PORT	8021	Server port

Usage Example

Start server with auth

export AUTH_KEY=your-secret-key
python server.py

Use with OpenAI SDK

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8021/v1", api_key="your-secret-key")
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Testing

Verified all endpoints:

• GET /v1/models — Returns correct OpenAI format model list
• POST /v1/chat/completions (non-streaming) — Returns proper response with usage
• POST /v1/chat/completions (streaming) — SSE chunks with correct format + [DONE]
• Authentication — Bearer token validation works correctly
• GET /health — Returns {"status": "ok"}

Breaking Changes

None. All existing endpoints remain unchanged.