pyyapi 0.2.0__tar.gz → 0.3.0__tar.gz

{pyyapi-0.2.0/pyyapi.egg-info → pyyapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyyapi
-Version: 0.2.0
+Version: 0.3.0
 Summary: Prompt-first declarative HTTP framework on top of FastAPI and PydanticAI
 Author-email: DJJ <shuaiqijianhao@qq.com>
 License: MIT
@@ -133,6 +133,8 @@ YAPI_MODEL=test                        # PydanticAI TestModel, no key, no networ
 
 Unset → constructor emits a `YapiUsageWarning`, first request returns HTTP 500.
 
+> ⚠️ **The model must support OpenAI Function Calling's `tool_choice` parameter.** `yapi` relies on PydanticAI's structured-output path, which forces the model to emit a tool call matching your response `BaseModel`. Models that lack `tool_choice` support — most notably "reasoning / thinking" variants such as `deepseek-reasoner`, `deepseek-v4-flash`, `o1-preview` / `o1-mini`, or any chat-only / completion-only checkpoint — will return HTTP 500 with a `ModelHTTPError` at the first request. Pick a model whose API docs explicitly support function calling (`gpt-4o`, `gpt-4o-mini`, `claude-3-5-sonnet`, `deepseek-chat`, …).
+
 ### Provider credentials (read directly by PydanticAI)
 
 `yapi` does **not** validate or even look at these — they are consumed by the underlying PydanticAI provider via `os.environ`:
@@ -156,7 +158,7 @@ OPENAI_BASE_URL=https://api.deepseek.com/v1
 uv run uvicorn examples.wish_api:app --reload --env-file .env
 ```
 
-> DeepSeek's "thinking" models (`deepseek-reasoner`, `deepseek-v4-flash`) currently reject OpenAI Function Calling's `tool_choice` parameter, which PydanticAI uses by default for structured output. Use `deepseek-chat` for now.
+> Same caveat as the warning above: DeepSeek's "thinking" models (`deepseek-reasoner`, `deepseek-v4-flash`) reject `tool_choice` and won't work here. Use `deepseek-chat`.
 
 ## How a prompt route runs
 
@@ -189,6 +191,55 @@ Decoration kwargs:
 
 Violations are raised as `YapiDeclarationError` at decoration time — broken routes fail at import, not at request time.
 
+## Prompt context
+
+Use `PromptContext` to inject structured facts into the system prompt without returning a string. Declare a parameter typed `PromptContext` and `yapi` auto-injects a per-request instance:
+
+```python
+from yapi import PromptContext, PromptRouter
+
+router = PromptRouter()
+
+
+@router.prompt.post("/wish")
+def make_a_wish(req: WishIn, ctx: PromptContext) -> WishOut:
+    """Decide whether to grant the user's wish."""
+    ctx.add_section("User Profile", {"vip": req.user_id.startswith("vip-")})
+    ctx.add_kv("user_id", req.user_id)
+    ctx.add(req.wish)
+```
+
+`yapi` collects all segments and wraps them in `<context>…</context>` at the end of the system prompt:
+
+```
+You are the execution engine…
+
+Decide whether to grant the user's wish.
+
+<context>
+# User Profile
+{"vip": true}
+
+user_id: vip-1
+
+moon
+</context>
+```
+
+Three methods:
+
+| Method | Produces |
+|---|---|
+| `ctx.add(value)` | `<serialized value>` |
+| `ctx.add_kv(key, value)` | `{key}: <serialized value>` |
+| `ctx.add_section(name, body)` | `# {name}\n<serialized body>` |
+
+Value serialization: `str` → pass-through; `BaseModel` → `model_dump_json()`; `dict`/`list`/`tuple` → `json.dumps(..., ensure_ascii=False)`; anything else → `str()`. `None` is rejected — use `""` if you want an empty segment.
+
+`PromptContext` is **append-only** — no `clear` / `pop`. Use Python `if` for conditional adds. At most one `PromptContext` parameter per route; the parameter must not carry FastAPI markers (`Annotated[PromptContext, Body()/Query()/Depends()]` is a declaration error).
+
+State retrieval is out of scope for `yapi`. Fetch your data via `Depends(...)` and pass it to `ctx.*`. See `examples/state_via_depends.py`.
+
 ## Dependency injection
 
 ```python

{pyyapi-0.2.0 → pyyapi-0.3.0}/README.md

@@ -98,6 +98,8 @@ YAPI_MODEL=test                        # PydanticAI TestModel, no key, no networ
 
 Unset → constructor emits a `YapiUsageWarning`, first request returns HTTP 500.
 
+> ⚠️ **The model must support OpenAI Function Calling's `tool_choice` parameter.** `yapi` relies on PydanticAI's structured-output path, which forces the model to emit a tool call matching your response `BaseModel`. Models that lack `tool_choice` support — most notably "reasoning / thinking" variants such as `deepseek-reasoner`, `deepseek-v4-flash`, `o1-preview` / `o1-mini`, or any chat-only / completion-only checkpoint — will return HTTP 500 with a `ModelHTTPError` at the first request. Pick a model whose API docs explicitly support function calling (`gpt-4o`, `gpt-4o-mini`, `claude-3-5-sonnet`, `deepseek-chat`, …).
+
 ### Provider credentials (read directly by PydanticAI)
 
 `yapi` does **not** validate or even look at these — they are consumed by the underlying PydanticAI provider via `os.environ`:
@@ -121,7 +123,7 @@ OPENAI_BASE_URL=https://api.deepseek.com/v1
 uv run uvicorn examples.wish_api:app --reload --env-file .env
 ```
 
-> DeepSeek's "thinking" models (`deepseek-reasoner`, `deepseek-v4-flash`) currently reject OpenAI Function Calling's `tool_choice` parameter, which PydanticAI uses by default for structured output. Use `deepseek-chat` for now.
+> Same caveat as the warning above: DeepSeek's "thinking" models (`deepseek-reasoner`, `deepseek-v4-flash`) reject `tool_choice` and won't work here. Use `deepseek-chat`.
 
 ## How a prompt route runs
 
@@ -154,6 +156,55 @@ Decoration kwargs:
 
 Violations are raised as `YapiDeclarationError` at decoration time — broken routes fail at import, not at request time.
 
+## Prompt context
+
+Use `PromptContext` to inject structured facts into the system prompt without returning a string. Declare a parameter typed `PromptContext` and `yapi` auto-injects a per-request instance:
+
+```python
+from yapi import PromptContext, PromptRouter
+
+router = PromptRouter()
+
+
+@router.prompt.post("/wish")
+def make_a_wish(req: WishIn, ctx: PromptContext) -> WishOut:
+    """Decide whether to grant the user's wish."""
+    ctx.add_section("User Profile", {"vip": req.user_id.startswith("vip-")})
+    ctx.add_kv("user_id", req.user_id)
+    ctx.add(req.wish)
+```
+
+`yapi` collects all segments and wraps them in `<context>…</context>` at the end of the system prompt:
+
+```
+You are the execution engine…
+
+Decide whether to grant the user's wish.
+
+<context>
+# User Profile
+{"vip": true}
+
+user_id: vip-1
+
+moon
+</context>
+```
+
+Three methods:
+
+| Method | Produces |
+|---|---|
+| `ctx.add(value)` | `<serialized value>` |
+| `ctx.add_kv(key, value)` | `{key}: <serialized value>` |
+| `ctx.add_section(name, body)` | `# {name}\n<serialized body>` |
+
+Value serialization: `str` → pass-through; `BaseModel` → `model_dump_json()`; `dict`/`list`/`tuple` → `json.dumps(..., ensure_ascii=False)`; anything else → `str()`. `None` is rejected — use `""` if you want an empty segment.
+
+`PromptContext` is **append-only** — no `clear` / `pop`. Use Python `if` for conditional adds. At most one `PromptContext` parameter per route; the parameter must not carry FastAPI markers (`Annotated[PromptContext, Body()/Query()/Depends()]` is a declaration error).
+
+State retrieval is out of scope for `yapi`. Fetch your data via `Depends(...)` and pass it to `ctx.*`. See `examples/state_via_depends.py`.
+
 ## Dependency injection
 
 ```python

{pyyapi-0.2.0 → pyyapi-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyyapi"
-version = "0.2.0"
+version = "0.3.0"
 description = "Prompt-first declarative HTTP framework on top of FastAPI and PydanticAI"
 readme = "README.md"
 license = { text = "MIT" }

{pyyapi-0.2.0 → pyyapi-0.3.0/pyyapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyyapi
-Version: 0.2.0
+Version: 0.3.0
 Summary: Prompt-first declarative HTTP framework on top of FastAPI and PydanticAI
 Author-email: DJJ <shuaiqijianhao@qq.com>
 License: MIT
@@ -133,6 +133,8 @@ YAPI_MODEL=test                        # PydanticAI TestModel, no key, no networ
 
 Unset → constructor emits a `YapiUsageWarning`, first request returns HTTP 500.
 
+> ⚠️ **The model must support OpenAI Function Calling's `tool_choice` parameter.** `yapi` relies on PydanticAI's structured-output path, which forces the model to emit a tool call matching your response `BaseModel`. Models that lack `tool_choice` support — most notably "reasoning / thinking" variants such as `deepseek-reasoner`, `deepseek-v4-flash`, `o1-preview` / `o1-mini`, or any chat-only / completion-only checkpoint — will return HTTP 500 with a `ModelHTTPError` at the first request. Pick a model whose API docs explicitly support function calling (`gpt-4o`, `gpt-4o-mini`, `claude-3-5-sonnet`, `deepseek-chat`, …).
+
 ### Provider credentials (read directly by PydanticAI)
 
 `yapi` does **not** validate or even look at these — they are consumed by the underlying PydanticAI provider via `os.environ`:
@@ -156,7 +158,7 @@ OPENAI_BASE_URL=https://api.deepseek.com/v1
 uv run uvicorn examples.wish_api:app --reload --env-file .env
 ```
 
-> DeepSeek's "thinking" models (`deepseek-reasoner`, `deepseek-v4-flash`) currently reject OpenAI Function Calling's `tool_choice` parameter, which PydanticAI uses by default for structured output. Use `deepseek-chat` for now.
+> Same caveat as the warning above: DeepSeek's "thinking" models (`deepseek-reasoner`, `deepseek-v4-flash`) reject `tool_choice` and won't work here. Use `deepseek-chat`.
 
 ## How a prompt route runs
 
@@ -189,6 +191,55 @@ Decoration kwargs:
 
 Violations are raised as `YapiDeclarationError` at decoration time — broken routes fail at import, not at request time.
 
+## Prompt context
+
+Use `PromptContext` to inject structured facts into the system prompt without returning a string. Declare a parameter typed `PromptContext` and `yapi` auto-injects a per-request instance:
+
+```python
+from yapi import PromptContext, PromptRouter
+
+router = PromptRouter()
+
+
+@router.prompt.post("/wish")
+def make_a_wish(req: WishIn, ctx: PromptContext) -> WishOut:
+    """Decide whether to grant the user's wish."""
+    ctx.add_section("User Profile", {"vip": req.user_id.startswith("vip-")})
+    ctx.add_kv("user_id", req.user_id)
+    ctx.add(req.wish)
+```
+
+`yapi` collects all segments and wraps them in `<context>…</context>` at the end of the system prompt:
+
+```
+You are the execution engine…
+
+Decide whether to grant the user's wish.
+
+<context>
+# User Profile
+{"vip": true}
+
+user_id: vip-1
+
+moon
+</context>
+```
+
+Three methods:
+
+| Method | Produces |
+|---|---|
+| `ctx.add(value)` | `<serialized value>` |
+| `ctx.add_kv(key, value)` | `{key}: <serialized value>` |
+| `ctx.add_section(name, body)` | `# {name}\n<serialized body>` |
+
+Value serialization: `str` → pass-through; `BaseModel` → `model_dump_json()`; `dict`/`list`/`tuple` → `json.dumps(..., ensure_ascii=False)`; anything else → `str()`. `None` is rejected — use `""` if you want an empty segment.
+
+`PromptContext` is **append-only** — no `clear` / `pop`. Use Python `if` for conditional adds. At most one `PromptContext` parameter per route; the parameter must not carry FastAPI markers (`Annotated[PromptContext, Body()/Query()/Depends()]` is a declaration error).
+
+State retrieval is out of scope for `yapi`. Fetch your data via `Depends(...)` and pass it to `ctx.*`. See `examples/state_via_depends.py`.
+
 ## Dependency injection
 
 ```python

{pyyapi-0.2.0 → pyyapi-0.3.0}/pyyapi.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ tests/test_compat.py
 tests/test_dx.py
 tests/test_exports.py
 tests/test_integration.py
+tests/test_prompt_context.py
 tests/test_router.py
 tests/test_runner.py
 tests/test_runtime.py
@@ -18,6 +19,7 @@ yapi/agent.py
 yapi/endpoint.py
 yapi/errors.py
 yapi/models.py
+yapi/prompt_context.py
 yapi/py.typed
 yapi/router.py
 yapi/runner.py

{pyyapi-0.2.0 → pyyapi-0.3.0}/tests/test_integration.py

@@ -87,3 +87,85 @@ def test_handler_returning_non_string_raises_runtime_error() -> None:
     response = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
 
     assert response.status_code == 500
+
+
+# ---- v2.2 PromptContext e2e ----
+
+
+from yapi import PromptContext
+
+
+def test_e2e_ctx_segments_reach_runner() -> None:
+    captured = {}
+
+    def fake_runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    app = FastAPI()
+    router = PromptRouter(agent_runner=fake_runner)
+
+    @router.prompt.post("/wish")
+    def make_a_wish(req: WishRequest, ctx: PromptContext) -> WishResponse:
+        """grant wishes"""
+        ctx.add_section("User", req.user_id)
+        ctx.add_kv("wish", req.wish)
+        ctx.add("extra hint")
+
+    app.include_router(router)
+    client = TestClient(app)
+    resp = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
+
+    assert resp.status_code == 200
+    prompt = captured["prompt"]
+    assert "<context>" in prompt
+    assert "# User" in prompt
+    assert "u-1" in prompt
+    assert "wish: moon" in prompt
+    assert "extra hint" in prompt
+
+
+def test_e2e_v21_route_with_return_str_wraps_in_context() -> None:
+    captured = {}
+
+    def fake_runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    app = FastAPI()
+    router = PromptRouter(agent_runner=fake_runner)
+
+    @router.prompt.post("/wish")
+    def make_a_wish(req: WishRequest) -> WishResponse:
+        """grant wishes"""
+        return "legacy hint string"
+
+    app.include_router(router)
+    client = TestClient(app)
+    resp = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
+
+    assert resp.status_code == 200
+    prompt = captured["prompt"]
+    assert "<context>\nlegacy hint string\n</context>" in prompt
+
+
+def test_e2e_route_with_no_ctx_and_no_return_skips_context_tag() -> None:
+    captured = {}
+
+    def fake_runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    app = FastAPI()
+    router = PromptRouter(agent_runner=fake_runner)
+
+    @router.prompt.post("/wish")
+    def make_a_wish(req: WishRequest) -> WishResponse:
+        """grant wishes"""
+
+    app.include_router(router)
+    client = TestClient(app)
+    resp = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
+
+    assert resp.status_code == 200
+    assert "<context>" not in captured["prompt"]

pyyapi-0.3.0/tests/test_prompt_context.py

@@ -0,0 +1,89 @@
+import pytest
+from pydantic import BaseModel
+
+from yapi.errors import RuntimeExecutionError
+from yapi.prompt_context import PromptContext, _format_value
+
+
+class SomeModel(BaseModel):
+    name: str
+    vip: bool
+
+
+def test_add_str_passes_through():
+    ctx = PromptContext()
+    ctx.add("hello")
+    assert ctx.segments() == ("hello",)
+
+
+def test_add_basemodel_uses_model_dump_json():
+    ctx = PromptContext()
+    model = SomeModel(name="djj", vip=True)
+    ctx.add(model)
+    import json
+    parsed = json.loads(ctx.segments()[0])
+    assert parsed == {"name": "djj", "vip": True}
+
+
+def test_add_dict_uses_json_dumps_with_ensure_ascii_false():
+    ctx = PromptContext()
+    ctx.add({"k": "中"})
+    assert ctx.segments()[0] == '{"k": "中"}'
+
+
+def test_add_list_uses_json_dumps():
+    ctx = PromptContext()
+    ctx.add([1, "中", True])
+    assert ctx.segments()[0] == '[1, "中", true]'
+
+
+def test_add_tuple_uses_json_dumps():
+    ctx = PromptContext()
+    ctx.add((1, 2))
+    assert ctx.segments()[0] == "[1, 2]"
+
+
+def test_add_other_uses_str():
+    ctx = PromptContext()
+    ctx.add(42)
+    assert ctx.segments()[0] == "42"
+
+
+def test_add_kv_format():
+    ctx = PromptContext()
+    ctx.add_kv("k", {"x": 1})
+    assert ctx.segments()[0] == 'k: {"x": 1}'
+
+
+def test_add_section_format():
+    ctx = PromptContext()
+    model = SomeModel(name="djj", vip=True)
+    ctx.add_section("Profile", model)
+    seg = ctx.segments()[0]
+    assert seg.startswith("# Profile\n")
+    import json
+    body = seg[len("# Profile\n"):]
+    parsed = json.loads(body)
+    assert parsed == {"name": "djj", "vip": True}
+
+
+def test_add_none_raises_runtime_error():
+    ctx = PromptContext()
+    with pytest.raises(RuntimeExecutionError):
+        ctx.add(None)
+
+
+def test_segments_returns_in_call_order():
+    ctx = PromptContext()
+    ctx.add("first")
+    ctx.add_kv("key", "second")
+    ctx.add_section("sec", "third")
+    segs = ctx.segments()
+    assert segs[0] == "first"
+    assert segs[1] == "key: second"
+    assert segs[2] == "# sec\nthird"
+
+
+def test_empty_segments_returns_empty_tuple():
+    ctx = PromptContext()
+    assert ctx.segments() == ()

{pyyapi-0.2.0 → pyyapi-0.3.0}/tests/test_router.py

@@ -430,3 +430,119 @@ def test_prompt_handler_signature_preserves_annotated() -> None:
     q_param = sig.parameters["q"]
     assert hasattr(req_param.annotation, "__metadata__")
     assert hasattr(q_param.annotation, "__metadata__")
+
+
+# ---- v2.2 PromptContext ----
+
+
+from yapi import PromptContext
+
+
+def test_router_injects_prompt_context_by_type() -> None:
+    captured = {}
+    app = FastAPI()
+
+    def runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    router = PromptRouter(agent_runner=runner)
+
+    @router.prompt.post("/wish")
+    def make_a_wish(req: WishRequest, ctx: PromptContext) -> WishResponse:
+        """grant wishes"""
+        ctx.add_section("User", req.user_id)
+
+    app.include_router(router)
+    client = TestClient(app)
+    resp = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
+    assert resp.status_code == 200
+    assert "<context>" in captured["prompt"]
+    assert "# User" in captured["prompt"]
+    assert "u-1" in captured["prompt"]
+
+
+def test_router_injects_prompt_context_async() -> None:
+    captured = {}
+    app = FastAPI()
+
+    def runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    router = PromptRouter(agent_runner=runner)
+
+    @router.prompt.post("/wish")
+    async def make_a_wish(req: WishRequest, ctx: PromptContext) -> WishResponse:
+        """grant wishes"""
+        ctx.add_kv("wish", req.wish)
+
+    app.include_router(router)
+    client = TestClient(app)
+    resp = client.post("/wish", json={"user_id": "u-1", "wish": "stars"})
+    assert resp.status_code == 200
+    assert "wish: stars" in captured["prompt"]
+
+
+def test_router_prompt_context_param_name_is_arbitrary() -> None:
+    captured = {}
+    app = FastAPI()
+
+    def runner(**kwargs):
+        captured.update(kwargs)
+        return {"granted": True, "message": "ok"}
+
+    router = PromptRouter(agent_runner=runner)
+
+    @router.prompt.post("/wish")
+    def make_a_wish(req: WishRequest, prompt_ctx: PromptContext) -> WishResponse:
+        """grant wishes"""
+        prompt_ctx.add("from prompt_ctx")
+
+    app.include_router(router)
+    client = TestClient(app)
+    resp = client.post("/wish", json={"user_id": "u-1", "wish": "moon"})
+    assert resp.status_code == 200
+    assert "from prompt_ctx" in captured["prompt"]
+
+
+def test_router_rejects_two_prompt_context_params() -> None:
+    router = PromptRouter(agent_runner=_ok_runner)
+
+    with pytest.raises(YapiDeclarationError, match="at most one PromptContext"):
+
+        @router.prompt.post("/wish")
+        def make_a_wish(
+            req: WishRequest,
+            ctx1: PromptContext,
+            ctx2: PromptContext,
+        ) -> WishResponse:
+            """grant wishes"""
+
+
+def test_router_rejects_prompt_context_with_fastapi_marker() -> None:
+    router = PromptRouter(agent_runner=_ok_runner)
+
+    with pytest.raises(YapiDeclarationError, match="must not carry FastAPI markers"):
+
+        @router.prompt.post("/wish")
+        def make_a_wish(
+            req: WishRequest,
+            ctx: Annotated[PromptContext, Body()],
+        ) -> WishResponse:
+            """grant wishes"""
+
+
+def test_router_prompt_context_not_in_openapi() -> None:
+    app = FastAPI()
+    router = PromptRouter(agent_runner=_ok_runner)
+
+    @router.prompt.post("/wish")
+    def make_a_wish(req: WishRequest, ctx: PromptContext) -> WishResponse:
+        """grant wishes"""
+        ctx.add("hint")
+
+    app.include_router(router)
+    schema = app.openapi()
+    schema_str = str(schema)
+    assert "PromptContext" not in schema_str

{pyyapi-0.2.0 → pyyapi-0.3.0}/tests/test_runtime.py

@@ -95,3 +95,60 @@ def test_runtime_sends_composed_prompt_to_agent_runner() -> None:
     assert "user is shouting" in captured["prompt"]
     assert captured["request"] == {"user_id": "u-1", "wish": "moon"}
     assert captured["injected"] == {"profile": {"vip": True}}
+
+
+from yapi.prompt_context import PromptContext
+from yapi.runtime import compose_prompt
+
+
+def test_compose_skips_context_when_empty():
+    endpoint = PromptEndpoint(
+        path="/wish",
+        method="POST",
+        request_model=None,
+        response_model=WishResponse,
+        function_doc="grant wishes",
+    )
+    prompt = compose_prompt(endpoint, None, None)
+    assert "<context>" not in prompt
+
+
+def test_compose_wraps_single_ctx_segment():
+    endpoint = PromptEndpoint(
+        path="/wish",
+        method="POST",
+        request_model=None,
+        response_model=WishResponse,
+        function_doc="grant wishes",
+    )
+    ctx = PromptContext()
+    ctx.add("hint segment")
+    prompt = compose_prompt(endpoint, ctx, None)
+    assert "<context>\nhint segment\n</context>" in prompt
+
+
+def test_compose_wraps_dynamic_only():
+    endpoint = PromptEndpoint(
+        path="/wish",
+        method="POST",
+        request_model=None,
+        response_model=WishResponse,
+        function_doc="grant wishes",
+    )
+    prompt = compose_prompt(endpoint, None, "dynamic text")
+    assert "<context>\ndynamic text\n</context>" in prompt
+
+
+def test_compose_concatenates_ctx_then_dynamic():
+    endpoint = PromptEndpoint(
+        path="/wish",
+        method="POST",
+        request_model=None,
+        response_model=WishResponse,
+        function_doc="grant wishes",
+    )
+    ctx = PromptContext()
+    ctx.add("s1")
+    ctx.add("s2")
+    prompt = compose_prompt(endpoint, ctx, "dynamic")
+    assert "<context>\ns1\n\ns2\n\ndynamic\n</context>" in prompt

{pyyapi-0.2.0 → pyyapi-0.3.0}/yapi/__init__.py

@@ -4,11 +4,13 @@ from yapi.errors import (
     YapiError,
     YapiUsageWarning,
 )
+from yapi.prompt_context import PromptContext
 from yapi.router import PromptRouter
 from yapi.runner import AgentRunner, RunnerContext
 
 __all__ = [
     "PromptRouter",
+    "PromptContext",
     "AgentRunner",
     "RunnerContext",
     "YapiError",

pyyapi-0.3.0/yapi/prompt_context.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+from yapi.errors import RuntimeExecutionError
+
+
+def _format_value(value: Any) -> str:
+    if value is None:
+        raise RuntimeExecutionError(
+            "PromptContext does not accept None; use an empty string if you want an empty segment."
+        )
+    if isinstance(value, str):
+        return value
+    if isinstance(value, BaseModel):
+        return value.model_dump_json()
+    if isinstance(value, (dict, list, tuple)):
+        return json.dumps(value, ensure_ascii=False)
+    return str(value)
+
+
+class PromptContext:
+    def __init__(self) -> None:
+        self._segments: list[str] = []
+
+    def add(self, value: Any) -> None:
+        self._segments.append(_format_value(value))
+
+    def add_kv(self, key: str, value: Any) -> None:
+        self._segments.append(f"{key}: {_format_value(value)}")
+
+    def add_section(self, name: str, body: Any) -> None:
+        self._segments.append(f"# {name}\n{_format_value(body)}")
+
+    def segments(self) -> tuple[str, ...]:
+        return tuple(self._segments)

{pyyapi-0.2.0 → pyyapi-0.3.0}/yapi/router.py

@@ -14,6 +14,7 @@ from pydantic import BaseModel
 from yapi.agent import build_default_runner
 from yapi.endpoint import PromptEndpoint
 from yapi.errors import RuntimeExecutionError, YapiDeclarationError, YapiUsageWarning
+from yapi.prompt_context import PromptContext
 from yapi.runner import AgentRunner
 from yapi.runtime import PromptComposer, Runtime
 
@@ -63,6 +64,7 @@ class ParamRole(Enum):
     REQUEST_MODEL = "request_model"
     DEPENDENCY = "dependency"
     INJECTED_FIELD = "injected_field"
+    PROMPT_CONTEXT = "prompt_context"
 
 
 def _unwrap_annotated(annotation: Any) -> tuple[Any, tuple[Any, ...]]:
@@ -75,6 +77,10 @@ def _is_basemodel_type(tp: Any) -> bool:
     return isinstance(tp, type) and issubclass(tp, BaseModel)
 
 
+def _is_prompt_context_type(tp: Any) -> bool:
+    return isinstance(tp, type) and issubclass(tp, PromptContext)
+
+
 def _classify_param(
     name: str,
     param: inspect.Parameter,
@@ -90,9 +96,22 @@ def _classify_param(
         )
 
     annotation = param.annotation
-    default = param.default
+
+    # PromptContext bare type → auto-inject role (must be checked before _unwrap_annotated)
+    if _is_prompt_context_type(annotation):
+        return ParamRole.PROMPT_CONTEXT
+
     base_annotation, metadata = _unwrap_annotated(annotation)
 
+    # PromptContext inside Annotated[...] with markers is forbidden
+    if _is_prompt_context_type(base_annotation) and metadata:
+        raise YapiDeclarationError(
+            f"yapi prompt route '{func_name}' parameter '{name}': "
+            "PromptContext is auto-injected by yapi and must not carry FastAPI markers"
+        )
+
+    default = param.default
+
     if isinstance(default, params.Depends):
         return ParamRole.DEPENDENCY
 
@@ -134,7 +153,13 @@ def _classify_param(
 
 def _introspect(
     func: Callable,
-) -> tuple[type[BaseModel] | None, type[BaseModel], dict[str, ParamRole], str | None]:
+) -> tuple[
+    type[BaseModel] | None,
+    type[BaseModel],
+    dict[str, ParamRole],
+    str | None,
+    str | None,
+]:
     signature = inspect.signature(func)
 
     return_annotation = signature.return_annotation
@@ -156,6 +181,7 @@ def _introspect(
     param_roles: dict[str, ParamRole] = {}
     request_model: type[BaseModel] | None = None
     request_param_name: str | None = None
+    ctx_param_name: str | None = None
 
     for name, param in signature.parameters.items():
         role = _classify_param(name, param, func.__name__)
@@ -169,8 +195,14 @@ def _introspect(
             base_annotation, _ = _unwrap_annotated(param.annotation)
             request_model = base_annotation
             request_param_name = name
+        elif role is ParamRole.PROMPT_CONTEXT:
+            if ctx_param_name is not None:
+                raise YapiDeclarationError(
+                    f"yapi prompt route '{func.__name__}' may declare at most one PromptContext parameter"
+                )
+            ctx_param_name = name
 
-    return request_model, return_annotation, param_roles, request_param_name
+    return request_model, return_annotation, param_roles, request_param_name, ctx_param_name
 
 
 def _validate_prompt_kwargs(path: str, kwargs: dict[str, Any]) -> dict[str, Any]:
@@ -238,7 +270,13 @@ class PromptRouter(APIRouter):
         passthrough = _validate_prompt_kwargs(path, kwargs)
 
         def decorator(func: Callable) -> Callable:
-            request_model, response_model, param_roles, request_param_name = _introspect(func)
+            (
+                request_model,
+                response_model,
+                param_roles,
+                request_param_name,
+                ctx_param_name,
+            ) = _introspect(func)
 
             endpoint = PromptEndpoint(
                 path=path,
@@ -255,7 +293,11 @@ class PromptRouter(APIRouter):
             async def handler(**kwargs):
                 injected: dict[str, Any] = {}
                 request_instance: BaseModel | None = None
+                ctx = PromptContext() if ctx_param_name else None
+
                 for name, role in param_roles.items():
+                    if name == ctx_param_name:
+                        continue
                     if name not in kwargs:
                         continue
                     if role is ParamRole.REQUEST_MODEL:
@@ -263,10 +305,14 @@ class PromptRouter(APIRouter):
                     else:
                         injected[name] = kwargs[name]
 
+                user_kwargs = dict(kwargs)
+                if ctx_param_name is not None:
+                    user_kwargs[ctx_param_name] = ctx
+
                 if is_async:
-                    dynamic_prompt = await func(**kwargs)
+                    dynamic_prompt = await func(**user_kwargs)
                 else:
-                    dynamic_prompt = func(**kwargs)
+                    dynamic_prompt = func(**user_kwargs)
 
                 if dynamic_prompt is not None and not isinstance(dynamic_prompt, str):
                     raise RuntimeExecutionError(
@@ -279,16 +325,22 @@ class PromptRouter(APIRouter):
                     endpoint=endpoint,
                     request_model=request_instance,
                     injected=injected,
+                    prompt_context=ctx,
                     dynamic_prompt=dynamic_prompt,
                 )
 
+            # FastAPI-visible params: filter out PROMPT_CONTEXT
+            fastapi_visible_params = [
+                p for p in original_params
+                if param_roles.get(p.name) is not ParamRole.PROMPT_CONTEXT
+            ]
             handler.__signature__ = inspect.Signature(
-                parameters=original_params,
+                parameters=fastapi_visible_params,
                 return_annotation=response_model,
             )
             handler.__annotations__ = {
                 p.name: p.annotation
-                for p in original_params
+                for p in fastapi_visible_params
                 if p.annotation is not inspect.Parameter.empty
             }
             handler.__annotations__["return"] = response_model
@@ -296,11 +348,12 @@ class PromptRouter(APIRouter):
             handler.__doc__ = func.__doc__
 
             logger.debug(
-                "registering prompt route method=%s path=%s handler=%s async=%s",
+                "registering prompt route method=%s path=%s handler=%s async=%s ctx=%s",
                 upper,
                 path,
                 func.__name__,
                 is_async,
+                ctx_param_name,
             )
 
             self.add_api_route(

{pyyapi-0.2.0 → pyyapi-0.3.0}/yapi/runtime.py

@@ -2,12 +2,14 @@ from __future__ import annotations
 
 import logging
 from collections.abc import Callable
+from typing import Any
 
 from pydantic import BaseModel
 
 from yapi.endpoint import PromptEndpoint
 from yapi.errors import RuntimeExecutionError
 from yapi.models import RuntimeContext
+from yapi.prompt_context import PromptContext
 from yapi.runner import AgentRunner, RunnerContext, _coerce_runner
 
 logger = logging.getLogger("yapi.runtime")
@@ -18,21 +20,46 @@ DEFAULT_SYSTEM_PREFIX = (
 )
 
 
-PromptComposer = Callable[[PromptEndpoint, str | None], str]
+PromptComposer = Callable[[PromptEndpoint, "PromptContext | None", "str | None"], str]
 
 
-def compose_prompt(endpoint: PromptEndpoint, dynamic_prompt: str | None) -> str:
+def compose_prompt(
+    endpoint: PromptEndpoint,
+    prompt_context: PromptContext | None,
+    dynamic_prompt: str | None,
+) -> str:
     sections = [DEFAULT_SYSTEM_PREFIX]
-    response_doc = endpoint.response_doc
-    if response_doc:
-        sections.append(response_doc)
+    if endpoint.response_doc:
+        sections.append(endpoint.response_doc)
     if endpoint.function_doc:
         sections.append(endpoint.function_doc)
+
+    ctx_segments = list(prompt_context.segments()) if prompt_context else []
     if dynamic_prompt:
-        sections.append(dynamic_prompt)
+        ctx_segments.append(dynamic_prompt)
+    if ctx_segments:
+        body = "\n\n".join(ctx_segments)
+        sections.append(f"<context>\n{body}\n</context>")
+
     return "\n\n".join(sections)
 
 
+def _adapt_composer(composer: Any) -> PromptComposer:
+    """Wrap a possibly v2.1-style (endpoint, dynamic_prompt) composer for v2.2 calls."""
+
+    def adapted(
+        endpoint: PromptEndpoint,
+        prompt_context: PromptContext | None,
+        dynamic_prompt: str | None,
+    ) -> str:
+        try:
+            return composer(endpoint, prompt_context, dynamic_prompt)
+        except TypeError:
+            return composer(endpoint, dynamic_prompt)
+
+    return adapted
+
+
 class Runtime:
     def __init__(
         self,
@@ -40,7 +67,9 @@ class Runtime:
         prompt_composer: PromptComposer | None = None,
     ) -> None:
         self._agent_runner: AgentRunner = _coerce_runner(agent_runner)
-        self._compose_prompt: PromptComposer = prompt_composer or compose_prompt
+        self._compose_prompt: PromptComposer = (
+            _adapt_composer(prompt_composer) if prompt_composer is not None else compose_prompt
+        )
 
     def build_context(self, request_data: dict, injected: dict) -> RuntimeContext:
         return RuntimeContext(
@@ -54,10 +83,11 @@ class Runtime:
         request_model: BaseModel | None,
         injected: dict,
         dynamic_prompt: str | None,
+        prompt_context: PromptContext | None = 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 = self._compose_prompt(endpoint, dynamic_prompt)
+        prompt = self._compose_prompt(endpoint, prompt_context, dynamic_prompt)
 
         logger.debug(
             "execute path=%s method=%s has_request_model=%s injected_keys=%s",