tcaicc 1.4.0__tar.gz

tcaicc-1.4.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# Test / coverage caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# 明文默认 mTLS 证书源材料(由 hardcode.sh 加密进 _default_certs.py;密文可提交,明文不提交)
+cert/
+
+# doc/ 下 demo*.py 是权威文档示例,随仓库提交;doc.html 不在本仓库,维护于 ../aicc-sdk-doc/。

tcaicc-1.4.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: tcaicc
+Version: 1.4.0
+Summary: Tencent AICC confidential-model SDK for Python
+Author: Tencent
+License-Expression: LicenseRef-Proprietary
+License-File: THIRD_PARTY_NOTICES
+Keywords: aicc,confidential-computing,encryption,ml-kem,remote-attestation,sev-snp,tencent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=48
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# TCAICC
+
+版本:1.4.0
+
+许可:专有软件,仅限腾讯云 AICC 服务客户使用;第三方组件见 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES)。

tcaicc-1.4.0/README.md

@@ -0,0 +1,5 @@
+# TCAICC
+
+版本:1.4.0
+
+许可:专有软件,仅限腾讯云 AICC 服务客户使用;第三方组件见 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES)。

tcaicc-1.4.0/THIRD_PARTY_NOTICES

@@ -0,0 +1,26 @@
+TCAICC SDK 第三方组件声明 / Third-Party Notices
+
+本软件未内置第三方源代码。下列开源组件为运行时依赖,由用户在安装时从 PyPI
+另行获取,适用其各自的许可证,不受本软件 LICENSE 约束。版本为本版本构建时锁定的版本,
+实际安装版本以 pip 解析结果为准。
+
+| 组件 | 版本 | 许可证 | 项目地址 |
+|---|---|---|---|
+| cryptography | 49.0.0 | Apache-2.0 OR BSD-3-Clause | https://github.com/pyca/cryptography |
+| cffi | 2.1.0 | MIT-0 | https://github.com/python-cffi/cffi |
+| pycparser | 3.0 | BSD-3-Clause | https://github.com/eliben/pycparser |
+| httpx | 0.28.1 | BSD-3-Clause | https://github.com/encode/httpx |
+| httpcore | 1.0.9 | BSD-3-Clause | https://github.com/encode/httpcore |
+| h11 | 0.16.0 | MIT | https://github.com/python-hyper/h11 |
+| anyio | 4.14.2 | MIT | https://github.com/agronholm/anyio |
+| idna | 3.18 | BSD-3-Clause | https://github.com/kjd/idna |
+| certifi | 2026.7.22 | MPL-2.0 | https://github.com/certifi/python-certifi |
+| exceptiongroup | 1.3.1 | MIT | https://github.com/agronholm/exceptiongroup |
+| typing-extensions | 4.16.0 | PSF-2.0 | https://github.com/python/typing_extensions |
+
+说明:
+- cryptography、httpx 为直接依赖,其余为传递依赖;exceptiongroup 仅 Python < 3.11、
+  typing-extensions 仅 Python < 3.13、cffi/pycparser 仅 CPython 时安装。
+- 本软件随包分发的 AMD SEV-SNP 根证书(ARK/ASK,位于 tcaicc/common/security/trust_anchors/)
+  为 AMD 公开发布的证书,版权归 Advanced Micro Devices, Inc. 所有。
+- 各组件许可证全文见其项目地址或安装后的 *.dist-info/ 目录。

tcaicc-1.4.0/doc/demo.py

@@ -0,0 +1,50 @@
+# demo.py —— 非流式示例(ModelPool 按 model 发现端点):安全会话握手 → 加密请求 → 解密回文,只打印明文。
+#
+# 环境变量(均必填,无内置默认):AICC_BASE_URL(安全会话入口)、AICC_GATEWAY_URL(LLM 网关)、AICC_API_KEY、AICC_MODEL_NAME
+#
+#   python doc/demo.py
+import json
+import os
+
+import httpx
+
+from tcaicc import ModelPool, Protocol, SessionFactory, SessionPool, default_policy
+
+base_url = os.getenv("AICC_BASE_URL")
+gateway_url = os.getenv("AICC_GATEWAY_URL")
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME")
+
+
+def run():
+    # ① 模型池:按 model 发现集群端点并握手,托管会话。
+    # tls_verify=True(默认):校验 https 证书;网关用自签证书时改 False(直接不校验,构造时告警一次)。
+    config = {"tls_verify": True}
+
+    def build(endpoint):
+        return SessionPool(SessionFactory(base_url, api_key, ttl=60 * 60 * 8).set_config(config), 1)
+
+    with ModelPool(base_url, api_key, 60 * 60 * 8, build).set_config(config) as models:
+        # ② 每轮 HTTP 请求新建一个 Request(携带本次会话的集群端点)。
+        with models.new_request(model_name) as req:
+            # ③ 加密请求体后发给网关。
+            policy = default_policy(Protocol.OPENAI)
+            body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}]}
+            enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+            headers = {
+                "Content-Type": "application/json",
+                "X-AICC-Mode": "1",
+                "Authorization": f"Bearer {api_key}",
+                "X-AICC-Endpoint": req.endpoint,  # 带上握手时的集群端点,网关据此路由
+            }
+            r = httpx.post(gateway_url, content=enc_body, headers=headers, timeout=600)
+            if r.status_code != 200:
+                raise RuntimeError(f"gateway {r.status_code}: {r.text}")
+
+            # ④ 解密回文,打印明文回答。
+            plain = req.decrypt_response(r.content, policy)
+            print(json.loads(plain)["choices"][0]["message"]["content"])
+
+
+if __name__ == "__main__":
+    run()

tcaicc-1.4.0/doc/demo_endpoint.py

@@ -0,0 +1,53 @@
+# demo_endpoint.py —— 非流式示例(固定端点):安全会话握手 → 加密请求 → 解密回文,只打印明文。
+#
+# 环境变量(均必填,无内置默认):AICC_BASE_URL(安全会话入口)、AICC_GATEWAY_URL(LLM 网关)、AICC_API_KEY、AICC_MODEL_NAME、
+# AICC_ENDPOINT(集群端点;不经 DescribeEndpoints 发现,直接用于握手与数据面路由)
+#
+#   python doc/demo_endpoint.py
+import json
+import os
+
+import httpx
+
+from tcaicc import Protocol, SessionFactory, SessionPool, default_policy
+
+base_url = os.getenv("AICC_BASE_URL")
+gateway_url = os.getenv("AICC_GATEWAY_URL")
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME")
+endpoint = os.getenv("AICC_ENDPOINT")
+
+
+def run():
+    # ① 会话池:工厂固定集群端点,握手时带 X-AICC-Endpoint 头,托管会话。
+    # tls_verify=True(默认):校验 https 证书;网关用自签证书时改 False(直接不校验,构造时告警一次)。
+    factory = (
+        SessionFactory(base_url, api_key, ttl=60 * 60 * 8)
+        .set_config({"tls_verify": True})
+        .set_endpoint(endpoint)
+    )
+
+    with SessionPool(factory, 1) as sessions:
+        # ② 每轮 HTTP 请求新建一个 Request(携带本次会话的集群端点)。
+        with sessions.new_request() as req:
+            # ③ 加密请求体后发给网关。
+            policy = default_policy(Protocol.OPENAI)
+            body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}]}
+            enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+            headers = {
+                "Content-Type": "application/json",
+                "X-AICC-Mode": "1",
+                "Authorization": f"Bearer {api_key}",
+                "X-AICC-Endpoint": req.endpoint,  # 带上握手时的集群端点,网关据此路由
+            }
+            r = httpx.post(gateway_url, content=enc_body, headers=headers, timeout=600)
+            if r.status_code != 200:
+                raise RuntimeError(f"gateway {r.status_code}: {r.text}")
+
+            # ④ 解密回文,打印明文回答。
+            plain = req.decrypt_response(r.content, policy)
+            print(json.loads(plain)["choices"][0]["message"]["content"])
+
+
+if __name__ == "__main__":
+    run()

tcaicc-1.4.0/doc/demo_endpoint_stream.py

@@ -0,0 +1,67 @@
+# demo_endpoint_stream.py —— 流式示例(固定端点):安全会话握手 → 加密请求 → 逐 SSE 事件解密,只打印明文。
+#
+# 环境变量(均必填,无内置默认):AICC_BASE_URL(安全会话入口)、AICC_GATEWAY_URL(LLM 网关)、AICC_API_KEY、AICC_MODEL_NAME、
+# AICC_ENDPOINT(集群端点;不经 DescribeEndpoints 发现,直接用于握手与数据面路由)
+#
+#   python doc/demo_endpoint_stream.py
+import json
+import os
+
+import httpx
+
+from tcaicc import Protocol, SessionFactory, SessionPool, default_policy
+
+base_url = os.getenv("AICC_BASE_URL")
+gateway_url = os.getenv("AICC_GATEWAY_URL")
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME")
+endpoint = os.getenv("AICC_ENDPOINT")
+
+
+def run():
+    # ① 会话池:工厂固定集群端点,握手时带 X-AICC-Endpoint 头,托管会话。
+    # tls_verify=True(默认):校验 https 证书;网关用自签证书时改 False(直接不校验,构造时告警一次)。
+    factory = (
+        SessionFactory(base_url, api_key, ttl=60 * 60 * 8)
+        .set_config({"tls_verify": True})
+        .set_endpoint(endpoint)
+    )
+
+    with SessionPool(factory, 1) as sessions:
+        # ② 每轮 HTTP 请求新建一个 Request(携带本次会话的集群端点)。
+        with sessions.new_request() as req:
+            # ③ 加密请求体(stream=true)后发给网关。
+            policy = default_policy(Protocol.OPENAI)
+            body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}], "stream": True}
+            enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+            headers = {
+                "Content-Type": "application/json",
+                "Accept": "text/event-stream",
+                "X-AICC-Mode": "1",
+                "Authorization": f"Bearer {api_key}",
+                "X-AICC-Endpoint": req.endpoint,  # 带上握手时的集群端点,网关据此路由
+            }
+            timeout = httpx.Timeout(600, read=None)
+            with httpx.stream("POST", gateway_url, content=enc_body, headers=headers, timeout=timeout) as r:
+                if r.status_code != 200:
+                    raise RuntimeError(f"gateway {r.status_code}: {r.read().decode()}")
+
+                # ④ 逐个 SSE 事件解密,打印增量明文。
+                sd = req.new_stream_decryptor()
+                for line in r.iter_lines():
+                    if not line.startswith("data: "):
+                        continue
+                    data = line[len("data: "):]
+                    if data == "[DONE]":
+                        break
+                    plain, is_last = sd.decrypt_event(data.encode(), policy)
+                    choices = json.loads(plain).get("choices") if plain else None
+                    if choices:
+                        print(choices[0].get("delta", {}).get("content") or "", end="", flush=True)
+                    if is_last:
+                        break
+            print()
+
+
+if __name__ == "__main__":
+    run()

tcaicc-1.4.0/doc/demo_stream.py

@@ -0,0 +1,64 @@
+# demo_stream.py —— 流式示例(ModelPool 按 model 发现端点):安全会话握手 → 加密请求 → 逐 SSE 事件解密,只打印明文。
+#
+# 环境变量(均必填,无内置默认):AICC_BASE_URL(安全会话入口)、AICC_GATEWAY_URL(LLM 网关)、AICC_API_KEY、AICC_MODEL_NAME
+#
+#   python doc/demo_stream.py
+import json
+import os
+
+import httpx
+
+from tcaicc import ModelPool, Protocol, SessionFactory, SessionPool, default_policy
+
+base_url = os.getenv("AICC_BASE_URL")
+gateway_url = os.getenv("AICC_GATEWAY_URL")
+api_key = os.getenv("AICC_API_KEY")
+model_name = os.getenv("AICC_MODEL_NAME")
+
+
+def run():
+    # ① 模型池:按 model 发现集群端点并握手,托管会话。
+    # tls_verify=True(默认):校验 https 证书;网关用自签证书时改 False(直接不校验,构造时告警一次)。
+    config = {"tls_verify": True}
+
+    def build(endpoint):
+        return SessionPool(SessionFactory(base_url, api_key, ttl=60 * 60 * 8).set_config(config), 1)
+
+    with ModelPool(base_url, api_key, 60 * 60 * 8, build).set_config(config) as models:
+        # ② 每轮 HTTP 请求新建一个 Request(携带本次会话的集群端点)。
+        with models.new_request(model_name) as req:
+            # ③ 加密请求体(stream=true)后发给网关。
+            policy = default_policy(Protocol.OPENAI)
+            body = {"model": model_name, "messages": [{"role": "user", "content": "你好"}], "stream": True}
+            enc_body = req.encrypt_request(json.dumps(body).encode(), policy)
+            headers = {
+                "Content-Type": "application/json",
+                "Accept": "text/event-stream",
+                "X-AICC-Mode": "1",
+                "Authorization": f"Bearer {api_key}",
+                "X-AICC-Endpoint": req.endpoint,  # 带上握手时的集群端点,网关据此路由
+            }
+            timeout = httpx.Timeout(600, read=None)
+            with httpx.stream("POST", gateway_url, content=enc_body, headers=headers, timeout=timeout) as r:
+                if r.status_code != 200:
+                    raise RuntimeError(f"gateway {r.status_code}: {r.read().decode()}")
+
+                # ④ 逐个 SSE 事件解密,打印增量明文。
+                sd = req.new_stream_decryptor()
+                for line in r.iter_lines():
+                    if not line.startswith("data: "):
+                        continue
+                    data = line[len("data: "):]
+                    if data == "[DONE]":
+                        break
+                    plain, is_last = sd.decrypt_event(data.encode(), policy)
+                    choices = json.loads(plain).get("choices") if plain else None
+                    if choices:
+                        print(choices[0].get("delta", {}).get("content") or "", end="", flush=True)
+                    if is_last:
+                        break
+            print()
+
+
+if __name__ == "__main__":
+    run()

tcaicc-1.4.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tcaicc"
+version = "1.4.0"
+description = "Tencent AICC confidential-model SDK for Python"
+readme = "README.md"
+license = "LicenseRef-Proprietary"
+license-files = ["THIRD_PARTY_NOTICES"]
+requires-python = ">=3.10"
+authors = [{ name = "Tencent" }]
+keywords = [
+    "aicc",
+    "confidential-computing",
+    "remote-attestation",
+    "sev-snp",
+    "ml-kem",
+    "encryption",
+    "tencent",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "cryptography>=48",
+    "httpx>=0.27",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.16"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tcaicc"]
+
+# sdist 用白名单:只收源码、权威 demo 与元数据,工作树里的 tests/release/脚本/html 一律不进。
+# doc/*.html 是网页文档(另行发布),不进发行包。
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "/src/tcaicc",
+    "/doc/demo.py",
+    "/doc/demo_stream.py",
+    "/doc/demo_endpoint.py",
+    "/doc/demo_endpoint_stream.py",
+    "/README.md",
+    "/THIRD_PARTY_NOTICES",
+    "/pyproject.toml",
+]
+exclude = ["__pycache__", "*.py[cod]"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests", "scripts"]
+extend-exclude = ["doc/examples", ".venv"]
+
+[tool.ruff.lint]
+# 选用对 SDK 友好的规则集:
+#   E/W  pycodestyle(基础风格)
+#   F    pyflakes(未用导入/变量等真实缺陷)
+#   I    isort(导入排序)
+#   UP   pyupgrade(现代语法;future-annotations 下移除多余引号)
+#   B    bugbear(常见 bug,含 BLE001 盲 except)
+#   SIM  simplify
+#   C4   comprehensions
+#   RUF  ruff 专有(__all__/__slots__ 排序等)
+#   PIE  杂项清理
+#   ISC  隐式字符串拼接
+select = ["E", "W", "F", "I", "UP", "B", "SIM", "C4", "RUF", "PIE", "ISC"]
+ignore = [
+  "E501",   # 不强制行长;超长多为长字符串/URL/对齐注释,手动折行取舍
+  "B008",   # 函数默认值里调用函数(测试 fixture 常见)
+  "SIM117", # 嵌套 try/with 合并有时降低可读性
+  # 代码注释/文档大量使用中文全角标点(，。×– 等),RUF001/002/003 会误报为歧义字符。
+  "RUF001", "RUF002", "RUF003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# 测试中 broad except 配 pytest.fail 是惯用法。
+"tests/*" = ["BLE001"]
+# 包 __init__.py 的 __all__ 按模块分组(带注释),刻意不按字母序。
+"src/tcaicc/**/__init__.py" = ["RUF022"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["tcaicc"]
+combine-as-imports = true
+
+# 本项目只启用 ruff lint,不启用 ruff format(保留手工列对齐等刻意风格)。
+# 不要对 src/tests/scripts 运行 `ruff format`,会重排 35+ 文件并破坏对齐注释。

tcaicc-1.4.0/src/tcaicc/__init__.py

@@ -0,0 +1,121 @@
+__version__ = "1.4.0"
+
+from .common.cipherx import (
+    ChunkDecryptor,
+    ChunkEncryptor,
+    CipherType,
+    CipherTypeError,
+    CipherxError,
+    DecryptError,
+    Envelope,
+    FormatError,
+    HashMismatchError,
+    KeySizeError,
+    Metadata,
+    StreamClosedError,
+    StreamVerifyError,
+    TooLargeError,
+    compute_prefix,
+    encrypt_prompt,
+    encrypt_response,
+    parse,
+)
+from .common.cryptox import (
+    CryptoxError,
+    DecryptError as CryptoxDecryptError,
+    HybridEphemeral,
+    HybridShare,
+    constant_time_equal,
+    derive_dek,
+    encode_lp,
+    hkdf_expand,
+    hkdf_extract,
+    hmac_sha256,
+    open_,
+    open_base64,
+    random_nonce,
+    respond_hybrid_exchange,
+    seal,
+    seal_base64,
+    zero,
+)
+from .common.security import (
+    ENDPOINT_NOT_FOUND,
+    FLAG_PROMPT_LONG,
+    FLAG_PROMPT_SHORT,
+    NO_ENDPOINT,
+    TLS_INSECURE,
+    TLS_NONE,
+    TLS_TLS,
+    ClosedError,
+    CreateResult,
+    CryptoError,
+    DeriveResult,
+    EncodingError,
+    EndpointNotFoundError,
+    EndpointPool,
+    HttpClient,
+    HttpTransportResponse,
+    ImportResult,
+    InsecureTLSWarning,
+    KeyGeneratorError,
+    KeySizeError as CryptoKeySizeError,
+    Logger,
+    LogLevel,
+    ModelPool,
+    NoEndpointError,
+    Policy,
+    Protocol,
+    Request,
+    SecuritySession,
+    SecuritySessionError,
+    SessionFactory,
+    SessionIDError,
+    SessionPool,
+    StreamDecryptor,
+    TimeoutException,
+    TlsMode,
+    Transport,
+    TransportError,
+    TransportRequest,
+    TransportResponse,
+    binding_key,
+    build_ssl_context,
+    default_policy,
+    describe_endpoints,
+    detect_envelope,
+    set_log_level,
+    set_logger,
+)
+
+__all__ = [
+    "__version__",
+    # cryptox(低层原语)
+    "CryptoxError", "CryptoxDecryptError", "HybridEphemeral", "HybridShare",
+    "constant_time_equal", "derive_dek", "encode_lp", "hkdf_expand", "hkdf_extract",
+    "hmac_sha256", "open_", "open_base64", "random_nonce",
+    "respond_hybrid_exchange", "seal", "seal_base64", "zero",
+    # cipherx(信封格式)
+    "CipherxError", "KeySizeError", "FormatError", "TooLargeError", "DecryptError",
+    "HashMismatchError", "CipherTypeError", "StreamClosedError", "StreamVerifyError",
+    "encrypt_prompt", "encrypt_response", "parse",
+    "ChunkEncryptor", "ChunkDecryptor", "Envelope", "Metadata", "CipherType",
+    "compute_prefix",
+    # 数据面加解密客户端
+    "CryptoError", "CryptoKeySizeError", "SessionIDError", "ClosedError", "EncodingError",
+    "Request", "StreamDecryptor", "detect_envelope",
+    "Policy", "Protocol", "default_policy",
+    # 传输(TLS 形态由 base_url scheme 决定,无 mTLS)
+    "HttpClient", "TransportResponse", "TransportRequest", "Transport",
+    "HttpTransportResponse", "InsecureTLSWarning", "build_ssl_context", "TlsMode",
+    "TLS_TLS", "TLS_INSECURE", "TLS_NONE",
+    # 安全会话
+    "SessionFactory", "SessionPool", "SecuritySession",
+    "EndpointPool", "ModelPool", "describe_endpoints", "binding_key",
+    "FLAG_PROMPT_SHORT", "FLAG_PROMPT_LONG",
+    "EndpointNotFoundError", "NoEndpointError", "ENDPOINT_NOT_FOUND", "NO_ENDPOINT",
+    "CreateResult", "ImportResult", "DeriveResult",
+    "SecuritySessionError", "TransportError", "TimeoutException", "KeyGeneratorError",
+    # 进程级日志(四级阈值,默认 error 即零输出)
+    "set_logger", "set_log_level", "LogLevel", "Logger",
+]

tcaicc-1.4.0/src/tcaicc/common/__init__.py

@@ -0,0 +1 @@
+"""common 共享子包。"""