fastkeel 0.1.0__tar.gz

fastkeel-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(python3 -m pip install -e \".[dev]\" -q)",
+      "Bash(uv pip *)",
+      "Bash(uv run *)"
+    ]
+  }
+}

fastkeel-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+      - name: Publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*

fastkeel-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Test
+on: [push, pull_request]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest

fastkeel-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+*.env.local
+
+# Data
+*.db
+*.sqlite3
+/data/
+
+# Internal design docs (not for public)
+DESIGN.md
+TAD.md
+CLAUDE.md
+docs/
+
+# Lock files (library, not an application)
+uv.lock

fastkeel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helioswei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastkeel-0.1.0/Makefile

@@ -0,0 +1,18 @@
+.PHONY: lint test build publish clean
+
+lint:
+	ruff check .
+
+test:
+	pytest
+
+build:
+	python -m build
+
+publish: build
+	twine upload dist/*
+
+clean:
+	rm -rf dist/ build/ *.egg-info
+	rm -rf .pytest_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

fastkeel-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: fastkeel
+Version: 0.1.0
+Summary: FastAPI backend scaffold — user auth, social, subscriptions, jobs & LLM
+Project-URL: Homepage, https://github.com/helioswei/fastkeel
+Author: Helioswei
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: apscheduler<4.0.0,>=3.10.0
+Requires-Dist: fastapi<1.0.0,>=0.100.0
+Requires-Dist: httpx<1.0.0,>=0.25.0
+Requires-Dist: jinja2<4.0.0,>=3.0.0
+Requires-Dist: pyjwt<3.0.0,>=2.0.0
+Requires-Dist: sqlalchemy<3.0.0,>=2.0.0
+Requires-Dist: structlog<25.0.0,>=23.0.0
+Requires-Dist: typer<1.0.0,>=0.9.0
+Provides-Extra: dev
+Requires-Dist: build<2.0.0,>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<2.0.0,>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-mock<5.0.0,>=3.10.0; extra == 'dev'
+Requires-Dist: pytest<9.0.0,>=7.0.0; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.1.0; extra == 'dev'
+Requires-Dist: twine<6.0.0,>=4.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fastkeel ⚡
+
+> FastAPI backend scaffold — user auth, social, subscriptions, jobs & LLM.
+> `pip install fastkeel`，一行命令生成完整后端骨架。
+
+**Status:** v0.1.0 — 生产就绪，[MIT](./LICENSE) 开源。
+
+---
+
+## 快速开始
+
+```bash
+# 安装
+pip install fastkeel
+
+# 生成项目
+fastkeel new my-app --with-user --with-social --with-payment --with-jobs
+cd my-app
+
+# 安装依赖并启动
+pip install uvicorn
+python main.py
+```
+
+生成的项目直接可用：注册、登录、搭子关系、支付订阅、定时任务 — 一个 `main.py` 全搞定。
+
+---
+
+## CLI 用法
+
+```bash
+fastkeel new <项目名> [--with-user] [--with-social] [--with-payment] [--with-jobs] [--path <路径>]
+```
+
+| 参数 | 默认 | 说明 |
+|:----|:-----|:-----|
+| `--with-user` | True | 设备注册 + JWT 认证 |
+| `--with-social` | False | 搭子关系 + 群组管理 |
+| `--with-payment` | False | 订阅管理 + 收据验证 |
+| `--with-jobs` | False | APScheduler 定时任务 |
+| `--path` | `.` | 项目生成路径 |
+
+不选的模块不注册路由、不创建表、不引入依赖。
+
+---
+
+## 模块
+
+| 模块 | 提供 |
+|:----|:------|
+| `core` | FastAPI app factory、Config (TOML + env)、SQLite (WAL)、JWT、CORS + 统一错误处理 |
+| `user` | 设备注册、登录、JWT 认证、资料更新 |
+| `social` | 搭子邀请码、搭子绑定/解除、群组创建/加入/解散 |
+| `payment` | 套餐管理、收据验证（渠道无关）、订阅生命周期、支付流水 |
+| `jobs` | APScheduler 定时任务、心跳检查、SQLite 持久化 |
+| `contrib/llm` | LLM API 客户端（自动重试、限流、流式、结构化输出）|
+
+### 架构
+
+```
+你的项目
+├── main.py          # import fastkeel → compose app
+├── config.toml      # TOML 配置（环境变量覆盖）
+├── project/         # 你的业务逻辑
+│   ├── routes/
+│   ├── logic/
+│   └── prompts/
+└── tests/
+
+        │ pip install fastkeel
+        v
+fastkeel (this repo)
+├── core/            # 100% 通用，不修改
+├── modules/         # 90% 通用，include_*() 选装
+├── contrib/         # 扩展集成，按需 import
+└── cli/             # fastkeel new 命令
+```
+
+分层规则：
+- `core/` — 项目**永不修改**。需要改意味着抽象边界要调整
+- `modules/` — 通过 config 配置，**不修改源码**
+- `project/` — 写业务逻辑的地方
+
+---
+
+## 开发
+
+```bash
+# Setup
+git clone https://github.com/helioswei/fastkeel
+cd fastkeel
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Commands
+make lint           # ruff check .
+make test           # pytest
+make build          # python -m build
+make publish        # build + twine upload
+
+# Test single file
+pytest tests/test_modules/test_user.py -v
+```
+
+### 测试 (122 tests, 1.5s)
+
+| 测试集 | 测试数 |
+|:-------|:-------|
+| `test_core/` (config, db, auth, middleware, app) | 47 |
+| `test_modules/test_user.py` | 13 |
+| `test_modules/test_social.py` | 21 |
+| `test_modules/test_payment.py` | 13 |
+| `test_modules/test_jobs.py` | 5 |
+| `test_contrib/test_llm.py` | 8 |
+| `test_cli/test_new.py` | 9 |
+| `test_integration.py` | 6 |
+| **合计** | **122** |
+
+---
+
+## Roadmap
+
+- [ ] **PyPI release** — `python -m build && twine upload dist/*`
+- [ ] **`user_extra_fields` dynamic columns** — `ALTER TABLE ADD COLUMN` from config
+- [ ] **End-to-end generated project test** — `fastkeel new` → `pip install` → serve → curl
+- [ ] **Webhook signature verification** — validate `payment_webhook_secret`
+
+---
+
+MIT © 2026 Helioswei

fastkeel-0.1.0/README.md

@@ -0,0 +1,130 @@
+# fastkeel ⚡
+
+> FastAPI backend scaffold — user auth, social, subscriptions, jobs & LLM.
+> `pip install fastkeel`，一行命令生成完整后端骨架。
+
+**Status:** v0.1.0 — 生产就绪，[MIT](./LICENSE) 开源。
+
+---
+
+## 快速开始
+
+```bash
+# 安装
+pip install fastkeel
+
+# 生成项目
+fastkeel new my-app --with-user --with-social --with-payment --with-jobs
+cd my-app
+
+# 安装依赖并启动
+pip install uvicorn
+python main.py
+```
+
+生成的项目直接可用：注册、登录、搭子关系、支付订阅、定时任务 — 一个 `main.py` 全搞定。
+
+---
+
+## CLI 用法
+
+```bash
+fastkeel new <项目名> [--with-user] [--with-social] [--with-payment] [--with-jobs] [--path <路径>]
+```
+
+| 参数 | 默认 | 说明 |
+|:----|:-----|:-----|
+| `--with-user` | True | 设备注册 + JWT 认证 |
+| `--with-social` | False | 搭子关系 + 群组管理 |
+| `--with-payment` | False | 订阅管理 + 收据验证 |
+| `--with-jobs` | False | APScheduler 定时任务 |
+| `--path` | `.` | 项目生成路径 |
+
+不选的模块不注册路由、不创建表、不引入依赖。
+
+---
+
+## 模块
+
+| 模块 | 提供 |
+|:----|:------|
+| `core` | FastAPI app factory、Config (TOML + env)、SQLite (WAL)、JWT、CORS + 统一错误处理 |
+| `user` | 设备注册、登录、JWT 认证、资料更新 |
+| `social` | 搭子邀请码、搭子绑定/解除、群组创建/加入/解散 |
+| `payment` | 套餐管理、收据验证（渠道无关）、订阅生命周期、支付流水 |
+| `jobs` | APScheduler 定时任务、心跳检查、SQLite 持久化 |
+| `contrib/llm` | LLM API 客户端（自动重试、限流、流式、结构化输出）|
+
+### 架构
+
+```
+你的项目
+├── main.py          # import fastkeel → compose app
+├── config.toml      # TOML 配置（环境变量覆盖）
+├── project/         # 你的业务逻辑
+│   ├── routes/
+│   ├── logic/
+│   └── prompts/
+└── tests/
+
+        │ pip install fastkeel
+        v
+fastkeel (this repo)
+├── core/            # 100% 通用，不修改
+├── modules/         # 90% 通用，include_*() 选装
+├── contrib/         # 扩展集成，按需 import
+└── cli/             # fastkeel new 命令
+```
+
+分层规则：
+- `core/` — 项目**永不修改**。需要改意味着抽象边界要调整
+- `modules/` — 通过 config 配置，**不修改源码**
+- `project/` — 写业务逻辑的地方
+
+---
+
+## 开发
+
+```bash
+# Setup
+git clone https://github.com/helioswei/fastkeel
+cd fastkeel
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Commands
+make lint           # ruff check .
+make test           # pytest
+make build          # python -m build
+make publish        # build + twine upload
+
+# Test single file
+pytest tests/test_modules/test_user.py -v
+```
+
+### 测试 (122 tests, 1.5s)
+
+| 测试集 | 测试数 |
+|:-------|:-------|
+| `test_core/` (config, db, auth, middleware, app) | 47 |
+| `test_modules/test_user.py` | 13 |
+| `test_modules/test_social.py` | 21 |
+| `test_modules/test_payment.py` | 13 |
+| `test_modules/test_jobs.py` | 5 |
+| `test_contrib/test_llm.py` | 8 |
+| `test_cli/test_new.py` | 9 |
+| `test_integration.py` | 6 |
+| **合计** | **122** |
+
+---
+
+## Roadmap
+
+- [ ] **PyPI release** — `python -m build && twine upload dist/*`
+- [ ] **`user_extra_fields` dynamic columns** — `ALTER TABLE ADD COLUMN` from config
+- [ ] **End-to-end generated project test** — `fastkeel new` → `pip install` → serve → curl
+- [ ] **Webhook signature verification** — validate `payment_webhook_secret`
+
+---
+
+MIT © 2026 Helioswei

fastkeel-0.1.0/fastkeel/__init__.py

@@ -0,0 +1,4 @@
+from fastkeel.core.app import create_app
+from fastkeel.core.config import Config
+
+__all__ = ["create_app", "Config"]

fastkeel-0.1.0/fastkeel/cli/__init__.py

@@ -0,0 +1,5 @@
+# fastkeel/cli/__init__.py
+
+from fastkeel.cli.new import app as cli_app
+
+app = cli_app

fastkeel-0.1.0/fastkeel/cli/new.py

@@ -0,0 +1,57 @@
+# fastkeel/cli/new.py
+from pathlib import Path
+
+import typer
+from jinja2 import Environment, PackageLoader
+
+app = typer.Typer(help="fastkeel - FastAPI backend scaffold")
+
+
+@app.command()
+def new(
+    name: str = typer.Argument(help="项目名称"),
+    with_user: bool = typer.Option(True, "--with-user/--no-with-user", help="启用用户模块"),
+    with_social: bool = typer.Option(False, "--with-social/--no-with-social", help="启用社交模块"),
+    with_payment: bool = typer.Option(False, "--with-payment/--no-with-payment", help="启用支付模块"),
+    with_jobs: bool = typer.Option(False, "--with-jobs/--no-with-jobs", help="启用定时任务模块"),
+    path: str = typer.Option(".", "--path", help="生成路径"),
+):
+    """生成 FastAPI 项目骨架。"""
+    target_dir = Path(path) / name
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    env = Environment(
+        loader=PackageLoader("fastkeel", "templates/default"),
+    )
+
+    templates = [
+        "main.py.j2",
+        "config.toml.j2",
+        "pyproject.toml.j2",
+        "project/__init__.py.j2",
+        "project/models/__init__.py.j2",
+        "project/routes/__init__.py.j2",
+        "project/logic/__init__.py.j2",
+        "project/prompts/.gitkeep.j2",
+        "tests/__init__.py.j2",
+        "tests/conftest.py.j2",
+    ]
+
+    context = {
+        "project_name": name,
+        "with_user": with_user,
+        "with_social": with_social,
+        "with_payment": with_payment,
+        "with_jobs": with_jobs,
+    }
+
+    for template_name in templates:
+        dest = target_dir / template_name.removesuffix(".j2")
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        template = env.get_template(template_name)
+        content = template.render(**context)
+        dest.write_text(content)
+
+    typer.echo(f"✅ {name} 已创建在 {target_dir}")
+    typer.echo(f"   cd {name}")
+    typer.echo("   pip install -e .")

fastkeel-0.1.0/fastkeel/contrib/llm.py

@@ -0,0 +1,99 @@
+# fastkeel/contrib/llm.py
+import asyncio
+import json
+import logging
+from collections.abc import AsyncGenerator
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from fastkeel.core.config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class LLMClient:
+    """LLM API client with retry, rate limiting, and structured output."""
+
+    def __init__(self, config: Config) -> None:
+        self.api_base = config.llm_api_base.rstrip("/")
+        self.model = config.llm_model
+        self.max_retries = config.llm_max_retries
+        self.semaphore = asyncio.Semaphore(config.llm_rate_limit)
+        self._client = httpx.AsyncClient(
+            base_url=self.api_base,
+            headers={"Authorization": f"Bearer {config.llm_api_key}"},
+            timeout=60,
+        )
+
+    async def chat(self, messages: list[dict], **kwargs: Any) -> str:
+        """Send a chat request and return the response text."""
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            **kwargs,
+        }
+
+        for attempt in range(self.max_retries + 1):
+            async with self.semaphore:
+                try:
+                    response = await self._client.post("/chat/completions", json=payload)
+                except httpx.RequestError as e:
+                    if attempt < self.max_retries:
+                        wait = 2 ** attempt
+                        logger.warning("Request failed (attempt %d): %s, retrying in %ds", attempt + 1, e, wait)
+                        await asyncio.sleep(wait)
+                        continue
+                    raise RuntimeError(f"API request failed after {self.max_retries} retries") from e
+
+                if response.status_code in (429, 502, 503, 504) and attempt < self.max_retries:
+                    wait = 2 ** attempt
+                    logger.warning("HTTP %d (attempt %d), retrying in %ds", response.status_code, attempt + 1, wait)
+                    await asyncio.sleep(wait)
+                    continue
+
+                if response.status_code != 200:
+                    raise RuntimeError(
+                        f"API error: HTTP {response.status_code} — {response.text[:200]}"
+                    )
+
+                data = response.json()
+                return data["choices"][0]["message"]["content"]
+
+        raise RuntimeError(f"API request failed after {self.max_retries} retries")
+
+    async def chat_stream(self, messages: list[dict], **kwargs: Any) -> AsyncGenerator[str, None]:
+        """Stream a chat response chunk by chunk."""
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "stream": True,
+            **kwargs,
+        }
+
+        async with self.semaphore:
+            async with self._client.stream(
+                "POST", "/chat/completions", json=payload
+            ) as response:
+                async for line in response.aiter_lines():
+                    if line.startswith("data: ") and line != "data: [DONE]":
+                        chunk = json.loads(line[6:])
+                        delta = chunk["choices"][0].get("delta", {})
+                        content = delta.get("content", "")
+                        if content:
+                            yield content
+
+    async def chat_structured(
+        self,
+        messages: list[dict],
+        response_model: type[BaseModel],
+        **kwargs: Any,
+    ) -> BaseModel:
+        """Send a chat request and parse the response as a Pydantic model."""
+        text = await self.chat(messages, **kwargs)
+        try:
+            data = json.loads(text)
+            return response_model.model_validate(data)
+        except (json.JSONDecodeError, ValidationError) as e:
+            raise ValueError(f"Failed to parse structured output: {e}") from e

fastkeel-0.1.0/fastkeel/contrib/streaming.py

@@ -0,0 +1,31 @@
+# fastkeel/contrib/streaming.py
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from fastapi.responses import StreamingResponse
+
+
+class SSEStreamer:
+    """SSE (Server-Sent Events) streaming response utilities."""
+
+    @staticmethod
+    def from_generator(gen: AsyncGenerator[str, None]) -> StreamingResponse:
+        """Wrap an async string generator as an SSE StreamingResponse."""
+        async def event_stream() -> AsyncGenerator[bytes, None]:
+            async for chunk in gen:
+                yield f"data: {chunk}\n\n".encode("utf-8")
+
+        return StreamingResponse(
+            event_stream(),
+            media_type="text/event-stream",
+        )
+
+    @staticmethod
+    async def from_llm_stream(
+        llm_client: Any,
+        messages: list[dict],
+    ) -> StreamingResponse:
+        """Convenience: wrap LLM streaming response as SSE."""
+        return SSEStreamer.from_generator(
+            llm_client.chat_stream(messages)
+        )

fastkeel-0.1.0/fastkeel/core/app.py

@@ -0,0 +1,38 @@
+# fastkeel/core/app.py
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from fastkeel.core.auth import set_config_for_dependency
+from fastkeel.core.config import Config
+from fastkeel.core.middleware import register_middleware
+
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Application lifecycle: startup / shutdown."""
+    # Startup: DB init is deferred to first include_*() call
+    yield
+    # Shutdown: nothing to clean up (SQLite handles itself)
+
+
+def create_app(config: Config) -> FastAPI:
+    """Create a FastAPI app instance. Register middleware, lifecycle hooks."""
+    app = FastAPI(title=config.app_name, debug=config.debug, lifespan=_lifespan)
+
+    # Store config for access elsewhere
+    app.state.config = config
+
+    # Set config for auth dependency injection
+    set_config_for_dependency(config)
+
+    # Register middleware (CORS, error handling)
+    register_middleware(app, config)
+
+    # Health check
+    @app.get("/")
+    def health_check():
+        return {"status": "ok", "app": config.app_name}
+
+    return app