pyyapi 0.1.0__tar.gz

pyyapi-0.1.0/LICENSE

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

pyyapi-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: pyyapi
+Version: 0.1.0
+Summary: Prompt-first declarative HTTP framework on top of FastAPI and PydanticAI
+Author-email: DJJ <shuaiqijianhao@qq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/TokenRollAI/yapi
+Project-URL: Repository, https://github.com/TokenRollAI/yapi
+Project-URL: Issues, https://github.com/TokenRollAI/yapi/issues
+Keywords: fastapi,pydantic,pydantic-ai,llm,prompt,http,framework,declarative
+Classifier: Development Status :: 3 - Alpha
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pydantic-ai<1,>=0.0.18
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx<1,>=0.27; extra == "dev"
+Requires-Dist: pytest<9,>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
+Dynamic: license-file
+
+# yapi
+
+[![PyPI](https://img.shields.io/pypi/v/pyyapi.svg)](https://pypi.org/project/pyyapi/)
+[![Python](https://img.shields.io/pypi/pyversions/pyyapi.svg)](https://pypi.org/project/pyyapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Prompt-first declarative HTTP framework** — write a normal Python function with a docstring, get an LLM-powered HTTP endpoint with structured JSON responses.
+
+`yapi` is a thin layer on top of [FastAPI](https://fastapi.tiangolo.com/) and [PydanticAI](https://ai.pydantic.dev/). You declare an HTTP route by decorating a regular function; the framework takes the function signature, the response model's docstring, the function's docstring and any dynamic prompt it returns, composes them into a system prompt, and hands the result to a PydanticAI `Agent` to produce a validated `BaseModel` response.
+
+> Package name on PyPI is `pyyapi` (the unhyphenated `yapi` was taken by a 2018 project). Import path is still `yapi`.
+
+## Install
+
+```bash
+pip install pyyapi
+```
+
+Python 3.12+ required.
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from yapi import PromptRouter
+
+
+class WishIn(BaseModel):
+    user_id: str
+    wish: str
+
+
+class WishOut(BaseModel):
+    """You are a wish-granting entity. Decide whether to grant the wish."""
+
+    granted: bool
+    message: str
+
+
+app = FastAPI(title="yapi showcase")
+router = PromptRouter()
+
+
+@router.post("/wish")
+def make_a_wish(req: WishIn) -> WishOut:
+    """Decide whether to grant the user's wish."""
+
+
+app.include_router(router)
+```
+
+Run it:
+
+```bash
+YAPI_MODEL=test uvicorn examples.wish_api:app --reload
+```
+
+`YAPI_MODEL=test` activates PydanticAI's built-in `TestModel` — no API key, no network, perfect for offline smoke tests. For real models, set e.g. `YAPI_MODEL=openai:gpt-4o` or `YAPI_MODEL=anthropic:claude-3-5-sonnet`.
+
+Open `http://localhost:8000/docs` for the auto-generated OpenAPI UI.
+
+## How it works
+
+For each request, `yapi`:
+
+1. parses the request body into the `BaseModel` you declared as a parameter,
+2. calls your function synchronously to optionally produce a **dynamic prompt** (the function's `return` value, must be `None` or `str`),
+3. composes the final system prompt from: response-model docstring + function docstring + dynamic prompt,
+4. invokes the configured `agent_runner` (defaulting to a PydanticAI `Agent`) with the prompt + request payload,
+5. validates the agent's output against your return annotation and serializes via FastAPI.
+
+## Contract (hard rules)
+
+- `PromptRouter` subclasses `fastapi.APIRouter` and overrides `.get/.post/.put/.patch/.delete`. All routes on a `PromptRouter` are prompt routes — don't mix plain FastAPI routes onto it.
+- The decorator only accepts the path argument. FastAPI kwargs like `tags=`, `summary=`, `status_code=`, `response_class=`, `response_model=` are silently ignored.
+- Return annotation **must** be a `BaseModel` subclass.
+- At most one parameter may be a `BaseModel` (the request body). Other parameters must have `default=fastapi.Depends(...)`.
+- Function body must `return` either `None` or a `str` (the dynamic prompt). Anything else raises at request time. `async def` is not supported.
+
+Violations are raised as `YapiDeclarationError` at decoration time — broken routes fail at import, not at request time.
+
+## Dependency injection
+
+```python
+from fastapi import Depends
+
+def get_db():
+    ...
+
+@router.post("/wish")
+def make_a_wish(req: WishIn, db = Depends(get_db)) -> WishOut:
+    """..."""
+    return f"user has {db.balance(req.user_id)} wishes left"
+```
+
+## Custom agent runner
+
+`PromptRouter(agent_runner=...)` accepts any callable with the signature `(*, prompt, request, injected, response_model) -> dict`. Useful for tests:
+
+```python
+router = PromptRouter(
+    agent_runner=lambda **_: {"granted": True, "message": "ok"},
+)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run uvicorn examples.wish_api:app --reload
+```
+
+## License
+
+MIT

pyyapi-0.1.0/README.md

@@ -0,0 +1,118 @@
+# yapi
+
+[![PyPI](https://img.shields.io/pypi/v/pyyapi.svg)](https://pypi.org/project/pyyapi/)
+[![Python](https://img.shields.io/pypi/pyversions/pyyapi.svg)](https://pypi.org/project/pyyapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Prompt-first declarative HTTP framework** — write a normal Python function with a docstring, get an LLM-powered HTTP endpoint with structured JSON responses.
+
+`yapi` is a thin layer on top of [FastAPI](https://fastapi.tiangolo.com/) and [PydanticAI](https://ai.pydantic.dev/). You declare an HTTP route by decorating a regular function; the framework takes the function signature, the response model's docstring, the function's docstring and any dynamic prompt it returns, composes them into a system prompt, and hands the result to a PydanticAI `Agent` to produce a validated `BaseModel` response.
+
+> Package name on PyPI is `pyyapi` (the unhyphenated `yapi` was taken by a 2018 project). Import path is still `yapi`.
+
+## Install
+
+```bash
+pip install pyyapi
+```
+
+Python 3.12+ required.
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from yapi import PromptRouter
+
+
+class WishIn(BaseModel):
+    user_id: str
+    wish: str
+
+
+class WishOut(BaseModel):
+    """You are a wish-granting entity. Decide whether to grant the wish."""
+
+    granted: bool
+    message: str
+
+
+app = FastAPI(title="yapi showcase")
+router = PromptRouter()
+
+
+@router.post("/wish")
+def make_a_wish(req: WishIn) -> WishOut:
+    """Decide whether to grant the user's wish."""
+
+
+app.include_router(router)
+```
+
+Run it:
+
+```bash
+YAPI_MODEL=test uvicorn examples.wish_api:app --reload
+```
+
+`YAPI_MODEL=test` activates PydanticAI's built-in `TestModel` — no API key, no network, perfect for offline smoke tests. For real models, set e.g. `YAPI_MODEL=openai:gpt-4o` or `YAPI_MODEL=anthropic:claude-3-5-sonnet`.
+
+Open `http://localhost:8000/docs` for the auto-generated OpenAPI UI.
+
+## How it works
+
+For each request, `yapi`:
+
+1. parses the request body into the `BaseModel` you declared as a parameter,
+2. calls your function synchronously to optionally produce a **dynamic prompt** (the function's `return` value, must be `None` or `str`),
+3. composes the final system prompt from: response-model docstring + function docstring + dynamic prompt,
+4. invokes the configured `agent_runner` (defaulting to a PydanticAI `Agent`) with the prompt + request payload,
+5. validates the agent's output against your return annotation and serializes via FastAPI.
+
+## Contract (hard rules)
+
+- `PromptRouter` subclasses `fastapi.APIRouter` and overrides `.get/.post/.put/.patch/.delete`. All routes on a `PromptRouter` are prompt routes — don't mix plain FastAPI routes onto it.
+- The decorator only accepts the path argument. FastAPI kwargs like `tags=`, `summary=`, `status_code=`, `response_class=`, `response_model=` are silently ignored.
+- Return annotation **must** be a `BaseModel` subclass.
+- At most one parameter may be a `BaseModel` (the request body). Other parameters must have `default=fastapi.Depends(...)`.
+- Function body must `return` either `None` or a `str` (the dynamic prompt). Anything else raises at request time. `async def` is not supported.
+
+Violations are raised as `YapiDeclarationError` at decoration time — broken routes fail at import, not at request time.
+
+## Dependency injection
+
+```python
+from fastapi import Depends
+
+def get_db():
+    ...
+
+@router.post("/wish")
+def make_a_wish(req: WishIn, db = Depends(get_db)) -> WishOut:
+    """..."""
+    return f"user has {db.balance(req.user_id)} wishes left"
+```
+
+## Custom agent runner
+
+`PromptRouter(agent_runner=...)` accepts any callable with the signature `(*, prompt, request, injected, response_model) -> dict`. Useful for tests:
+
+```python
+router = PromptRouter(
+    agent_runner=lambda **_: {"granted": True, "message": "ok"},
+)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run uvicorn examples.wish_api:app --reload
+```
+
+## License
+
+MIT

pyyapi-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyyapi"
+version = "0.1.0"
+description = "Prompt-first declarative HTTP framework on top of FastAPI and PydanticAI"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [
+  { name = "DJJ", email = "shuaiqijianhao@qq.com" },
+]
+keywords = ["fastapi", "pydantic", "pydantic-ai", "llm", "prompt", "http", "framework", "declarative"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: FastAPI",
+  "Framework :: Pydantic",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+  "Typing :: Typed",
+]
+dependencies = [
+  "fastapi>=0.115,<1",
+  "pydantic>=2.7,<3",
+  "pydantic-ai>=0.0.18,<1",
+  "uvicorn>=0.30,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "httpx>=0.27,<1",
+  "pytest>=8.2,<9",
+  "pytest-asyncio>=0.23,<1",
+]
+
+[project.urls]
+Homepage = "https://github.com/TokenRollAI/yapi"
+Repository = "https://github.com/TokenRollAI/yapi"
+Issues = "https://github.com/TokenRollAI/yapi/issues"
+
+[tool.setuptools.packages.find]
+include = ["yapi*"]
+exclude = ["tests*", "examples*", "docs*", "llmdoc*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

pyyapi-0.1.0/pyyapi.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: pyyapi
+Version: 0.1.0
+Summary: Prompt-first declarative HTTP framework on top of FastAPI and PydanticAI
+Author-email: DJJ <shuaiqijianhao@qq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/TokenRollAI/yapi
+Project-URL: Repository, https://github.com/TokenRollAI/yapi
+Project-URL: Issues, https://github.com/TokenRollAI/yapi/issues
+Keywords: fastapi,pydantic,pydantic-ai,llm,prompt,http,framework,declarative
+Classifier: Development Status :: 3 - Alpha
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pydantic-ai<1,>=0.0.18
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx<1,>=0.27; extra == "dev"
+Requires-Dist: pytest<9,>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
+Dynamic: license-file
+
+# yapi
+
+[![PyPI](https://img.shields.io/pypi/v/pyyapi.svg)](https://pypi.org/project/pyyapi/)
+[![Python](https://img.shields.io/pypi/pyversions/pyyapi.svg)](https://pypi.org/project/pyyapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Prompt-first declarative HTTP framework** — write a normal Python function with a docstring, get an LLM-powered HTTP endpoint with structured JSON responses.
+
+`yapi` is a thin layer on top of [FastAPI](https://fastapi.tiangolo.com/) and [PydanticAI](https://ai.pydantic.dev/). You declare an HTTP route by decorating a regular function; the framework takes the function signature, the response model's docstring, the function's docstring and any dynamic prompt it returns, composes them into a system prompt, and hands the result to a PydanticAI `Agent` to produce a validated `BaseModel` response.
+
+> Package name on PyPI is `pyyapi` (the unhyphenated `yapi` was taken by a 2018 project). Import path is still `yapi`.
+
+## Install
+
+```bash
+pip install pyyapi
+```
+
+Python 3.12+ required.
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from yapi import PromptRouter
+
+
+class WishIn(BaseModel):
+    user_id: str
+    wish: str
+
+
+class WishOut(BaseModel):
+    """You are a wish-granting entity. Decide whether to grant the wish."""
+
+    granted: bool
+    message: str
+
+
+app = FastAPI(title="yapi showcase")
+router = PromptRouter()
+
+
+@router.post("/wish")
+def make_a_wish(req: WishIn) -> WishOut:
+    """Decide whether to grant the user's wish."""
+
+
+app.include_router(router)
+```
+
+Run it:
+
+```bash
+YAPI_MODEL=test uvicorn examples.wish_api:app --reload
+```
+
+`YAPI_MODEL=test` activates PydanticAI's built-in `TestModel` — no API key, no network, perfect for offline smoke tests. For real models, set e.g. `YAPI_MODEL=openai:gpt-4o` or `YAPI_MODEL=anthropic:claude-3-5-sonnet`.
+
+Open `http://localhost:8000/docs` for the auto-generated OpenAPI UI.
+
+## How it works
+
+For each request, `yapi`:
+
+1. parses the request body into the `BaseModel` you declared as a parameter,
+2. calls your function synchronously to optionally produce a **dynamic prompt** (the function's `return` value, must be `None` or `str`),
+3. composes the final system prompt from: response-model docstring + function docstring + dynamic prompt,
+4. invokes the configured `agent_runner` (defaulting to a PydanticAI `Agent`) with the prompt + request payload,
+5. validates the agent's output against your return annotation and serializes via FastAPI.
+
+## Contract (hard rules)
+
+- `PromptRouter` subclasses `fastapi.APIRouter` and overrides `.get/.post/.put/.patch/.delete`. All routes on a `PromptRouter` are prompt routes — don't mix plain FastAPI routes onto it.
+- The decorator only accepts the path argument. FastAPI kwargs like `tags=`, `summary=`, `status_code=`, `response_class=`, `response_model=` are silently ignored.
+- Return annotation **must** be a `BaseModel` subclass.
+- At most one parameter may be a `BaseModel` (the request body). Other parameters must have `default=fastapi.Depends(...)`.
+- Function body must `return` either `None` or a `str` (the dynamic prompt). Anything else raises at request time. `async def` is not supported.
+
+Violations are raised as `YapiDeclarationError` at decoration time — broken routes fail at import, not at request time.
+
+## Dependency injection
+
+```python
+from fastapi import Depends
+
+def get_db():
+    ...
+
+@router.post("/wish")
+def make_a_wish(req: WishIn, db = Depends(get_db)) -> WishOut:
+    """..."""
+    return f"user has {db.balance(req.user_id)} wishes left"
+```
+
+## Custom agent runner
+
+`PromptRouter(agent_runner=...)` accepts any callable with the signature `(*, prompt, request, injected, response_model) -> dict`. Useful for tests:
+
+```python
+router = PromptRouter(
+    agent_runner=lambda **_: {"granted": True, "message": "ok"},
+)
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run uvicorn examples.wish_api:app --reload
+```
+
+## License
+
+MIT

pyyapi-0.1.0/pyyapi.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+pyyapi.egg-info/PKG-INFO
+pyyapi.egg-info/SOURCES.txt
+pyyapi.egg-info/dependency_links.txt
+pyyapi.egg-info/requires.txt
+pyyapi.egg-info/top_level.txt
+tests/test_exports.py
+tests/test_integration.py
+tests/test_router.py
+tests/test_runtime.py
+yapi/__init__.py
+yapi/agent.py
+yapi/endpoint.py
+yapi/errors.py
+yapi/models.py
+yapi/router.py
+yapi/runtime.py

pyyapi-0.1.0/pyyapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyyapi-0.1.0/pyyapi.egg-info/requires.txt

@@ -0,0 +1,9 @@
+fastapi<1,>=0.115
+pydantic<3,>=2.7
+pydantic-ai<1,>=0.0.18
+uvicorn<1,>=0.30
+
+[dev]
+httpx<1,>=0.27
+pytest<9,>=8.2
+pytest-asyncio<1,>=0.23

pyyapi-0.1.0/pyyapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+yapi

pyyapi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyyapi-0.1.0/tests/test_exports.py

@@ -0,0 +1,5 @@
+from yapi import PromptRouter
+
+
+def test_public_exports_are_available() -> None:
+    assert PromptRouter is not None

pyyapi-0.1.0/tests/test_integration.py

@@ -0,0 +1,89 @@
+from fastapi import Depends, FastAPI
+from fastapi.testclient import TestClient
+from pydantic import BaseModel
+
+from yapi import PromptRouter
+
+
+class WishRequest(BaseModel):
+    user_id: str
+    wish: str
+
+
+class WishResponse(BaseModel):
+    """你是一个愿望受理实体。"""
+
+    granted: bool
+    message: str
+
+
+def test_dependency_injection_flows_into_runtime() -> None:
+    app = FastAPI()
+
+    def fake_agent_runner(**kwargs):
+        injected = kwargs["injected"]
+        return {
+            "granted": injected["profile"]["vip"],
+            "message": "vip granted",
+        }
+
+    router = PromptRouter(agent_runner=fake_agent_runner)
+
+    def fetch_profile(req: WishRequest) -> dict:
+        return {"vip": req.user_id == "u-1"}
+
+    @router.post("/wish")
+    def make_a_wish(
+        req: WishRequest,
+        profile: dict = Depends(fetch_profile),
+    ) -> WishResponse:
+        """grant wishes"""
+
+    app.include_router(router)
+    client = TestClient(app)
+
+    response = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
+
+    assert response.status_code == 200
+    assert response.json() == {"granted": True, "message": "vip granted"}
+
+
+def test_dynamic_prompt_returned_by_handler_reaches_agent_runner() -> None:
+    captured = {}
+    app = FastAPI()
+
+    def fake_agent_runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    router = PromptRouter(agent_runner=fake_agent_runner)
+
+    @router.post("/wish")
+    def make_a_wish(req: WishRequest) -> WishResponse:
+        """grant wishes"""
+        return f"focus on user {req.user_id}'s mood: {req.wish}"
+
+    app.include_router(router)
+    client = TestClient(app)
+
+    response = client.post("/wish", json={"user_id": "u-1", "wish": "stars"})
+
+    assert response.status_code == 200
+    assert "focus on user u-1's mood: stars" in captured["prompt"]
+
+
+def test_handler_returning_non_string_raises_runtime_error() -> None:
+    app = FastAPI()
+    router = PromptRouter(agent_runner=lambda **_: {"granted": True, "message": "ok"})
+
+    @router.post("/wish")
+    def make_a_wish(req: WishRequest) -> WishResponse:
+        """grant wishes"""
+        return 42
+
+    app.include_router(router)
+    client = TestClient(app, raise_server_exceptions=False)
+
+    response = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
+
+    assert response.status_code == 500

pyyapi-0.1.0/tests/test_router.py

@@ -0,0 +1,106 @@
+import pytest
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+from yapi import PromptRouter
+from yapi.errors import YapiDeclarationError
+
+
+class WishRequest(BaseModel):
+    user_id: str
+    wish: str
+
+
+class WishResponse(BaseModel):
+    """你是一个愿望受理实体。"""
+
+    granted: bool
+    message: str
+
+
+def test_router_post_registers_route_with_inferred_models() -> None:
+    app = FastAPI()
+    router = PromptRouter(agent_runner=lambda **_: {"granted": True, "message": "ok"})
+
+    @router.post("/wish")
+    def make_a_wish(req: WishRequest) -> WishResponse:
+        """grant wishes"""
+
+    app.include_router(router)
+
+    paths = {(route.path, tuple(route.methods)) for route in app.routes}
+    assert ("/wish", ("POST",)) in paths
+
+
+def test_router_post_emits_openapi_with_declared_models() -> None:
+    app = FastAPI()
+    router = PromptRouter(agent_runner=lambda **_: {"granted": True, "message": "ok"})
+
+    @router.post("/wish")
+    def make_a_wish(req: WishRequest) -> WishResponse:
+        """grant wishes"""
+
+    app.include_router(router)
+    schema = app.openapi()
+
+    operation = schema["paths"]["/wish"]["post"]
+    assert operation["requestBody"] is not None
+    assert operation["responses"]["200"] is not None
+
+
+def test_router_post_requires_response_annotation() -> None:
+    router = PromptRouter(agent_runner=lambda **_: {"granted": True, "message": "ok"})
+
+    with pytest.raises(YapiDeclarationError):
+
+        @router.post("/wish")
+        def make_a_wish(req: WishRequest):
+            """grant wishes"""
+
+
+def test_router_post_rejects_non_basemodel_response() -> None:
+    router = PromptRouter(agent_runner=lambda **_: {"granted": True, "message": "ok"})
+
+    with pytest.raises(YapiDeclarationError):
+
+        @router.post("/wish")
+        def make_a_wish(req: WishRequest) -> dict:
+            """grant wishes"""
+
+
+def test_router_post_rejects_multiple_basemodel_params() -> None:
+    class Extra(BaseModel):
+        flag: bool
+
+    router = PromptRouter(agent_runner=lambda **_: {"granted": True, "message": "ok"})
+
+    with pytest.raises(YapiDeclarationError):
+
+        @router.post("/wish")
+        def make_a_wish(req: WishRequest, extra: Extra) -> WishResponse:
+            """grant wishes"""
+
+
+def test_router_supports_get_with_no_request_body() -> None:
+    app = FastAPI()
+    router = PromptRouter(agent_runner=lambda **_: {"message": "ok"})
+
+    class StatusOut(BaseModel):
+        """describe the system."""
+
+        message: str
+
+    @router.get("/status")
+    def status() -> StatusOut:
+        """return current status."""
+
+    app.include_router(router)
+
+    paths = {(route.path, tuple(route.methods)) for route in app.routes}
+    assert ("/status", ("GET",)) in paths
+
+
+def test_example_application_imports() -> None:
+    from examples.wish_api import app
+
+    assert app is not None

pyyapi-0.1.0/tests/test_runtime.py

@@ -0,0 +1,97 @@
+from pydantic import BaseModel
+
+from yapi.endpoint import PromptEndpoint
+from yapi.models import RuntimeContext
+from yapi.runtime import Runtime
+
+
+class WishRequest(BaseModel):
+    user_id: str
+    wish: str
+
+
+class WishResponse(BaseModel):
+    """你是一个愿望受理实体。"""
+
+    granted: bool
+    message: str
+
+
+def test_prompt_endpoint_stores_definition() -> None:
+    endpoint = PromptEndpoint(
+        path="/wish",
+        method="POST",
+        request_model=WishRequest,
+        response_model=WishResponse,
+        function_doc="grant wishes",
+    )
+
+    assert endpoint.path == "/wish"
+    assert endpoint.method == "POST"
+    assert endpoint.request_model is WishRequest
+    assert endpoint.response_model is WishResponse
+    assert endpoint.function_doc == "grant wishes"
+
+
+def test_runtime_builds_context_sections() -> None:
+    runtime = Runtime(agent_runner=lambda **_: {"granted": True, "message": "ok"})
+
+    context = runtime.build_context(
+        request_data={"user_id": "u-1", "wish": "moon"},
+        injected={"profile": {"vip": True}},
+    )
+
+    assert context.request == {"user_id": "u-1", "wish": "moon"}
+    assert context.injected == {"profile": {"vip": True}}
+
+
+def test_runtime_executes_agent_and_returns_response_model() -> None:
+    endpoint = PromptEndpoint(
+        path="/wish",
+        method="POST",
+        request_model=WishRequest,
+        response_model=WishResponse,
+        function_doc="grant wishes",
+    )
+
+    runtime = Runtime(
+        agent_runner=lambda **_: {"granted": True, "message": "granted"},
+    )
+
+    response = runtime.execute(
+        endpoint=endpoint,
+        request_model=WishRequest(user_id="u-1", wish="moon"),
+        injected={"profile": {"vip": True}},
+        dynamic_prompt=None,
+    )
+
+    assert response.model_dump() == {"granted": True, "message": "granted"}
+
+
+def test_runtime_sends_composed_prompt_to_agent_runner() -> None:
+    captured = {}
+    endpoint = PromptEndpoint(
+        path="/wish",
+        method="POST",
+        request_model=WishRequest,
+        response_model=WishResponse,
+        function_doc="grant wishes based on context",
+    )
+
+    def fake_agent_runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    runtime = Runtime(agent_runner=fake_agent_runner)
+    runtime.execute(
+        endpoint=endpoint,
+        request_model=WishRequest(user_id="u-1", wish="moon"),
+        injected={"profile": {"vip": True}},
+        dynamic_prompt="user is shouting",
+    )
+
+    assert "你是一个愿望受理实体。" in captured["prompt"]
+    assert "grant wishes based on context" in captured["prompt"]
+    assert "user is shouting" in captured["prompt"]
+    assert captured["request"] == {"user_id": "u-1", "wish": "moon"}
+    assert captured["injected"] == {"profile": {"vip": True}}

pyyapi-0.1.0/yapi/__init__.py

@@ -0,0 +1,3 @@
+from yapi.router import PromptRouter
+
+__all__ = ["PromptRouter"]

pyyapi-0.1.0/yapi/agent.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+
+from pydantic import BaseModel
+from pydantic_ai import Agent
+
+
+DEFAULT_SYSTEM_PREFIX = (
+    "You are the execution engine behind a declarative HTTP endpoint. "
+    "Return data that matches the required response model exactly."
+)
+
+
+def build_agent_runner(model: str | None = None) -> Callable[..., dict]:
+    configured_model = model or os.getenv("YAPI_MODEL")
+
+    def runner(
+        *,
+        prompt: str,
+        request: dict,
+        injected: dict,
+        response_model: type[BaseModel],
+    ) -> dict:
+        if configured_model is None:
+            raise NotImplementedError("Connect pydantic_ai.Agent by setting YAPI_MODEL")
+
+        agent = Agent(
+            configured_model,
+            output_type=response_model,
+            system_prompt=prompt,
+        )
+
+        user_prompt = f"request={request}\ninjected={injected}"
+        result = agent.run_sync(user_prompt)
+        output = getattr(result, "output", result)
+        if hasattr(output, "model_dump"):
+            return output.model_dump()
+        return dict(output)
+
+    return runner

pyyapi-0.1.0/yapi/endpoint.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+
+@dataclass(frozen=True)
+class PromptEndpoint:
+    path: str
+    method: str
+    request_model: type[BaseModel] | None
+    response_model: type[BaseModel]
+    function_doc: str = ""
+
+    @property
+    def response_doc(self) -> str:
+        return (self.response_model.__doc__ or "").strip()

pyyapi-0.1.0/yapi/errors.py

@@ -0,0 +1,14 @@
+class YapiError(Exception):
+    pass
+
+
+class YapiDeclarationError(YapiError):
+    pass
+
+
+class StateStoreError(YapiError):
+    pass
+
+
+class RuntimeExecutionError(YapiError):
+    pass

pyyapi-0.1.0/yapi/models.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RuntimeContext:
+    request: dict
+    injected: dict

pyyapi-0.1.0/yapi/router.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+
+from fastapi import APIRouter, params
+from fastapi.concurrency import run_in_threadpool
+from pydantic import BaseModel
+
+from yapi.agent import build_agent_runner
+from yapi.endpoint import PromptEndpoint
+from yapi.errors import RuntimeExecutionError, YapiDeclarationError
+from yapi.runtime import Runtime
+
+_HTTP_METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE")
+
+
+def _introspect(func: Callable) -> tuple[type[BaseModel] | None, type[BaseModel], list[tuple[str, inspect.Parameter]]]:
+    signature = inspect.signature(func)
+
+    return_annotation = signature.return_annotation
+    if return_annotation is inspect.Signature.empty:
+        raise YapiDeclarationError(
+            f"yapi route handler '{func.__name__}' must declare a return type annotation"
+        )
+    if not (isinstance(return_annotation, type) and issubclass(return_annotation, BaseModel)):
+        raise YapiDeclarationError(
+            f"yapi route handler '{func.__name__}' must return a Pydantic BaseModel subclass"
+        )
+
+    request_model: type[BaseModel] | None = None
+    dependency_params: list[tuple[str, inspect.Parameter]] = []
+
+    for name, param in signature.parameters.items():
+        annotation = param.annotation
+        default = param.default
+
+        if isinstance(default, params.Depends):
+            dependency_params.append((name, param))
+            continue
+
+        if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+            if request_model is not None:
+                raise YapiDeclarationError(
+                    f"yapi route handler '{func.__name__}' may declare at most one Pydantic request model parameter"
+                )
+            request_model = annotation
+            continue
+
+        raise YapiDeclarationError(
+            f"yapi route handler '{func.__name__}' has parameter '{name}' that is neither a Pydantic model nor a Depends() dependency"
+        )
+
+    return request_model, return_annotation, dependency_params
+
+
+class PromptRouter(APIRouter):
+    def __init__(self, agent_runner: Callable[..., dict] | None = None) -> None:
+        super().__init__()
+        self._runtime = Runtime(agent_runner=agent_runner or build_agent_runner())
+
+    def _register(self, method: str, path: str) -> Callable[[Callable], Callable]:
+        upper = method.upper()
+        if upper not in _HTTP_METHODS:
+            raise YapiDeclarationError(f"Unsupported HTTP method: {method}")
+
+        def decorator(func: Callable) -> Callable:
+            request_model, response_model, dependency_params = _introspect(func)
+            endpoint = PromptEndpoint(
+                path=path,
+                method=upper,
+                request_model=request_model,
+                response_model=response_model,
+                function_doc=(func.__doc__ or "").strip(),
+            )
+
+            handler_params: list[inspect.Parameter] = []
+            request_param_name: str | None = None
+            for name, param in inspect.signature(func).parameters.items():
+                handler_params.append(param)
+                if isinstance(param.default, params.Depends):
+                    continue
+                if isinstance(param.annotation, type) and issubclass(param.annotation, BaseModel):
+                    request_param_name = name
+
+            async def handler(**kwargs):
+                injected = {
+                    name: kwargs[name] for name, _ in dependency_params if name in kwargs
+                }
+                request_instance = (
+                    kwargs.get(request_param_name) if request_param_name is not None else None
+                )
+
+                dynamic_prompt = func(**kwargs)
+                if dynamic_prompt is not None and not isinstance(dynamic_prompt, str):
+                    raise RuntimeExecutionError(
+                        f"yapi route handler '{func.__name__}' must return None or str, "
+                        f"got {type(dynamic_prompt).__name__}"
+                    )
+
+                return await run_in_threadpool(
+                    self._runtime.execute,
+                    endpoint=endpoint,
+                    request_model=request_instance,
+                    injected=injected,
+                    dynamic_prompt=dynamic_prompt,
+                )
+
+            handler.__signature__ = inspect.Signature(parameters=handler_params, return_annotation=response_model)
+            handler.__annotations__ = {p.name: p.annotation for p in handler_params if p.annotation is not inspect.Parameter.empty}
+            handler.__annotations__["return"] = response_model
+            handler.__name__ = func.__name__
+
+            self.add_api_route(
+                path,
+                handler,
+                methods=[upper],
+                response_model=response_model,
+            )
+            return func
+
+        return decorator
+
+    def get(self, path: str, **_unused):
+        return self._register("GET", path)
+
+    def post(self, path: str, **_unused):
+        return self._register("POST", path)
+
+    def put(self, path: str, **_unused):
+        return self._register("PUT", path)
+
+    def patch(self, path: str, **_unused):
+        return self._register("PATCH", path)
+
+    def delete(self, path: str, **_unused):
+        return self._register("DELETE", path)

pyyapi-0.1.0/yapi/runtime.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pydantic import BaseModel
+
+from yapi.endpoint import PromptEndpoint
+from yapi.errors import RuntimeExecutionError
+from yapi.models import RuntimeContext
+
+DEFAULT_SYSTEM_PREFIX = (
+    "You are the execution engine behind a declarative HTTP endpoint. "
+    "Return data that strictly matches the required response model."
+)
+
+
+def compose_prompt(endpoint: PromptEndpoint, dynamic_prompt: str | None) -> str:
+    sections = [DEFAULT_SYSTEM_PREFIX]
+    response_doc = endpoint.response_doc
+    if response_doc:
+        sections.append(response_doc)
+    if endpoint.function_doc:
+        sections.append(endpoint.function_doc)
+    if dynamic_prompt:
+        sections.append(dynamic_prompt)
+    return "\n\n".join(sections)
+
+
+class Runtime:
+    def __init__(self, agent_runner: Callable[..., dict]) -> None:
+        self._agent_runner = agent_runner
+
+    def build_context(self, request_data: dict, injected: dict) -> RuntimeContext:
+        return RuntimeContext(
+            request=dict(request_data),
+            injected=dict(injected),
+        )
+
+    def execute(
+        self,
+        endpoint: PromptEndpoint,
+        request_model: BaseModel | None,
+        injected: dict,
+        dynamic_prompt: str | None,
+    ) -> BaseModel:
+        request_data = {} if request_model is None else request_model.model_dump()
+        context = self.build_context(request_data=request_data, injected=injected)
+        prompt = compose_prompt(endpoint, dynamic_prompt)
+
+        try:
+            payload = self._agent_runner(
+                prompt=prompt,
+                request=context.request,
+                injected=context.injected,
+                response_model=endpoint.response_model,
+            )
+        except Exception as exc:
+            raise RuntimeExecutionError("Agent execution failed") from exc
+
+        return endpoint.response_model.model_validate(payload)