fiuai-sdk-python 0.15.0__tar.gz → 0.16.0__tar.gz

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.0] - 2026-07-15
+
+### Added
+- 新增 `X-FiuAI-Roles` JSON 数组认证头及 `AuthData.roles`, 支持严格解析、上下文传播和下游 HTTP 注入。
+- 新增 `get_roles()` 与 `get_effective_tenant_id()` 认证 helper。
+
 ## [0.13.0] - 2026-05-13
 
 ### Fixed

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiuai_sdk_python
-Version: 0.15.0
+Version: 0.16.0
 Summary: FiuAI Python SDK - 企业级AI服务集成开发工具包
 Project-URL: Homepage, https://github.com/fiuai/fiuai-sdk-python
 Project-URL: Documentation, https://github.com/fiuai/fiuai-sdk-python#readme

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fiuai_sdk_python"
-version = "0.15.0"
+version = "0.16.0"
 description = "FiuAI Python SDK - 企业级AI服务集成开发工具包"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -75,4 +75,3 @@ dev-dependencies = [
     "pre-commit>=3.0.0",
 ]
 
-

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/__init__.py

@@ -18,7 +18,7 @@ from .error_code import (
 )
 from .resp import ApiError, ApiResponse, parse_response
 
-__version__ = "0.13.0"
+__version__ = "0.16.0"
 
 __all__ = [
     'FiuaiSDK',

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/auth/__init__.py

@@ -1,4 +1,9 @@
-from .header import parse_auth_headers, extract_auth_from_request
+from .header import (
+    extract_auth_from_request,
+    parse_auth_headers,
+    parse_roles_header,
+    serialize_roles_header,
+)
 from .type import AuthData, AuthHeader
 from .helper import (
     get_auth_data,
@@ -7,6 +12,8 @@ from .helper import (
     get_current_company,
     get_company_unique_no,
     get_impersonation,
+    get_roles,
+    get_effective_tenant_id,
     is_impersonating,
 )
 from .context_mgr import (
@@ -27,6 +34,8 @@ get_auth_data_from_request = get_auth_data
 __all__ = [
     "parse_auth_headers",
     "extract_auth_from_request",
+    "parse_roles_header",
+    "serialize_roles_header",
     "AuthData",
     "AuthHeader",
     "get_auth_data",
@@ -37,6 +46,8 @@ __all__ = [
     "get_current_company",
     "get_company_unique_no",
     "get_impersonation",
+    "get_roles",
+    "get_effective_tenant_id",
     "is_impersonating",
     "ContextManager",
     "init_context",
@@ -46,4 +57,4 @@ __all__ = [
     "get_world_data",
     "set_user_profile_info",
     "get_user_profile_info",
-]
+]

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/auth/context_mgr.py

@@ -20,7 +20,7 @@ from pydantic import BaseModel, Field
 
 from ..context import RequestContext, get_current_headers, is_current_context_valid
 from .type import AuthData, FIUAI_CLIENT_VALUES
-from .header import parse_auth_headers
+from .header import parse_auth_headers, serialize_roles_header
 
 logger = logging.getLogger(__name__)
 
@@ -92,6 +92,7 @@ class ContextManager:
             "x-fiuai-channel": "default",
             "x-fiuai-lang": auth_data.lang or "zh",
             "accept-language": auth_data.accept_language or "zh",
+            "x-fiuai-roles": serialize_roles_header(auth_data.roles),
         }
         return RequestContext.from_dict(headers)
 
@@ -182,6 +183,7 @@ def init_context(
             lang=kwargs.get("lang", "zh"),
             accept_language=kwargs.get("accept_language", "zh"),
             model=(kwargs.get("model") or "auto").strip() or "auto",
+            roles=kwargs.get("roles") or [],
         )
         return ContextManager(
             auth_data=auth_data,
@@ -275,6 +277,7 @@ def update_auth_data(
             lang=kwargs.get("lang", current.lang),
             accept_language=kwargs.get("accept_language", current.accept_language),
             model=model,
+            roles=kwargs.get("roles", current.roles),
         )
         return set_auth_data(new_auth_data)
     except Exception as e:

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/auth/header.py

@@ -5,12 +5,51 @@
 # Email: lmlala@aliyun.com
 # Copyright (c) 2025 FiuAI
 
+import json
 from typing import Dict, Optional, Union, Literal
 from .type import AuthData, FIUAI_CLIENT_VALUES
 from fastapi import Request
 
 
-def parse_auth_headers(headers: Dict[str, str]) -> Optional[AuthData]:
+def parse_roles_header(raw_value: str | None) -> list[str]:
+    """严格解析 ``X-FiuAI-Roles`` JSON 数组并保持首次出现顺序."""
+    value = (raw_value or "").strip()
+    if not value:
+        return []
+    try:
+        decoded = json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise ValueError("Invalid header x-fiuai-roles: expected JSON array") from exc
+    if not isinstance(decoded, list):
+        raise ValueError("Invalid header x-fiuai-roles: expected JSON array")
+
+    roles: list[str] = []
+    seen: set[str] = set()
+    for raw_role in decoded:
+        if not isinstance(raw_role, str):
+            raise ValueError("Invalid header x-fiuai-roles: roles must be strings")
+        role = raw_role.strip()
+        if not role:
+            raise ValueError("Invalid header x-fiuai-roles: role cannot be empty")
+        if role not in seen:
+            seen.add(role)
+            roles.append(role)
+    return roles
+
+
+def serialize_roles_header(roles: list[str] | tuple[str, ...] | None) -> str:
+    """把角色代码规范化为紧凑、无歧义的 JSON header 值."""
+    normalized = parse_roles_header(
+        json.dumps(list(roles or []), ensure_ascii=True, separators=(",", ":"))
+    )
+    return json.dumps(normalized, ensure_ascii=True, separators=(",", ":"))
+
+
+def parse_auth_headers(
+    headers: Dict[str, str],
+    *,
+    allow_empty_company: bool = False,
+) -> Optional[AuthData]:
     """
     从 HTTP headers 中解析认证信息并转换为 AuthData
     
@@ -38,6 +77,7 @@ def parse_auth_headers(headers: Dict[str, str]) -> Optional[AuthData]:
         channel = "default"
         lang = headers.get("x-fiuai-lang", "zh") or "zh"
         accept_language = headers.get("accept-language", "zh") or "zh"
+        roles = parse_roles_header(headers.get("x-fiuai-roles"))
 
         # 验证必需字段
         if not user_id:
@@ -51,17 +91,17 @@ def parse_auth_headers(headers: Dict[str, str]) -> Optional[AuthData]:
             current_company = [company.strip() for company in current_company_str.split(",") if company.strip()]
         
         # 检查是否有有效的公司信息
-        if not current_company:
+        if not current_company and not allow_empty_company:
             raise ValueError("Missing required header: x-fiuai-current-company")
         
         # 如果没有提供 unique_no，使用第一个公司ID作为默认值
-        if not unique_no:
+        if not unique_no and current_company:
             unique_no = current_company[0]
             
         return AuthData(
             user_id=user_id,
             auth_tenant_id=auth_tenant_id,
-            current_company=current_company[0],
+            current_company=current_company[0] if current_company else "",
             impersonation=impersonation,
             company_unique_no=unique_no,
             trace_id=trace_id,
@@ -70,6 +110,7 @@ def parse_auth_headers(headers: Dict[str, str]) -> Optional[AuthData]:
             lang=lang,
             accept_language=accept_language,
             model=model,
+            roles=roles,
         )
         
     except Exception as e:

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/auth/helper.py

@@ -103,6 +103,26 @@ def get_impersonation(
     return auth_data.impersonation if auth_data else None
 
 
+def get_roles(
+    request: Optional[Union[Request, Dict[str, str]]] = None,
+    engine: Literal["fastapi", "dict"] = "fastapi",
+) -> list[str]:
+    """获取当前认证角色；无认证上下文时返回空列表."""
+    auth_data = get_auth_data(request, engine)
+    return list(auth_data.roles) if auth_data else []
+
+
+def get_effective_tenant_id(
+    request: Optional[Union[Request, Dict[str, str]]] = None,
+    engine: Literal["fastapi", "dict"] = "fastapi",
+) -> Optional[str]:
+    """获取权限判断使用的有效租户，impersonation 优先."""
+    auth_data = get_auth_data(request, engine)
+    if not auth_data:
+        return None
+    return auth_data.impersonation or auth_data.auth_tenant_id
+
+
 def get_current_client(
     request: Optional[Union[Request, Dict[str, str]]] = None,
     engine: Literal["fastapi", "dict"] = "fastapi",
@@ -137,4 +157,4 @@ def get_current_model_mode(
     获取当前模型模式。request 为 None 时从当前上下文取；无上下文或未认证时返回 None。
     """
     auth_data = get_auth_data(request, engine)
-    return auth_data.model if auth_data else None
+    return auth_data.model if auth_data else None

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/auth/type.py

@@ -31,6 +31,10 @@ class AuthData(BaseModel):
         description="下游/本地自定义 LLM 模型标识, 请求头 x-fiuai-model, 默认 auto",
         default="auto",
     )
+    roles: list[str] = Field(
+        description="网关认证后注入的规范化角色代码",
+        default_factory=list,
+    )
 
     # edoc
 
@@ -49,8 +53,13 @@ class AuthHeader(BaseModel):
         default="unknown",
         description="本地请求自定义 model, 默认 unknown",
     )
+    x_fiuai_roles: str = Field(
+        alias="x-fiuai-roles",
+        default="[]",
+        description="规范化角色代码 JSON 数组",
+    )
     x_fiuai_channel: str = Field(alias="x-fiuai-channel", default="default", description="渠道code，目前未用")
     accept_language: str = Field(alias="accept-language", default="zh", description="语言")
 
     class Config:
-        populate_by_name = True
+        populate_by_name = True

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/client.py

@@ -69,6 +69,7 @@ class FiuaiSDK(object):
             x_fiuai_impersonation="",
             x_fiuai_unique_no=company_unique_no or current_company or "",  # 优先使用 company_unique_no
             x_fiuai_trace_id="",
+            x_fiuai_roles="[]",
             )
         
         # 临时 headers 存储，用于 set_temp_header 方法
@@ -116,6 +117,7 @@ class FiuaiSDK(object):
                 "x-fiuai-channel": context_headers.get("x-fiuai-channel", self.headers.x_fiuai_channel),
                 "x-fiuai-lang": context_headers.get("x-fiuai-lang", self.headers.x_fiuai_lang),
                 "accept-language": context_headers.get("accept-language", self.headers.accept_language),
+                "x-fiuai-roles": context_headers.get("x-fiuai-roles", self.headers.x_fiuai_roles),
             })
         else:
             # 如果没有上下文，使用初始化参数或默认的 headers
@@ -137,6 +139,7 @@ class FiuaiSDK(object):
                 "x-fiuai-channel": self.headers.x_fiuai_channel,
                 "x-fiuai-lang": self.headers.x_fiuai_lang,
                 "accept-language": self.headers.accept_language,
+                "x-fiuai-roles": self.headers.x_fiuai_roles,
             }
         
         # 应用临时 headers（优先级高于上下文，低于 extra_headers）
@@ -588,4 +591,3 @@ def get_client(username: str = None, auth_tenant_id: str = None, current_company
         host=client_config.host,
         trust_env=client_config.trust_env,
     )
-

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/context.py

@@ -105,6 +105,8 @@ class RequestContext:
             processed_headers["x-fiuai-client"] = "default"
         if not (processed_headers.get("x-fiuai-model") or "").strip():
             processed_headers["x-fiuai-model"] = "auto"
+        if not (processed_headers.get("x-fiuai-roles") or "").strip():
+            processed_headers["x-fiuai-roles"] = "[]"
 
         return processed_headers
     
@@ -250,6 +252,7 @@ def extract_auth_headers_from_context(
     channel: str = "default",
     lang: str = "zh",
     accept_language: str = "zh",
+    roles: str = "[]",
 ) -> AuthHeader:
     """
     从当前上下文中提取认证头信息，并合并用户提供的参数
@@ -287,6 +290,7 @@ def extract_auth_headers_from_context(
             x_fiuai_channel="default",
             x_fiuai_lang=lang,
             accept_language=accept_language,
+            x_fiuai_roles=roles or "[]",
         )
 
     # 从上下文中提取信息，优先使用上下文中的值
@@ -310,5 +314,5 @@ def extract_auth_headers_from_context(
         x_fiuai_channel="default",
         x_fiuai_lang=context_lang or lang,
         accept_language=context_accept_language or accept_language,
+        x_fiuai_roles=context_headers.get("x-fiuai-roles") or roles or "[]",
     )
-

{fiuai_sdk_python-0.15.0 → fiuai_sdk_python-0.16.0}/src/fiuai_sdk_python/http/client.py

@@ -33,6 +33,7 @@ AUTH_HEADER_KEYS = [
     "x-fiuai-channel",
     "x-fiuai-lang",
     "accept-language",
+    "x-fiuai-roles",
 ]