fastapi-authly 0.1.34__tar.gz → 0.1.35__tar.gz

{fastapi_authly-0.1.34 → fastapi_authly-0.1.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-authly
-Version: 0.1.34
+Version: 0.1.35
 Summary: A modular authentication system for FastAPI with OAuth2, JWT, and password recovery
 Project-URL: Homepage, https://github.com/yourusername/fastapi-auth-module
 Project-URL: Documentation, https://yourusername.github.io/fastapi-auth-module/

{fastapi_authly-0.1.34 → fastapi_authly-0.1.35}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fastapi-authly"
-version = "0.1.34"
+version = "0.1.35"
 description = "A modular authentication system for FastAPI with OAuth2, JWT, and password recovery"
 readme = "README.md"
 license = {text = "MIT"}

{fastapi_authly-0.1.34 → fastapi_authly-0.1.35}/src/fastapi_authly/__about__.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.1.34"
+__version__ = "0.1.35"

fastapi_authly-0.1.35/src/fastapi_authly/ai/output_parsers/__init__.py

@@ -0,0 +1,4 @@
+from .tool import StructuredAgent
+from .direct import JsonExtractor
+
+__all__ = ["StructuredAgent", "JsonExtractor"]

fastapi_authly-0.1.35/src/fastapi_authly/ai/output_parsers/direct.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar
+
+from json_repair import repair_json
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage, convert_to_openai_messages
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+T = TypeVar("T", bound=BaseModel)
+ResultValidator = Callable[[T, str], None]
+
+
+def jsonify(value: str | BaseMessage) -> Any:
+    """提取文本中的 JSON；标准解析失败时尝试修复常见格式错误。"""
+    content = value.content if isinstance(value, BaseMessage) else value
+    if isinstance(content, list):
+        content = "\n".join(
+            block if isinstance(block, str) else block.get("text", "")
+            for block in content
+            if isinstance(block, str) or isinstance(block, dict) and block.get("type") == "text"
+        )
+    if not isinstance(content, str) or not content.strip():
+        raise ValueError("模型最终回复没有可解析的 JSON 文本")
+    text = content.strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        try:
+            repaired = repair_json(text, return_objects=True)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(f"JSON 修复失败：{exc}") from exc
+        if repaired == "":
+            raise ValueError("无法从模型最终回复中提取 JSON，请输出完整的 JSON")
+        return repaired
+
+
+class JsonExtractor(Generic[T]):
+    """直接调用聊天模型，从回复文本中提取经过 Pydantic 校验的 JSON。
+
+    将 JSON Schema 写入系统提示词，不启用模型原生 JSON 模式。
+    JSON 解析、Pydantic 或业务校验抛出 ValueError 时，保留对话历史并
+    追加错误反馈重试。max_validation_attempts 包含首次调用；模型调用
+    本身的异常直接向外抛出。
+
+    Examples:
+        model 由调用方提供，为 BaseChatModel 实例，无需支持工具调用。
+
+        >>> from pydantic import BaseModel, Field
+        >>> class ComplaintResult(BaseModel):
+        ...     person_name: str | None = Field(description="被投诉人姓名，未提及则为 null")
+        ...     unit_name: str | None = Field(description="被投诉单位，未提及则为 null")
+        >>> extractor = JsonExtractor(
+        ...     model,
+        ...     ComplaintResult,
+        ...     system_prompt="从诉求正文中抽取被投诉人和被投诉单位，不要编造信息。",
+        ...     max_validation_attempts=3,
+        ... )
+        >>> result = extractor.invoke("投诉光明派出所的张三处理不当。")
+        >>> isinstance(result, ComplaintResult)
+        True
+        >>> data = result.model_dump()
+
+        在异步函数中调用：
+
+        >>> result = await extractor.ainvoke("投诉光明派出所的张三处理不当。")
+
+        如需校验抽取值来自原文，可提供业务校验函数；失败时抛出 ValueError：
+
+        >>> def validate_source(result: ComplaintResult, source_text: str) -> None:
+        ...     for name in (result.person_name, result.unit_name):
+        ...         if name is not None and name not in source_text:
+        ...             raise ValueError(f"{name!r} 未出现在原文，请使用原文名称或 null")
+        >>> checked = JsonExtractor(
+        ...     model, ComplaintResult,
+        ...     system_prompt="抽取被投诉人和被投诉单位。",
+        ...     result_validator=validate_source,
+        ... )
+        >>> content = "投诉光明派出所的张三处理不当。"
+        >>> result = checked.invoke(content, source_text=content)
+
+        调试时同时启用 debug_model 和本模块的 DEBUG 日志：
+
+        >>> import logging
+        >>> logging.basicConfig(level=logging.INFO)
+        >>> logging.getLogger(JsonExtractor.__module__).setLevel(logging.DEBUG)
+        >>> extractor = JsonExtractor(
+        ...     model, ComplaintResult, system_prompt="抽取投诉信息。", debug_model=True,
+        ... )
+    """
+
+    def __init__(
+            self,
+            model: BaseChatModel,
+            schema: type[T],
+            *,
+            system_prompt: str,
+            max_validation_attempts: int = 3,
+            result_validator: ResultValidator[T] | None = None,
+            debug_model: bool = False,
+    ) -> None:
+        self.model = model
+        self.schema = schema
+        self.system_prompt = system_prompt
+        self.max_validation_attempts = self._positive(max_validation_attempts, "max_validation_attempts")
+        self.result_validator = result_validator
+        self.debug_model = debug_model
+
+    @staticmethod
+    def _positive(value: int, name: str) -> int:
+        if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+            raise ValueError(f"{name} 必须是大于 0 的整数")
+        return value
+
+    def _messages(self, message: str) -> list[BaseMessage]:
+        schema_json = json.dumps(self.schema.model_json_schema(), ensure_ascii=False, indent=2)
+        prompt = (
+            f"{self.system_prompt}\n\n"
+            "最终回复必须只包含一个符合下述 JSON Schema 的完整 JSON 值。\n"
+            "不要输出 Markdown 代码围栏、解释或推理过程。字段类型、必填项、枚举值及约束"
+            "必须遵守 Schema；只有 Schema 允许时才能使用 null。\n"
+            "如果收到校验错误，请结合已有对话修正，重新输出完整 JSON。\n"
+            f"JSON Schema：\n{schema_json}"
+        )
+        return [SystemMessage(content=prompt), HumanMessage(content=message)]
+
+    def _prepare(self, max_validation_attempts: int | None, source_text: str | None) -> int:
+        attempts = (
+            self.max_validation_attempts if max_validation_attempts is None
+            else self._positive(max_validation_attempts, "max_validation_attempts")
+        )
+        if self.result_validator is not None and not isinstance(source_text, str):
+            raise ValueError("设置 result_validator 时必须传入可信原文 source_text")
+        return attempts
+
+    def _result(self, response: BaseMessage, source_text: str | None) -> T:
+        result = self.schema.model_validate(jsonify(response))
+        if self.result_validator is not None:
+            assert source_text is not None
+            self.result_validator(result, source_text)
+        return result
+
+    def _validate_or_feedback(
+            self, messages: list[BaseMessage], response: BaseMessage,
+            source_text: str | None, attempt: int, attempts: int,
+    ) -> T | None:
+        messages.append(response)
+        if self.debug_model and logger.isEnabledFor(logging.DEBUG):
+            logger.debug("模型返回：\n%s", response.pretty_repr())
+        try:
+            return self._result(response, source_text)
+        except ValueError as exc:
+            logger.warning("JSON 结果校验未通过（第 %d/%d 次）：%s", attempt, attempts, exc)
+            if attempt == attempts:
+                raise ValueError(f"结果在 {attempts} 次调用后仍未通过校验：{exc}") from exc
+            messages.append(HumanMessage(content=(
+                f"上一轮最终结果未通过校验，错误信息如下：\n{exc}\n"
+                "请根据原始任务、已有对话和 JSON Schema 修正，重新输出完整 JSON。"
+            )))
+            return None
+
+    def _log_request(self, messages: list[BaseMessage], attempt: int) -> None:
+        if self.debug_model and logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "第 %d 轮模型调用，请求：\n%s", attempt,
+                json.dumps(convert_to_openai_messages(messages), ensure_ascii=False, indent=2, default=str),
+            )
+
+    def invoke(
+            self, message: str, *, source_text: str | None = None,
+            max_validation_attempts: int | None = None,
+    ) -> T:
+        attempts = self._prepare(max_validation_attempts, source_text)
+        messages = self._messages(message)
+        for attempt in range(1, attempts + 1):
+            self._log_request(messages, attempt)
+            response = self.model.invoke(messages)
+            result = self._validate_or_feedback(messages, response, source_text, attempt, attempts)
+            if result is not None:
+                return result
+        raise RuntimeError("未获得 JSON 结果")
+
+    async def ainvoke(
+            self, message: str, *, source_text: str | None = None,
+            max_validation_attempts: int | None = None,
+    ) -> T:
+        attempts = self._prepare(max_validation_attempts, source_text)
+        messages = self._messages(message)
+        for attempt in range(1, attempts + 1):
+            self._log_request(messages, attempt)
+            response = await self.model.ainvoke(messages)
+            result = self._validate_or_feedback(messages, response, source_text, attempt, attempts)
+            if result is not None:
+                return result
+        raise RuntimeError("未获得 JSON 结果")