sqlseed-ai 0.2.4__tar.gz → 0.2.6__tar.gz

{sqlseed_ai-0.2.4 → sqlseed_ai-0.2.6}/.gitignore

@@ -59,6 +59,16 @@ dmypy.json
 *.db
 *.sqlite
 *.sqlite3
+# SQLite runtime sidecars
+*.db-wal
+*.db-shm
+*.db-journal
+*.sqlite-wal
+*.sqlite-shm
+*.sqlite-journal
+*.sqlite3-wal
+*.sqlite3-shm
+*.sqlite3-journal
 .sqlseed_cache/
 snapshots/
 .env

{sqlseed_ai-0.2.4 → sqlseed_ai-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlseed-ai
-Version: 0.2.4
+Version: 0.2.6
 Summary: Optional LLM schema analysis and contract-driven configuration repair for sqlseed
 Project-URL: Documentation, https://sunbos.github.io/sqlseed/gemma4-integration/
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
@@ -18,9 +18,9 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: networkx>=3.0
-Requires-Dist: openai>=1.0
+Requires-Dist: openai>=1.55.3
 Requires-Dist: sqlseed-cli<0.3,>=0.2.4.dev0
-Requires-Dist: sqlseed<0.3,>=0.2.4.dev0
+Requires-Dist: sqlseed<0.3,>=0.2.5.dev0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
@@ -46,13 +46,15 @@ backend test; installing the plugin does not perform one.
 
 ## Installation
 
-For the 0.2.4 release, use a Python 3.10+ virtual environment:
+These instructions target version 0.2.6. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+for publication status; use the source installation below to test an unpublished candidate.
+Use a Python 3.10+ virtual environment:
 
 ```bash
-python -m pip install "sqlseed-ai==0.2.4"
+python -m pip install "sqlseed-ai==0.2.6"
 ```
 
-Core 0.2.3 lacks the plugin hooks and target-validation interfaces used here.
+Core 0.2.4 and older lack the shared diagnostic interfaces required by this version.
 For development, install Core and the required local plugins together from the
 repository root:
 
@@ -100,6 +102,28 @@ names fail before output is written. `--merge` requires `--output`; it replaces
 selected tables, retains existing dependency and unrelated tables plus root settings,
 and appends missing generated tables.
 
+Single-table `ai-suggest` checks that the target exists before contacting the
+model. Suggestions and cached results must name that same table, including when
+using `--no-verify` or `--max-retries 0`. SQLite case aliases remain supported;
+export preserves real table and column names, including leading punctuation.
+Rejected suggestions leave existing output files unchanged.
+
+The prompt requests one JSON object configuring only the named table, preserving
+its table and column names. Other table names are reference context, not additional
+output targets; the response still passes target validation.
+
+Direct analysis (`--no-verify` or `--max-retries 0`), streaming or non-streaming,
+reports empty replies, invalid JSON, output-limit truncation, and empty configuration
+objects separately, without
+echoing the model response in these diagnostics. It announces a retry only when
+another existing shorter-prompt level remains. Once those levels are exhausted,
+it reports the final cause and exits unsuccessfully; it does not increase the
+request budget or change the existing output YAML or database.
+
+Direct Python callers can pass `preserve_names=True` to
+`SchemaAnalyzer.call_llm()` or `call_llm_streaming()` before validating against
+their schema. The default retains the existing leading-punctuation cleanup.
+
 `auto-heal --config` reads that document. An explicit `--db` or `--url` selects the
 output connection. Invalid YAML, configuration structure, or unknown input tables
 fail without replacing the output file. Candidate repairs are checked for config
@@ -112,7 +136,7 @@ actual generated values and database constraints.
 The AI MCP entry point requires the `mcp` extra:
 
 ```bash
-python -m pip install "sqlseed-ai[mcp]==0.2.4"
+python -m pip install "sqlseed-ai[mcp]==0.2.6"
 mcp-server-sqlseed-ai
 ```
 
@@ -145,15 +169,57 @@ explicit backend, then known URL patterns, then OpenAI-compatible behavior. It d
 not probe every service as a fallback chain. The `tool_calling_protocol` setting and
 its resolver choose the response protocol; a model name alone is insufficient.
 
-AI configuration caches include schema hashes. Schema changes invalidate cached
-suggestions; `--no-cache` bypasses them. Review model output before writing data.
+AI requests to `localhost` and loopback IP addresses connect directly even when
+an HTTP proxy is configured. Remote services keep the environment proxy settings;
+`SSL_CERT_FILE` and `SSL_CERT_DIR` remain effective for HTTPS certificate validation.
+
+For Python callers, `SchemaAnalyzer.call_llm(..., strict_json=True)` and
+`call_llm_streaming(..., strict_json=True)` distinguish empty replies, invalid JSON,
+and output-limit truncation using content-free `JSONResponseError.code` values.
+JSON parsing can complete missing final `}` or `]`
+delimiters, including inside code fences, but never fills missing values or strings.
+An output-limit response is rejected even if its prefix parses, including a streaming
+length marker in a separate empty terminal chunk. Both methods default to
+`strict_json=False`. Strict local calls request JSON sampling constraints: LM Studio
+uses its JSON-schema grammar interface, and Ollama uses JSON object mode. A server
+that explicitly rejects the format gets one text-mode compatibility attempt;
+the same strict parser still rejects invalid or truncated output. The CLI's direct
+path and both refiner modes keep their existing prompt/refinement retry budgets.
+Strict tool calling also rejects arrays, scalars and `null` arguments as `invalid_json`;
+compatibility mode may still fall back to response text. Parsed suggestions still
+require scope and rule validation.
+
+Single-table suggestion caches use a versioned hash of sorted column names, encoded
+as a JSON array so names containing delimiters remain distinct. The check detects
+added, removed, or renamed columns; column order, types, and constraints are not
+included. Caches using the older delimiter encoding are ignored and regenerated.
+Use `--no-cache` to analyze again without cached suggestions. This cache check is
+separate from AutoHeal's full schema fingerprint. Malformed cache metadata
+or configuration containers are treated as cache misses. Review model output before
+writing data.
+
+## Hardware estimates on macOS
+
+The AI MCP model list distinguishes Apple unified memory, Intel shared graphics
+memory, and dedicated GPU memory. Apple unified RAM is not reported as dedicated
+VRAM or added to system RAM. `unified_memory_budget_gb` is a static heuristic:
+`max(0, min(total_ram_gb * 0.75, total_ram_gb - 4))`, reserving at least 4 GiB or
+25% for the system. It is not measured free memory or a Metal allocation limit.
+
+For an identified Apple GPU on macOS, model screening compares that budget with
+both existing minimum RAM and VRAM estimates and reports at most `capable`.
+This does not verify Metal acceleration, backend/model support, or successful
+inference; loaded applications and context size can require more memory.
 
 ## Requirements
 
+These metadata requirements apply to version 0.2.6 and its source candidates.
+Use local Core and plugins together when developing from source.
+
 - Python `>=3.10`
-- `sqlseed>=0.2.4.dev0,<0.3`
+- `sqlseed>=0.2.5.dev0,<0.3`
 - `sqlseed-cli>=0.2.4.dev0,<0.3`
-- `openai>=1.0`
+- `openai>=1.55.3` (SDK transport defaults with HTTPX 0.28 compatibility)
 - `httpx>=0.24.0`
 - `networkx>=3.0`
 - Optional `mcp` extra: `mcp>=1.0,<2`

{sqlseed_ai-0.2.4 → sqlseed_ai-0.2.6}/README.md

@@ -14,13 +14,15 @@ backend test; installing the plugin does not perform one.
 
 ## Installation
 
-For the 0.2.4 release, use a Python 3.10+ virtual environment:
+These instructions target version 0.2.6. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+for publication status; use the source installation below to test an unpublished candidate.
+Use a Python 3.10+ virtual environment:
 
 ```bash
-python -m pip install "sqlseed-ai==0.2.4"
+python -m pip install "sqlseed-ai==0.2.6"
 ```
 
-Core 0.2.3 lacks the plugin hooks and target-validation interfaces used here.
+Core 0.2.4 and older lack the shared diagnostic interfaces required by this version.
 For development, install Core and the required local plugins together from the
 repository root:
 
@@ -68,6 +70,28 @@ names fail before output is written. `--merge` requires `--output`; it replaces
 selected tables, retains existing dependency and unrelated tables plus root settings,
 and appends missing generated tables.
 
+Single-table `ai-suggest` checks that the target exists before contacting the
+model. Suggestions and cached results must name that same table, including when
+using `--no-verify` or `--max-retries 0`. SQLite case aliases remain supported;
+export preserves real table and column names, including leading punctuation.
+Rejected suggestions leave existing output files unchanged.
+
+The prompt requests one JSON object configuring only the named table, preserving
+its table and column names. Other table names are reference context, not additional
+output targets; the response still passes target validation.
+
+Direct analysis (`--no-verify` or `--max-retries 0`), streaming or non-streaming,
+reports empty replies, invalid JSON, output-limit truncation, and empty configuration
+objects separately, without
+echoing the model response in these diagnostics. It announces a retry only when
+another existing shorter-prompt level remains. Once those levels are exhausted,
+it reports the final cause and exits unsuccessfully; it does not increase the
+request budget or change the existing output YAML or database.
+
+Direct Python callers can pass `preserve_names=True` to
+`SchemaAnalyzer.call_llm()` or `call_llm_streaming()` before validating against
+their schema. The default retains the existing leading-punctuation cleanup.
+
 `auto-heal --config` reads that document. An explicit `--db` or `--url` selects the
 output connection. Invalid YAML, configuration structure, or unknown input tables
 fail without replacing the output file. Candidate repairs are checked for config
@@ -80,7 +104,7 @@ actual generated values and database constraints.
 The AI MCP entry point requires the `mcp` extra:
 
 ```bash
-python -m pip install "sqlseed-ai[mcp]==0.2.4"
+python -m pip install "sqlseed-ai[mcp]==0.2.6"
 mcp-server-sqlseed-ai
 ```
 
@@ -113,15 +137,57 @@ explicit backend, then known URL patterns, then OpenAI-compatible behavior. It d
 not probe every service as a fallback chain. The `tool_calling_protocol` setting and
 its resolver choose the response protocol; a model name alone is insufficient.
 
-AI configuration caches include schema hashes. Schema changes invalidate cached
-suggestions; `--no-cache` bypasses them. Review model output before writing data.
+AI requests to `localhost` and loopback IP addresses connect directly even when
+an HTTP proxy is configured. Remote services keep the environment proxy settings;
+`SSL_CERT_FILE` and `SSL_CERT_DIR` remain effective for HTTPS certificate validation.
+
+For Python callers, `SchemaAnalyzer.call_llm(..., strict_json=True)` and
+`call_llm_streaming(..., strict_json=True)` distinguish empty replies, invalid JSON,
+and output-limit truncation using content-free `JSONResponseError.code` values.
+JSON parsing can complete missing final `}` or `]`
+delimiters, including inside code fences, but never fills missing values or strings.
+An output-limit response is rejected even if its prefix parses, including a streaming
+length marker in a separate empty terminal chunk. Both methods default to
+`strict_json=False`. Strict local calls request JSON sampling constraints: LM Studio
+uses its JSON-schema grammar interface, and Ollama uses JSON object mode. A server
+that explicitly rejects the format gets one text-mode compatibility attempt;
+the same strict parser still rejects invalid or truncated output. The CLI's direct
+path and both refiner modes keep their existing prompt/refinement retry budgets.
+Strict tool calling also rejects arrays, scalars and `null` arguments as `invalid_json`;
+compatibility mode may still fall back to response text. Parsed suggestions still
+require scope and rule validation.
+
+Single-table suggestion caches use a versioned hash of sorted column names, encoded
+as a JSON array so names containing delimiters remain distinct. The check detects
+added, removed, or renamed columns; column order, types, and constraints are not
+included. Caches using the older delimiter encoding are ignored and regenerated.
+Use `--no-cache` to analyze again without cached suggestions. This cache check is
+separate from AutoHeal's full schema fingerprint. Malformed cache metadata
+or configuration containers are treated as cache misses. Review model output before
+writing data.
+
+## Hardware estimates on macOS
+
+The AI MCP model list distinguishes Apple unified memory, Intel shared graphics
+memory, and dedicated GPU memory. Apple unified RAM is not reported as dedicated
+VRAM or added to system RAM. `unified_memory_budget_gb` is a static heuristic:
+`max(0, min(total_ram_gb * 0.75, total_ram_gb - 4))`, reserving at least 4 GiB or
+25% for the system. It is not measured free memory or a Metal allocation limit.
+
+For an identified Apple GPU on macOS, model screening compares that budget with
+both existing minimum RAM and VRAM estimates and reports at most `capable`.
+This does not verify Metal acceleration, backend/model support, or successful
+inference; loaded applications and context size can require more memory.
 
 ## Requirements
 
+These metadata requirements apply to version 0.2.6 and its source candidates.
+Use local Core and plugins together when developing from source.
+
 - Python `>=3.10`
-- `sqlseed>=0.2.4.dev0,<0.3`
+- `sqlseed>=0.2.5.dev0,<0.3`
 - `sqlseed-cli>=0.2.4.dev0,<0.3`
-- `openai>=1.0`
+- `openai>=1.55.3` (SDK transport defaults with HTTPX 0.28 compatibility)
 - `httpx>=0.24.0`
 - `networkx>=3.0`
 - Optional `mcp` extra: `mcp>=1.0,<2`

{sqlseed_ai-0.2.4 → sqlseed_ai-0.2.6}/README.zh-CN.md

@@ -3,7 +3,7 @@
 [English](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/README.md) |
 **[中文](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/README.zh-CN.md)**
 
-[sqlseed](https://sunbos.github.io/sqlseed/) 的可选 LLM Schema 分析与契约驱动配置修复插件。
+[sqlseed](https://sunbos.github.io/sqlseed/zh-CN/) 的可选 LLM Schema 分析与契约驱动配置修复插件。
 提供列规则建议、配置校验与修复，以及模板候选值生成。接受的配置可交由 Core 离线执行。
 
 支持 Google AI Studio、LM Studio、Ollama 和 OpenAI-compatible API 后端。
@@ -11,13 +11,13 @@
 
 ## 安装
 
-安装 0.2.4 版本时，使用 Python 3.10+ 虚拟环境：
+本文安装说明对应 0.2.6 版本；发布状态以 [Releases](https://github.com/sunbos/sqlseed/releases) 为准。测试尚未发布的候选版本时，使用下方的源码安装方式。请先创建并激活 Python 3.10+ 虚拟环境：
 
 ```bash
-python -m pip install "sqlseed-ai==0.2.4"
+python -m pip install "sqlseed-ai==0.2.6"
 ```
 
-Core 0.2.3 缺少本插件使用的 hooks 与数据库目标校验接口。
+Core 0.2.4 及更早版本缺少本版本使用的共享诊断接口。
 开发源码时，从仓库根一次安装本地 Core、CLI 和 AI：
 
 ```bash
@@ -91,7 +91,7 @@ native/custom 方法、实际生成值及依赖数据库状态的约束需另行
 AI MCP 入口要求本包的 `mcp` extra：
 
 ```bash
-python -m pip install "sqlseed-ai[mcp]==0.2.4"
+python -m pip install "sqlseed-ai[mcp]==0.2.6"
 mcp-server-sqlseed-ai
 ```
 
@@ -114,6 +114,9 @@ mcp-server-sqlseed-ai
 后端解析顺序是显式 `SQLSEED_AI_BACKEND`、已知 URL 模式、最后 `openai_compat`。
 这不是逐个探测所有服务的 fallback 链。
 
+AI 请求访问 `localhost` 或回环 IP 地址时直接连接，不经过环境代理；远程服务仍使用
+原有代理配置。HTTPS 证书校验继续遵循 `SSL_CERT_FILE` 和 `SSL_CERT_DIR`。
+
 | 变量 | 用途 |
 | --- | --- |
 | `SQLSEED_AI_BACKEND` | `google_ai_studio`、`lm_studio`、`ollama` 或 `openai_compat` |
@@ -148,6 +151,33 @@ Gemma 26B ID。注册的模型名称不保证服务当前提供该模型，请
 修正；默认最多重试 3 次，仍失败时报告 `AISuggestionFailedError`。
 `ai-analyze` 和 `auto-heal` 则使用 v4 `AutoHealOrchestrator` 的契约驱动路径。
 
+单表 `ai-suggest` 在请求模型前检查目标表是否存在；建议与缓存必须指向同一张表。
+`--no-verify` 和 `--max-retries 0` 只跳过生成校验，仍保留目标保护。
+SQLite 表名大小写别名继续可用；导出保留真实表名和列名，包括前导 `.` 或 `:`。
+拒绝的建议不会覆盖已有输出文件。
+
+Prompt 明确要求只为指定表返回一个 JSON 对象，并保留表名和列名原文。上下文中的
+其他表名只供参考，不是额外输出目标；这一提示不能替代响应后的目标校验。
+
+直接分析（`--no-verify` 或 `--max-retries 0`）的流式和非流式路径均分别说明空回答、无效 JSON、输出长度
+截断和空配置对象，这些诊断不回显模型原文。仅在既定流程中还有更短提示层时才提示
+并继续重试；最后一层失败会报告具体原因并以失败退出，不再声称正在重试，也不增加
+请求预算。拒绝响应时，已有输出 YAML 与数据库均保持不变。
+
+Python 调用可使用 `SchemaAnalyzer.call_llm(..., strict_json=True)` 或
+`call_llm_streaming(..., strict_json=True)`，通过不含原文的
+`JSONResponseError.code` 区分空回答、无效 JSON 和输出长度截断。解析器可补齐末尾缺失的
+`}` / `]`，包括代码围栏内的 JSON，但不会补值或字符串；达到输出长度上限时，即使前缀
+可解析也会拒绝，包括流式独立空终止帧中的长度截断标记。两种 Python 方法默认均为
+`strict_json=False`。严格本地调用请求 JSON 采样约束：LM Studio 使用 JSON Schema 语法接口，
+Ollama 使用 JSON 对象模式。服务明确拒绝该格式时，只进行一次文本模式兼容请求，仍由同一
+严格解析器拒绝无效或截断输出。CLI 直接分析与 refiner 保留各自现有提示与自纠正重试预算。
+严格工具调用还会拒绝数组、标量和 `null` 参数，
+返回 `invalid_json`；兼容模式仍可回退到响应正文。解析后的建议仍需验证范围和业务规则。
+
+直接 Python 调用可给 `SchemaAnalyzer.call_llm()` 或 `call_llm_streaming()` 传入
+`preserve_names=True`，保留标识符后再按实际 schema 校验；默认仍保留既有的前导标点清理。
+
 开启 AI 生成路径时，`sqlseed_pre_generate_templates` 可为符合条件的未匹配字符串列
 准备候选值。用户明确配置、UNIQUE、默认值或主键等条件会影响是否使用模板池，
 不保证每个复杂字段都会调用模型。
@@ -164,7 +194,11 @@ Gemma 26B ID。注册的模型名称不保证服务当前提供该模型，请
 
 ### 文件缓存
 
-AI 配置缓存包含 schema hash，结构变化会使旧建议失效；`--no-cache` 跳过缓存。
+单表建议缓存使用带版本标识的 schema hash，将排序后的列名编码为 JSON 数组，
+避免含分隔符的不同列名集合混淆。校验覆盖列的增删和重命名，不包含列顺序、类型或约束。
+旧分隔符编码的缓存会被忽略并重新生成；可用 `--no-cache` 跳过缓存重新分析。
+此处的缓存校验与 AutoHeal 使用的完整 schema 指纹不同。
+缓存元数据或配置容器类型无效时，按缓存未命中重新分析。
 默认路径为 macOS 的 `~/Library/Caches/sqlseed/ai_configs/`、Linux 的
 `$XDG_CACHE_HOME/sqlseed/ai_configs/`（未设置时为 `~/.cache/sqlseed/ai_configs/`），
 以及 Windows 的 `%LOCALAPPDATA%/sqlseed/ai_configs/`。
@@ -184,19 +218,32 @@ AI 配置缓存包含 schema hash，结构变化会使旧建议失效；`--no-ca
 CLI 命令另由 `sqlseed.cli_commands` entry point 注册。本插件不实现 provider 或
 column-mapper 注册 hooks，也不要求 Core 导入 AI 实现。
 
+## macOS 硬件估算
+
+AI MCP 模型列表区分 Apple 统一内存、Intel 共享显存与独立显存。Apple 统一内存
+不会被报告为独立显存，也不会与系统 RAM 相加。`unified_memory_budget_gb` 是静态
+启发式预算：`max(0, min(total_ram_gb * 0.75, total_ram_gb - 4))`，为系统预留
+至少 4 GiB 或 25% 内存。它不是实测可用内存，也不是 Metal 分配上限。
+
+仅在 macOS 上识别出 Apple GPU 后，模型筛选才使用该预算与既有最低 RAM、VRAM
+估算同时比较，最高返回 `capable`。该结果不代表已验证 Metal 加速、后端或模型支持，
+也不保证推理成功；其他应用占用和上下文大小可能增加实际内存需求。
+
 ## 依赖
 
+以下为 0.2.6 版本及其源码候选的依赖要求。源码开发时请在同一次解析中安装本地 Core 和插件。
+
 - Python `>=3.10`
-- `sqlseed>=0.2.4.dev0,<0.3`
+- `sqlseed>=0.2.5.dev0,<0.3`
 - `sqlseed-cli>=0.2.4.dev0,<0.3`
-- `openai>=1.0`
+- `openai>=1.55.3`（保留 SDK 传输默认值并兼容 HTTPX 0.28）
 - `httpx>=0.24.0`
 - `networkx>=3.0`
 - 可选 `mcp` extra：`mcp>=1.0,<2`
 - 实际模型请求需要已配置且可达的后端
 
-更多信息见[AI 集成指南](https://sunbos.github.io/sqlseed/gemma4-integration.zh-CN/)、
-[升级说明](https://sunbos.github.io/sqlseed/migration.zh-CN/)和
+更多信息见[AI 集成指南](https://sunbos.github.io/sqlseed/zh-CN/gemma4-integration/)、
+[升级说明](https://sunbos.github.io/sqlseed/zh-CN/migration/)和
 [配置源码](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/src/sqlseed_ai/config.py)。
 
 许可证：[AGPL-3.0-or-later](https://github.com/sunbos/sqlseed/blob/main/LICENSE)。

{sqlseed_ai-0.2.4 → sqlseed_ai-0.2.6}/pyproject.toml

@@ -23,9 +23,9 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "sqlseed>=0.2.4.dev0,<0.3",
+    "sqlseed>=0.2.5.dev0,<0.3",
     "sqlseed-cli>=0.2.4.dev0,<0.3",
-    "openai>=1.0",
+    "openai>=1.55.3",
     "httpx>=0.24.0",
     "networkx>=3.0",
 ]

{sqlseed_ai-0.2.4 → sqlseed_ai-0.2.6}/src/sqlseed_ai/_client.py

@@ -7,18 +7,25 @@ unified httpx timeouts suitable for both cloud and local (GPU) inference.
 
 from __future__ import annotations
 
+from ipaddress import ip_address
+from typing import TYPE_CHECKING
+
 import httpx
-from openai import APIConnectionError, APIError, APITimeoutError, OpenAI
+from openai import APIConnectionError, APIError, APITimeoutError
 from sqlseed_ai.config import AIConfig
 
 from sqlseed._utils.logger import get_logger
 
+if TYPE_CHECKING:
+    from openai import OpenAI
+
 logger = get_logger(__name__)
 
 __all__ = [
     "APIConnectionError",
     "APIError",
     "APITimeoutError",
+    "build_openai_client",
     "get_openai_client",
     "httpx_timeout",
 ]
@@ -49,7 +56,36 @@ def get_openai_client(config: AIConfig | None = None) -> OpenAI:
     # - pool=10s: connection-pool acquisition timeout
     kwargs["timeout"] = httpx_timeout(config.resolve_timeout())
     logger.info("Creating OpenAI client", **{"backend": config.backend.value, "base_url": kwargs["base_url"]})
-    return OpenAI(**kwargs)
+    return build_openai_client(**kwargs)
+
+
+def build_openai_client(*, api_key: str, base_url: str, timeout: float | httpx.Timeout | None) -> OpenAI:
+    """Create a client with direct loopback routing and SDK transport defaults.
+
+    Exact loopback hosts bypass environment proxies. TLS certificate settings,
+    remote proxy routes, timeouts, redirects, and pool limits remain unchanged.
+    The returned SDK client owns its optional HTTP client.
+    """
+    from openai import DefaultHttpxClient, OpenAI, Timeout
+
+    resolved_timeout = Timeout(**timeout.as_dict()) if isinstance(timeout, httpx.Timeout) else timeout
+    if (host := httpx.URL(base_url).host) != "localhost":
+        try:
+            is_loopback = ip_address(host).is_loopback
+        except ValueError:
+            is_loopback = False
+    else:
+        is_loopback = True
+    if not is_loopback:
+        return OpenAI(api_key=api_key, base_url=base_url, timeout=resolved_timeout)
+
+    authority = f"[{host}]" if ":" in host else host
+    transport = DefaultHttpxClient(mounts={f"all://{authority}": None})
+    try:
+        return OpenAI(api_key=api_key, base_url=base_url, timeout=resolved_timeout, http_client=transport)
+    except BaseException:
+        transport.close()
+        raise
 
 
 def httpx_timeout(total: float) -> httpx.Timeout:

{sqlseed_ai-0.2.4 → sqlseed_ai-0.2.6}/src/sqlseed_ai/_hardware.py

@@ -11,8 +11,10 @@ from __future__ import annotations
 import ctypes
 import json
 import platform
+import re
 import subprocess
 import time
+from math import isfinite
 from typing import Any, NamedTuple
 
 from sqlseed._utils.logger import get_logger
@@ -200,8 +202,34 @@ def _detect_gpu_nvidia() -> list[dict[str, Any]]:
         return []
 
 
+def _video_memory_mb(value: object) -> int:
+    """Parse a profiler memory quantity without trusting malformed card fields."""
+    if not isinstance(value, str):
+        return 0
+    if (match := re.fullmatch(r"(\d+(?:\.\d+)?)\s*(MB|GB)", value.strip(), re.IGNORECASE)) is None:
+        return 0
+    size_mb = float(match[1]) * (1024 if match[2].upper() == "GB" else 1)
+    return int(size_mb) if isfinite(size_mb) else 0
+
+
+def _macos_gpu_memory(gpu_info: dict[str, object], vendor: str) -> tuple[str, int]:
+    """Separate shared and dedicated video memory from Apple unified RAM."""
+    if vendor == "apple":
+        return "unified", 0
+    memory_type = "shared" if "spdisplays_vram_shared" in gpu_info else "dedicated"
+    vram_mb = next(
+        (
+            size
+            for key in ("spdisplays_vram", "spdisplays_vram_shared", "_spdisplays_vram")
+            if (size := _video_memory_mb(gpu_info.get(key))) > 0
+        ),
+        0,
+    )
+    return memory_type, vram_mb
+
+
 def _detect_gpu_macos() -> list[dict[str, Any]]:
-    """Detect Apple Silicon GPU via system_profiler. macOS only."""
+    """Detect Apple, Intel and discrete GPUs via macOS system_profiler."""
     try:
         result = subprocess.run(
             ["system_profiler", "SPDisplaysDataType", "-json"],
@@ -214,26 +242,30 @@ def _detect_gpu_macos() -> list[dict[str, Any]]:
             return []
 
         data = json.loads(result.stdout)
+        if not isinstance(data, dict):
+            return []
         displays = data.get("SPDisplaysDataType", [])
+        if not isinstance(displays, list):
+            return []
         gpus: list[dict[str, Any]] = []
         for gpu_info in displays:
+            if not isinstance(gpu_info, dict):
+                continue
             name = gpu_info.get("sppci_model", "Unknown GPU")
-            vram_str = gpu_info.get("spdisplays_vram", "")
-            vram_mb = 0
-            if vram_str:
-                parts = vram_str.split()
-                if len(parts) >= 2:
-                    val = int(parts[0])
-                    unit = parts[1].upper()
-                    vram_mb = val * 1024 if "GB" in unit else val
+            if not isinstance(name, str):
+                name = "Unknown GPU"
+            vendor_label = str(gpu_info.get("spdisplays_vendor") or name).lower()
+            vendor = next((v for v in ("apple", "intel", "amd", "nvidia") if v in vendor_label), "unknown")
+            memory_type, vram_mb = _macos_gpu_memory(gpu_info, vendor)
 
             gpus.append(
                 {
                     "name": name,
                     "vram_total_mb": vram_mb,
-                    "vram_free_mb": 0,  # Apple Silicon uses unified memory; discrete VRAM is always 0
+                    "vram_free_mb": 0,  # system_profiler does not report free VRAM
                     "vram_total_gb": round(vram_mb / 1024, 1),
-                    "vendor": "apple",
+                    "vendor": vendor,
+                    "memory_type": memory_type,
                 }
             )
         return gpus
@@ -252,6 +284,13 @@ def _detect_gpus() -> list[dict[str, Any]]:
     return []
 
 
+def _has_apple_unified_memory(hw: dict[str, Any]) -> bool:
+    """Require an identified Apple GPU on macOS, including under Rosetta."""
+    return hw.get("platform", {}).get("system") == "Darwin" and any(
+        gpu.get("vendor") == "apple" and gpu.get("memory_type") == "unified" for gpu in hw.get("gpus", [])
+    )
+
+
 # ── Public API ───────────────────────────────────────────────────────
 
 
@@ -262,7 +301,8 @@ def detect_hardware() -> dict[str, Any]:
         platform: {system, release, machine}
         ram: {total_gb, available_gb}
         gpus: [{name, vram_total_mb, vram_free_mb, vram_total_gb, vendor, ...}]
-        max_vram_gb: float  (max VRAM across all GPUs, 0 if no GPU)
+        max_vram_gb: float (largest reported non-unified VRAM quantity)
+        unified_memory_budget_gb: float (heuristic budget, not measured free VRAM)
     """
     if _HardwareCache.data is not None:
         cached_time, cached_result = _HardwareCache.data
@@ -271,9 +311,9 @@ def detect_hardware() -> dict[str, Any]:
 
     ram = _detect_system_ram()
     gpus = _detect_gpus()
-    max_vram = max((g.get("vram_total_gb", 0) for g in gpus), default=0)
+    max_vram = max((g.get("vram_total_gb", 0) for g in gpus if g.get("memory_type") != "unified"), default=0)
 
-    result = {
+    result: dict[str, Any] = {
         "platform": {
             "system": platform.system(),
             "release": platform.release(),
@@ -282,7 +322,13 @@ def detect_hardware() -> dict[str, Any]:
         "ram": ram,
         "gpus": gpus,
         "max_vram_gb": max_vram,
+        "unified_memory_budget_gb": 0.0,
     }
+    if _has_apple_unified_memory(result):
+        # A static screening heuristic, not Metal's runtime allocation limit.
+        # Reserve at least 4 GiB / 25% for the OS and other applications.
+        total_ram = ram["total_gb"]
+        result["unified_memory_budget_gb"] = max(0.0, min(total_ram * 0.75, total_ram - 4.0))
 
     _HardwareCache.data = (time.monotonic(), result)
     logger.info(
@@ -340,6 +386,11 @@ def evaluate_model_status(
         return "recommended"
     if max_vram >= req.min_vram_gb:
         return "capable"
+    if _has_apple_unified_memory(hw):
+        budget = hw.get("unified_memory_budget_gb", 0)
+        # RAM and GPU allocations share this budget; never add them or grant
+        # a recommendation without verifying the backend and actual model.
+        return "capable" if budget >= max(req.min_ram_gb, req.min_vram_gb) else "insufficient"
     if total_ram >= req.min_ram_gb and max_vram == 0:
         return "cpu_only"
     if total_ram >= req.min_ram_gb: