Content
<p align="center">
<img src="Logo.png" alt="HyperSpace" width="550">
</p>
# Tool List
[](https://github.com/freerunningkid/HyperSpace/actions/workflows/tests.yml)
[](https://www.python.org/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
> **Let local AI Agent prioritize calling DeepSeek Web (¥0, native Python client) ⊗ DeepSeek API (low-cost) → Zhipu GLM (free fallback) with a three-layer hybrid reasoning architecture.**
>
> No external service dependency | Smart routing | PoW auto-solving | Auto-fallback | Cost tracking | 202 unit tests
## Why HyperSpace?
Local Agent (Reasonix / ClaudeCode / Copilot) calling large model APIs can be costly.
HyperSpace is an MCP service layer that intelligently routes between Agent and large models:
### Three-Layer Hybrid Engine (native implementation)
| Layer | Engine | Cost | Implementation | Applicable Scenarios |
|---|---|---|---|---|
| 🥇 **Primary** | DeepSeek Web | **¥0** | Native Python client (PoW + internal API) | Planning, search, image recognition, long text |
| 🥈 **Secondary** | DeepSeek API | ~¥2/M token | OpenAI compatible API call | Code generation, translation, structured output |
| 🥉 **Fallback** | Zhipu GLM | **¥0** | OpenAI compatible API call | When both primary and secondary are unavailable |
> **Core innovation**: No dependency on external services like OpenClaw or FreeLLMAPI. We independently implemented DeepSeek Web's internal API call (PoW challenge solving, session management, streaming dialogue, file upload), with self-contained Python code and zero external dependencies.
### Architecture Diagram
```mermaid
graph TD
Agent[Agent<br/>Reasonix/ClaudeCode] -->|MCP stdio| HS[HyperSpace Server]
subgraph "Hybrid Engine (core)"
HR[HybridRouter] --> TA[TaskAnalyzer<br/>feature analysis]
HR --> HC[HealthChecker<br/>credential detection]
HR --> FB[FallbackManager<br/>fallback management]
HR --> RP[ResultProcessor<br/>post-processing]
TA -->|rule matching| DECISION{routing decision}
DECISION -->|image/search/planning/long text| DW[DeepSeek Web<br/>native Python client]
DECISION -->|code/translation/structured| DA[DeepSeek API<br/>OpenAI compatible]
DECISION -->|fallback| ZP[Zhipu GLM-4.7-Flash]
DW -->|PoW solving + streaming SSE| WS[chat.deepseek.com]
DA -->|API call| DS[api.deepseek.com]
ZP -->|API call| ZS[open.bigmodel.cn]
end
subgraph "Auth layer"
WA[web_auth.py<br/>Playwright CDP] -->|extract Cookie + Bearer| AJ[deepseek_web_auth.json]
AJ --> DW
end
HS -->|auto / force_web / force_api / force_zhipu| HR
HS -->|legacy modes| LR[legacy routing<br/>select_tier + Executor]
LR --> LF[Zhipu/DeepSeek API]
```
Routing decision **zero token cost** — purely based on keywords and rules, without involving large models.
## Quick Start
### Requirements
- Python 3.10+
- Zhipu API Key (free, apply on [bigmodel.cn](https://bigmodel.cn/)) — **fallback required**
- (Recommended) DeepSeek API Key — secondary layer
- (Optional) Chrome browser — required for DeepSeek Web primary layer login
### Installation
```bash
# 1. Clone the project
git clone https://github.com/freerunningkid/HyperSpace.git
cd HyperSpace
# 2. Install dependencies
pip install -e ".[dev]"
# 3. (Optional) Install Playwright + Chromium — for extracting DeepSeek Web login credentials
pip install playwright
playwright install chromium
# 4. Configure API Key
cp .env.example .env
# Edit .env and fill in ZHIPU_API_KEY (required) and DEEPSEEK_API_KEY (recommended)
# 5. Extract DeepSeek Web credentials (optional, but enables search/planning/image recognition/long text at ¥0)
# Start Chrome in debugging mode:
# chrome.exe --remote-debugging-port=9222
# Log in to https://chat.deepseek.com in Chrome
# Then run:
python -m hyperspace.hybrid_engine.web_auth --extract
# 6. Verify readiness
python -c "from hyperspace.config import load_config; c=load_config(); print([t for t in c.providers if c.candidates_for(t)])"
```
### Integration with Agent
HyperSpace is a standard MCP stdio service. Add the following configuration to your Agent's MCP settings:
```json
{
"mcpServers": {
"hyperspace": {
"command": "python",
"args": ["path/to/HyperSpace/hyperspace/server.py"],
"env": { "PYTHONIOENCODING": "utf-8" },
"autoApprove": ["*"]
}
}
}
```
> Replace `path/to/HyperSpace` with your actual clone path. For Claude Code users, add the above configuration to the `.mcp.json` file in the project root directory.
### Integration with Agent
HyperSpace is a standard MCP stdio service compatible with all MCP protocol-supported Agents (Claude Code / VS Code Copilot / Cline / Roo Code, etc.).
Add the following configuration to your MCP settings file:
```json
{
"mcpServers": {
"hyperspace": {
"command": "python",
"args": ["path/to/HyperSpace/hyperspace/server.py"],
"env": { "PYTHONIOENCODING": "utf-8" },
"autoApprove": ["*"]
}
}
}
```
> Replace `path/to/HyperSpace` with your actual clone path.
### Usage Examples
Agent calls the `hyperspace_query` tool:
| Example prompt | Routing engine | Cost |
|---|---|---|
| "Help me create a study plan" | **DeepSeek Web** (native client, planning) | **¥0** |
| [User sends an image] "Describe this image" | **DeepSeek Web** (native image recognition) | **¥0** |
| "Write quicksort in Python" | **DeepSeek API** (code generation) | ~¥0.0004 |
| "Translate this text to English" | **DeepSeek API** (translation) | ~¥0.0001 |
| "Hello, nice weather today" | **DeepSeek Web** (simple Q&A) | **¥0** |
| mode=force_zhipu "..." | **Zhipu GLM-4.7-Flash** | **¥0** |
Each call returns with engine metadata:
```
---
[hyperspace] Engine: deepseek_web/deepseek-chat Planning: (chain of thought summary)
```
## Project Structure
```
HyperSpace/
├── hyperspace/ # Core package
│ ├── server.py # MCP server (dual paths: hybrid engine + legacy routing)
│ ├── config.py # Configuration loading (YAML + .env)
│ ├── router.py # Legacy routing decision (reserved for compatibility)
│ ├── executor.py # Legacy execution engine (reserved for compatibility)
│ ├── cost.py # Cost tracking log
│ ├── tiers.py # Tier enumeration
│ ├── hybrid_engine/ # 🆕 Hybrid reasoning engine (core innovation)
│ │ ├── __init__.py
│ │ ├── task_analyzer.py # Task feature analysis (keywords/regular expressions)
│ │ ├── health_checker.py # Service health detection (credential check + API detection)
│ │ ├── hybrid_router.py # Core routing decision (8-level priority + fallback chain)
│ │ ├── deepseek_web_client.py # 🆕 DeepSeek Web native client (PoW + SSE stream)
│ │ ├── web_auth.py # 🆕 Browser credential extraction (Playwright CDP)
│ │ ├── result_processor.py # Result post-processing (chain of thought extraction)
│ │ └── fallback.py # Fallback management (exponential backoff retry)
│ ├── providers/ # API call layer
│ │ ├── base.py # Protocol + exception type
│ │ └── openai_compat.py # OpenAI compatible client
│ └── experimental/ # Personal experiments (strictly isolated)
├── config/
│ ├── providers.yaml # tier → provider mapping
│ ├── routing.yaml # Legacy routing rules
│ └── hybrid_config.yaml # 🆕 Hybrid engine configuration
├── data/
│ ├── hyperspace_cost.log # Cost log (gitignored)
│ └── deepseek_web_auth.json # 🆕 Web credentials (gitignored)
├── tests/
│ ├── test_router.py # Legacy routing rule test (16 cases)
│ ├── test_providers.py # Provider exception + fallback test (9 cases)
│ └── test_hybrid_engine.py # 🆕 Hybrid engine test (39 cases)
├── docs/
│ └── architecture.md
├── pyproject.toml
├── README.md
└── LICENSE # MIT
```
## Routing Rules
### Hybrid Engine Routing (auto mode)
Priority from high to low:
| Condition | Routed to | Reason |
|---|---|---|
| Image present (`has_image`) | **DeepSeek Web** (native Python client) | Web-native image recognition |
| Search required (`needs_search`) | **DeepSeek Web** | Web can search online |
| Planning required (`needs_planning`) | **DeepSeek Web** | Long text planning capability |
| Long text (`is_long`, >5000 characters) | **DeepSeek Web** | 1M context window |
| Code generation (`needs_coding`) | **DeepSeek API** | API output code more stable |
| Translation (`needs_translation`) | **DeepSeek API** | Standardized translation |
| Structured output (`needs_structured_output`) | **DeepSeek API** | Supports JSON mode |
| Default (simple Q&A/chit-chat) | **DeepSeek Web** | Economic priority |
### Explicit Mode Override
| mode | Behavior |
|---|---|
| `auto` | Automatic decision (default) |
| `force_web` | Force use of DeepSeek Web (native client) |
| `force_api` | Force use of DeepSeek API |
| `force_zhipu` | Force use of Zhipu GLM fallback |
| `free_text` / `free_vision` | Legacy routing (backward compatible) |
### Fallback Chain
`DeepSeek Web → DeepSeek API → Zhipu GLM → Friendly error prompt`
## Cost Tracking
Each call is written to `data/hyperspace_cost.log` in JSONL format:
```json
{"ts":"2026-06-21T11:08:38","provider":"deepseek","model":"deepseek-chat",
"requested_tier":"cheap_capable","actual_tier":"cheap_capable",
"prompt_tokens":10,"completion_tokens":2,
"actual_cost_usd":5e-06,"equivalent_premium_usd":6e-05,"saved_usd":5.5e-05}
```
Available command to view summary:
```bash
python -m hyperspace.summary
```
> **Honest caliber**: Savings ratio varies depending on usage patterns. The project does not preset a fixed "save 90%" propaganda figure, and actual data will be used.
## DeepSeek Web Native Client
`hyperspace/hybrid_engine/deepseek_web_client.py` is our independently implemented DeepSeek Web internal API client:
- **PoW solving**: SHA256 leading zero PoW, self-implementation with zero external dependencies
- **Streaming dialogue**: SSE stream parsing, supporting streaming real-time return
- **Chain of thought extraction**: Automatic separation of reasoning_content and text
- **File upload**: Supports image upload + polling status confirmation
- **Session management**: Automatic creation/reuse of chat_session
### Credential Management
`hyperspace/hybrid_engine/web_auth.py` connects Chrome via Playwright CDP:
```bash
# Extract DeepSeek login credentials
# Start Chrome in debugging mode:
chrome.exe --remote-debugging-port=9222
# Log in to chat.deepseek.com and run:
python -m hyperspace.hybrid_engine.web_auth --extract
# View credential status:
python -m hyperspace.hybrid_engine.web_auth --status
```
Credentials are saved to `data/deepseek_web_auth.json`, including Cookie + Bearer Token + User-Agent.
## Development
```bash
# Run all tests (202 unit tests, zero network dependencies)
pytest tests/ -v
```
## License
[MIT](LICENSE)
*This is my first open-source project, PRs and ideas are warmly welcomed!*
