pyyapi 0.1.0__py3-none-any.whl

pyyapi-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyyapi-0.1.0.dist-info/licenses/LICENSE,sha256=do6SIX12qLn8oPKQradS4jQ1Et8t0dIMrOgzzIW-raU,1060
+yapi/__init__.py,sha256=ej4HIY4qTJaPPg4cuMdQDJAMWGJ-wmc1racmFqlHjgY,65
+yapi/agent.py,sha256=WHe2YMqF1kVZMttn8QY7frFyDH_tV1Jh0gXCtQ1NO8U,1151
+yapi/endpoint.py,sha256=xsQHbMhQUFQOhlUbLymVVGPb-RO8dW3jZx2pnrYTMq8,394
+yapi/errors.py,sha256=rcmfyO6Qhh8G0FfUBAtV5unBiTAsf7ZloIMY9QIiNfE,183
+yapi/models.py,sha256=PXutepPXwoKlZFg6u1Ka4yVF5C0rR3nt1lmw36kJySM,142
+yapi/router.py,sha256=MVrZU66Qt3HViwBap6LyS82ahJFPWtk581KgB3v8Ijs,5368
+yapi/runtime.py,sha256=8LEqP1VsXaAPVmlvExHsruXWQ-3WUzr0oOYQBnOmd6c,1949
+pyyapi-0.1.0.dist-info/METADATA,sha256=FM9lt8l5j5I2GZssOm_3z40xNokQDpQ6XRbHh8j_vNM,5455
+pyyapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pyyapi-0.1.0.dist-info/top_level.txt,sha256=9CRrEew74JkNhm0PcYmHznjQ2F8xI4_Rkys48bjxl6U,5
+pyyapi-0.1.0.dist-info/RECORD,,

pyyapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyyapi-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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

yapi/__init__.py

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

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

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()

yapi/errors.py

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

yapi/models.py

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

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)

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)