Metadata-Version: 2.4
Name: apideepseek
Version: 0.1.2
Summary: High-performance async Python client for the private DeepSeek API
Author: inmyuse
License-Expression: MIT
Project-URL: Homepage, https://github.com/inmyuse/apideepseek
Project-URL: Documentation, https://github.com/inmyuse/apideepseek#documentation
Project-URL: Issues, https://github.com/inmyuse/apideepseek/issues
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Framework :: AsyncIO
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Dynamic: license-file

# apideepseek

<p align="left">
  <img src="docs/assets/icon.svg" width="90">
</p>

![Python](https://img.shields.io/badge/python-3.9+-blue.svg)
![Platform](https://img.shields.io/badge/platform-linux%20%7C%20windows-lightgrey)
![Async](https://img.shields.io/badge/asyncio-fully%20async-blueviolet)
![DeepSeek](https://img.shields.io/badge/API-DeepSeek-blue)

`apideepseek` is an async Python client for the private DeepSeek API. It supports token or email/password authentication, streaming responses, multi-turn conversations, image uploads, generic file uploads, model modes, and account registration.

Russian documentation: [docs/ru/README.md](docs/ru/README.md)

## Installation

```bash
pip install apideepseek
```

Building from source requires a C++17 compiler with AVX2 support and `pybind11` for the PoW extension. See [docs/en/pow.md](docs/en/pow.md).

## Quick Start

```python
import asyncio
from apideepseek import DeepSeekClient

async def main():
    async with DeepSeekClient(token="YOUR_TOKEN") as client:
        result = await client.ask("Hello!")
        print(result.text)

asyncio.run(main())
```

Email/password login also works:

```python
async with DeepSeekClient(email="myname@example.com", password="password123") as client:
    result = await client.ask("Hello!")
    print(result.text)
```

## Model Modes

| Mode | Use When | Code |
|------|----------|------|
| Fast/default | Normal text chat and most file questions | `ModelType.DEFAULT` |
| Expert | Harder reasoning or expert answers | `ModelType.EXPERT` |
| Vision/recognition | Questions about images | `ModelType.VISION` |

```python
from apideepseek import DeepSeekClient, ModelType

async with DeepSeekClient(token="...", model=ModelType.DEFAULT) as client:
    fast = await client.ask("Short answer: what is asyncio?")
    expert = await client.ask("Analyze this deeply", model=ModelType.EXPERT)
```

## Attach Files to a Prompt

Use `file=` for one file and `files=` for several files. Paths are uploaded automatically before the prompt is sent.

```python
from pathlib import Path
from apideepseek import DeepSeekClient

async with DeepSeekClient(token="...") as client:
    result = await client.ask(
        "Summarize this file",
        file=Path("notes.txt"),
    )
    print(result.text)
```

You can attach source code the same way:

```python
result = await client.ask(
    "Review this function and explain what it returns",
    file=Path("sample_code.py"),
)
```

Attach several files:

```python
result = await client.ask(
    "Compare the JSON config with the CSV data",
    files=[Path("config.json"), Path("data.csv")],
)
```

Upload once and reuse the file object:

```python
uploaded = await client.upload_file(Path("report.pdf"))
first = await client.ask("Summarize the report", file=uploaded)
second = await client.ask("List the key risks", file=uploaded)
```

Raw bytes work too, but you must provide a filename so DeepSeek can detect the format:

```python
data = Path("contract.docx").read_bytes()
uploaded = await client.upload_file(data, filename="contract.docx")
result = await client.ask("Extract the main obligations", file=uploaded)
```

Common formats are passed through the same upload endpoint: TXT, Python/source code, JSON, CSV, PDF, DOCX, and other formats DeepSeek accepts. If DeepSeek rejects a file as empty or unsupported, `EmptyUploadedFileError` or `DeepSeekError` is raised.

## Attach Images

Images can be attached through `image=` or through the generic `file=` parameter. Use `image=`/`upload_image()` when you want local PNG/JPEG validation and image dimensions.

```python
from pathlib import Path
from apideepseek import DeepSeekClient, ModelType

async with DeepSeekClient(token="...") as client:
    result = await client.ask(
        "What is shown in this image?",
        image=Path("photo.jpg"),
        model=ModelType.VISION,
    )
    print(result.text)
```

Reuse an uploaded image:

```python
img = await client.upload_image(Path("photo.jpg"))
result = await client.ask("Describe the image", image=img, model=ModelType.VISION)
```

## Create a New Conversation

Use `client.new_conversation()` for a multi-turn chat. It remembers the last `message_id` and sends it as `parent_message_id` on the next turn.

```python
chat = client.new_conversation()
await chat.ask("Remember the attached file", file=Path("notes.txt"))
reply = await chat.ask("What did the file say?")
print(reply.text)
```

## Streaming

```python
async for chunk in client.ask_stream("Tell me about Python"):
    print(chunk, end="", flush=True)
```

Streaming works with files too:

```python
async for chunk in client.ask_stream("Summarize this file", file=Path("notes.txt")):
    print(chunk, end="", flush=True)
```

## Result Object

```python
result = await client.ask("Hello")
print(result.text)
print(result.session_id)
print(result.message_id)
```

## Documentation

- [DeepSeekClient methods](docs/en/client.md)
- [Conversation](docs/en/conversation.md)
- [Data types](docs/en/types.md)
- [Exceptions](docs/en/exceptions.md)
- [Proof-of-Work](docs/en/pow.md)
