AIserver 0.1.0__tar.gz

aiserver-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5

aiserver-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.14"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install project
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Test
+        run: python -m pytest
+
+  package:
+    name: Package validation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tools
+        run: python -m pip install build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*

aiserver-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+  attestations: write
+
+jobs:
+  release:
+    name: Build and publish GitHub release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install project and build tools
+        run: python -m pip install -e ".[dev]"
+
+      - name: Verify tag version
+        run: >-
+          python -c "import os, pathlib, tomllib;
+          version=tomllib.loads(pathlib.Path('pyproject.toml').read_text('utf-8'))['project']['version'];
+          expected=os.environ['GITHUB_REF_NAME'].removeprefix('v');
+          assert version == expected, f'tag {expected} does not match package {version}'"
+
+      - name: Lint and test
+        run: |
+          python -m ruff check .
+          python -m pytest
+
+      - name: Build and validate distributions
+        run: |
+          python -m build
+          python -m twine check dist/*
+
+      - name: Generate checksums
+        working-directory: dist
+        run: sha256sum aiserver-* > SHA256SUMS.txt
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: "dist/aiserver-*"
+
+      - name: Publish GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME"
+          dist/*
+          --repo "$GITHUB_REPOSITORY"
+          --verify-tag
+          --generate-notes
+          --title "$GITHUB_REF_NAME"

aiserver-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.venv/
+.wheel-test/
+build/
+dist/
+htmlcov/

aiserver-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 0.1.0 - 2026-08-20
+
+- Rebuilt AIserver from scratch as a local-first AI inference task server.
+- Added typed task registration with generated OpenAPI schemas.
+- Added direct execution and in-memory asynchronous jobs.
+- Added progress reporting, timeouts, concurrency limits, and lifecycle hooks.
+- Added optional bearer-token authentication and request-size limits.
+- Added a safe CLI that binds to localhost by default.
+
+This release does not preserve the unrelated API from the historical 0.0.x package.

aiserver-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+AIserver keeps a deliberately small scope: single-process, local-first serving for typed Python
+inference tasks. Discuss substantial features in an issue before implementing them.
+
+## Development setup
+
+```bash
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"
+python -m ruff check .
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+Use the activation command appropriate for your shell on Linux or macOS.
+
+Do not include model weights, credentials, private model inputs, generated datasets, or telemetry
+in a contribution. New behavior should include focused tests and documentation.

aiserver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NocoldBob
+
+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.

aiserver-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: AIserver
+Version: 0.1.0
+Summary: A lightweight, local-first Python server for typed AI inference tasks
+Project-URL: Homepage, https://github.com/NocoldBob/AIserver
+Project-URL: Documentation, https://github.com/NocoldBob/AIserver#readme
+Project-URL: Repository, https://github.com/NocoldBob/AIserver.git
+Project-URL: Issues, https://github.com/NocoldBob/AIserver/issues
+Project-URL: Changelog, https://github.com/NocoldBob/AIserver/blob/main/CHANGELOG.md
+Author: NocoldBob
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,fastapi,inference,local-first,model-serving
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: pydantic<3.0,>=2.8
+Requires-Dist: uvicorn<1.0,>=0.30
+Provides-Extra: dev
+Requires-Dist: build<2.0,>=1.2; extra == 'dev'
+Requires-Dist: httpx2<3.0,>=2.10; extra == 'dev'
+Requires-Dist: pytest<10.0,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.9; extra == 'dev'
+Requires-Dist: twine<7.0,>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AIserver
+
+[![PyPI](https://img.shields.io/pypi/v/AIserver.svg)](https://pypi.org/project/AIserver/)
+[![Python](https://img.shields.io/pypi/pyversions/AIserver.svg)](https://pypi.org/project/AIserver/)
+[![CI](https://github.com/NocoldBob/AIserver/actions/workflows/ci.yml/badge.svg)](https://github.com/NocoldBob/AIserver/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-2f6f50.svg)](LICENSE)
+
+[中文说明](docs/README.zh-CN.md)
+
+AIserver is a lightweight, local-first Python server for exposing AI inference functions as
+secure, typed, and concurrency-controlled HTTP APIs.
+
+It is intentionally smaller than a model runtime or distributed serving platform. Bring any
+Python model or pipeline you already use; AIserver handles request validation, task execution,
+job status, progress, lifecycle hooks, and conservative network defaults.
+
+## Features
+
+- Turn typed Python functions into documented HTTP endpoints.
+- Run tasks directly or submit in-memory asynchronous jobs.
+- Limit concurrency per task to protect CPU, GPU, and model memory.
+- Report progress from synchronous or asynchronous inference code.
+- Apply per-task timeouts and bounded job history.
+- Load and release models with startup and shutdown hooks.
+- Protect private endpoints with `AISERVER_TOKEN`.
+- Reject oversized request bodies and bind to localhost by default.
+- Generate OpenAPI documentation automatically at `/docs`.
+- No telemetry, model downloads, protocol proxy, or request-body logging.
+
+## Requirements
+
+- Python 3.11 or newer
+- Windows, Linux, or macOS
+
+## Install
+
+```bash
+pip install AIserver
+```
+
+Until `0.1.0` is available on PyPI, install the wheel from the GitHub Release or build from source.
+
+## Quick start
+
+Create `app.py`:
+
+```python
+from aiserver import AIServer, TaskContext
+
+server = AIServer("demo")
+
+
+@server.task(concurrency=2, timeout=30)
+def classify(text: str, context: TaskContext) -> dict[str, str]:
+    context.report(0.5, "running inference")
+    return {"label": text.upper()}
+```
+
+Run it:
+
+```bash
+aiserver run app:server
+```
+
+Open `http://127.0.0.1:8000/docs`, or call it directly:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/tasks/classify/run \
+  -H "Content-Type: application/json" \
+  -d '{"text":"hello"}'
+```
+
+Submit the same task as a job:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/tasks/classify/jobs \
+  -H "Content-Type: application/json" \
+  -d '{"text":"hello"}'
+```
+
+Poll the returned `status_url` to read progress and the final result.
+
+## Lifecycle hooks
+
+Keep large model objects in your application module and initialize them once:
+
+```python
+model = None
+
+
+@server.on_startup
+def load_model():
+    global model
+    model = load_your_model()
+
+
+@server.on_shutdown
+def release_model():
+    global model
+    model = None
+```
+
+AIserver is deliberately single-process so tasks can share an in-memory model. Its asynchronous
+job records are not persistent and are lost when the process restarts.
+
+## LAN access
+
+The CLI refuses unauthenticated non-loopback binding by default. Set the token in the environment,
+then start the server:
+
+```powershell
+$env:AISERVER_TOKEN = "use-a-long-random-value"
+aiserver run app:server --host 0.0.0.0
+```
+
+Clients can use either header:
+
+```text
+Authorization: Bearer <token>
+X-API-Key: <token>
+```
+
+Do not pass tokens on the command line or commit them to source control. Use a reverse proxy with
+TLS before exposing AIserver outside a trusted private network.
+
+## Scope
+
+AIserver is not an LLM inference engine, OpenAI/Anthropic protocol gateway, model downloader,
+distributed scheduler, or hosted control plane. Projects that need those capabilities should use
+specialized runtimes and platforms.
+
+## Historical package notice
+
+Version `0.1.0` is a clean rewrite. It does not preserve the unrelated remote-chat and robot demo
+APIs from the historical `0.0.x` releases. Those releases should not be used.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+## License
+
+MIT

aiserver-0.1.0/README.md

@@ -0,0 +1,150 @@
+# AIserver
+
+[![PyPI](https://img.shields.io/pypi/v/AIserver.svg)](https://pypi.org/project/AIserver/)
+[![Python](https://img.shields.io/pypi/pyversions/AIserver.svg)](https://pypi.org/project/AIserver/)
+[![CI](https://github.com/NocoldBob/AIserver/actions/workflows/ci.yml/badge.svg)](https://github.com/NocoldBob/AIserver/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-2f6f50.svg)](LICENSE)
+
+[中文说明](docs/README.zh-CN.md)
+
+AIserver is a lightweight, local-first Python server for exposing AI inference functions as
+secure, typed, and concurrency-controlled HTTP APIs.
+
+It is intentionally smaller than a model runtime or distributed serving platform. Bring any
+Python model or pipeline you already use; AIserver handles request validation, task execution,
+job status, progress, lifecycle hooks, and conservative network defaults.
+
+## Features
+
+- Turn typed Python functions into documented HTTP endpoints.
+- Run tasks directly or submit in-memory asynchronous jobs.
+- Limit concurrency per task to protect CPU, GPU, and model memory.
+- Report progress from synchronous or asynchronous inference code.
+- Apply per-task timeouts and bounded job history.
+- Load and release models with startup and shutdown hooks.
+- Protect private endpoints with `AISERVER_TOKEN`.
+- Reject oversized request bodies and bind to localhost by default.
+- Generate OpenAPI documentation automatically at `/docs`.
+- No telemetry, model downloads, protocol proxy, or request-body logging.
+
+## Requirements
+
+- Python 3.11 or newer
+- Windows, Linux, or macOS
+
+## Install
+
+```bash
+pip install AIserver
+```
+
+Until `0.1.0` is available on PyPI, install the wheel from the GitHub Release or build from source.
+
+## Quick start
+
+Create `app.py`:
+
+```python
+from aiserver import AIServer, TaskContext
+
+server = AIServer("demo")
+
+
+@server.task(concurrency=2, timeout=30)
+def classify(text: str, context: TaskContext) -> dict[str, str]:
+    context.report(0.5, "running inference")
+    return {"label": text.upper()}
+```
+
+Run it:
+
+```bash
+aiserver run app:server
+```
+
+Open `http://127.0.0.1:8000/docs`, or call it directly:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/tasks/classify/run \
+  -H "Content-Type: application/json" \
+  -d '{"text":"hello"}'
+```
+
+Submit the same task as a job:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/tasks/classify/jobs \
+  -H "Content-Type: application/json" \
+  -d '{"text":"hello"}'
+```
+
+Poll the returned `status_url` to read progress and the final result.
+
+## Lifecycle hooks
+
+Keep large model objects in your application module and initialize them once:
+
+```python
+model = None
+
+
+@server.on_startup
+def load_model():
+    global model
+    model = load_your_model()
+
+
+@server.on_shutdown
+def release_model():
+    global model
+    model = None
+```
+
+AIserver is deliberately single-process so tasks can share an in-memory model. Its asynchronous
+job records are not persistent and are lost when the process restarts.
+
+## LAN access
+
+The CLI refuses unauthenticated non-loopback binding by default. Set the token in the environment,
+then start the server:
+
+```powershell
+$env:AISERVER_TOKEN = "use-a-long-random-value"
+aiserver run app:server --host 0.0.0.0
+```
+
+Clients can use either header:
+
+```text
+Authorization: Bearer <token>
+X-API-Key: <token>
+```
+
+Do not pass tokens on the command line or commit them to source control. Use a reverse proxy with
+TLS before exposing AIserver outside a trusted private network.
+
+## Scope
+
+AIserver is not an LLM inference engine, OpenAI/Anthropic protocol gateway, model downloader,
+distributed scheduler, or hosted control plane. Projects that need those capabilities should use
+specialized runtimes and platforms.
+
+## Historical package notice
+
+Version `0.1.0` is a clean rewrite. It does not preserve the unrelated remote-chat and robot demo
+APIs from the historical `0.0.x` releases. Those releases should not be used.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+## License
+
+MIT

aiserver-0.1.0/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version.
+
+## Reporting a vulnerability
+
+Use GitHub private vulnerability reporting for this repository. Do not open a public issue
+containing credentials, private model inputs, or internal network details.
+
+## Security defaults
+
+- `aiserver run` binds to `127.0.0.1` by default.
+- Non-loopback binding requires `AISERVER_TOKEN` unless the operator explicitly passes
+  `--allow-unauthenticated`.
+- Tokens are read from the environment and are not accepted as command-line values.
+- AIserver does not include telemetry or request-body logging.
+- Uploaded or submitted values are never treated as executable code.
+
+AIserver is a single-process development and LAN-serving tool. Put it behind a production
+reverse proxy when exposing it beyond a trusted private network.

aiserver-0.1.0/docs/README.zh-CN.md

@@ -0,0 +1,98 @@
+# AIserver 中文说明
+
+AIserver 是一个轻量、本地优先的 Python AI 任务服务器，用于把推理函数快速发布为
+安全、类型明确并支持并发控制的 HTTP API。
+
+它不是模型推理引擎或云平台。你可以继续使用 PyTorch、ONNX Runtime、TensorRT、
+OpenCV、Ollama 客户端或任意 Python 代码，AIserver 只负责可靠地对外提供任务接口。
+
+## 主要能力
+
+- 根据 Python 类型注解自动校验输入并生成 OpenAPI 文档。
+- 同一个任务既可以直接执行，也可以提交为内存异步任务。
+- 为每个任务设置并发数，避免多个请求耗尽显存或内存。
+- 支持进度、状态、结果查询和任务超时。
+- 通过启动和关闭钩子统一加载、释放模型。
+- 默认只监听 `127.0.0.1`。
+- 使用 `AISERVER_TOKEN` 保护局域网接口。
+- 限制请求体大小，不记录请求内容，不包含遥测。
+
+## 安装
+
+```powershell
+pip install AIserver
+```
+
+## 快速开始
+
+新建 `app.py`：
+
+```python
+from aiserver import AIServer, TaskContext
+
+server = AIServer("demo")
+
+
+@server.task(concurrency=1, timeout=60)
+def detect(image_path: str, context: TaskContext) -> dict:
+    context.report(0.2, "loading image")
+    result = model.predict(image_path)
+    context.report(0.9, "formatting result")
+    return {"detections": result}
+```
+
+启动：
+
+```powershell
+aiserver run app:server
+```
+
+然后访问 `http://127.0.0.1:8000/docs`，可以直接在浏览器中调试接口。
+
+### 直接执行
+
+```text
+POST /v1/tasks/detect/run
+```
+
+请求会等待任务完成并直接返回结果，适合耗时较短的推理。
+
+### 异步任务
+
+```text
+POST /v1/tasks/detect/jobs
+GET  /v1/jobs/{job_id}
+```
+
+提交接口立即返回任务 ID，随后通过状态接口查询进度和结果，适合长时间推理。
+
+## 局域网使用
+
+开放到局域网前先设置长随机令牌：
+
+```powershell
+$env:AISERVER_TOKEN = "请替换为长随机值"
+aiserver run app:server --host 0.0.0.0
+```
+
+客户端通过以下任一种请求头提交令牌：
+
+```text
+Authorization: Bearer <token>
+X-API-Key: <token>
+```
+
+令牌不要写进源码、命令行参数或公开日志。需要通过互联网访问时，应在前面部署带
+TLS 的反向代理。
+
+## 当前边界
+
+- 单进程运行，便于多个任务共享同一个内存模型。
+- 异步任务记录只保存在内存，程序重启后不会保留。
+- 超时可以停止等待异步函数，但无法强制终止已经在线程中运行的同步模型代码。
+- 不负责下载模型、转换模型协议、分布式调度或云端管理。
+
+## 旧版本说明
+
+`0.1.0` 是完全重写版本，不兼容历史 `0.0.x` 中的远程聊天和机器人演示接口。旧版本
+不应继续使用。

aiserver-0.1.0/examples/__init__.py

@@ -0,0 +1 @@
+"""Runnable AIserver examples."""

aiserver-0.1.0/examples/basic.py

@@ -0,0 +1,26 @@
+"""Run with: aiserver run examples.basic:server"""
+
+from __future__ import annotations
+
+import time
+
+from aiserver import AIServer, TaskContext
+
+server = AIServer("AIserver example")
+
+
+@server.task(concurrency=4, timeout=10)
+def add(a: float, b: float) -> dict[str, float]:
+    """Add two numbers."""
+
+    return {"value": a + b}
+
+
+@server.task(concurrency=1, timeout=30)
+def simulated_inference(text: str, context: TaskContext) -> dict[str, str]:
+    """Demonstrate a long-running, concurrency-limited inference job."""
+
+    for step in range(5):
+        time.sleep(0.2)
+        context.report((step + 1) / 5, f"step {step + 1} of 5")
+    return {"output": text.upper()}