py2wl 0.6.1__tar.gz

py2wl-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026.3.3] [TurinFohlen]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py2wl-0.6.1/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: py2wl
+Version: 0.6.1
+Summary: Python → Wolfram Language bridge via PTY, with compat layer for NumPy/SciPy/pandas/PyTorch etc.
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: pexpect
+Requires-Dist: pyyaml
+Provides-Extra: wxf
+Requires-Dist: wolframclient>=1.4.0; extra == "wxf"
+Provides-Extra: ai
+Requires-Dist: requests; extra == "ai"
+Dynamic: license-file

py2wl-0.6.1/README.md

@@ -0,0 +1 @@
+# py2wl - Python to Wolfram Bridge

py2wl-0.6.1/py2wl/__init__.py

@@ -0,0 +1,13 @@
+"""py2wl 包（懒加载核心，避免在没有 pexpect 的环境爆炸）"""
+
+def __getattr__(name):
+    if name == "WolframKernel":
+        from .kernel import WolframKernel
+        import sys
+        sys.modules[__name__].WolframKernel = WolframKernel
+        return WolframKernel
+    if name == "WolframPipeline":
+        # WolframPipeline 已在 WSTP 版本中移除，保留兼容名避免 ImportError
+        raise AttributeError(
+            "WolframPipeline 已移除，请直接使用 WolframKernel.evaluate()")
+    raise AttributeError(f"module 'py2wl' has no attribute {name!r}")

py2wl-0.6.1/py2wl/compat/__init__.py

@@ -0,0 +1,13 @@
+"""
+py2wl.compat
+---------------------
+NumPy/SciPy 兼容层入口。
+
+用法：
+    from py2wl.compat import numpy as np
+    result = np.fft.fft([1, 2, 3, 4])
+"""
+from . import numpy
+from ._core.converters import register_input_converter, register_output_converter
+
+__all__ = ["numpy", "register_input_converter", "register_output_converter"]

py2wl-0.6.1/py2wl/compat/_core/ai_plugin.py

@@ -0,0 +1,133 @@
+"""
+compat/_core/ai_plugin.py
+--------------------------
+AI 插件：当 YAML 映射表找不到规则时，由 AI 给出 Wolfram 函数名建议；
+也用于容错系统的候选重排（candidate_finder.py）。
+
+环境变量：
+  AI_PROVIDER          = deepseek | claude | gemini | groq  （默认 deepseek）
+  DEEPSEEK_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY / GROQ_API_KEY
+  WOLFRAM_AI_PLUGIN    = 1   （必须设置才启用，避免意外网络调用）
+"""
+
+import os
+import importlib
+import pkgutil
+import logging
+from typing import Optional
+
+log = logging.getLogger("py2wl.compat")
+
+_PROVIDERS_PKG = "py2wl.compat._core.ai_providers"
+_HARDCODED_MAP = {
+    "deepseek": "DeepSeekProvider",
+    "claude":   "ClaudeProvider",
+    "gemini":   "GeminiProvider",
+    "groq":     "GroqProvider",
+}
+_ENV_KEY_MAP = {
+    "deepseek": "DEEPSEEK_API_KEY",
+    "claude":   "ANTHROPIC_API_KEY",
+    "gemini":   "GOOGLE_API_KEY",
+    "groq":     "GROQ_API_KEY",
+}
+
+
+class AIPlugin:
+    def __init__(self, api_key: str = None, provider_name: str = None):
+        self._name     = (provider_name or os.getenv("AI_PROVIDER", "deepseek")).lower()
+        self._api_key  = api_key
+        self._provider = None
+
+    def _ensure_provider(self) -> bool:
+        if self._provider is not None:
+            return True
+
+        pkg = importlib.import_module(_PROVIDERS_PKG)
+        dynamic = {
+            m: m.capitalize() + "Provider"
+            for _, m, _ in pkgutil.iter_modules(pkg.__path__)
+            if m not in ("__init__", "base")
+        }
+        full_map = {**dynamic, **_HARDCODED_MAP}
+
+        if self._name not in full_map:
+            log.warning(f"未知 AI 提供商：{self._name}，可用：{list(full_map)}")
+            return False
+
+        if not self._api_key:
+            env = _ENV_KEY_MAP.get(self._name, self._name.upper() + "_API_KEY")
+            self._api_key = os.getenv(env)
+        if not self._api_key:
+            log.warning(f"未找到 {self._name} API Key，AI 插件已禁用")
+            return False
+
+        try:
+            mod = importlib.import_module(f"{_PROVIDERS_PKG}.{self._name}")
+            self._provider = getattr(mod, full_map[self._name])(api_key=self._api_key)
+            log.info(f"AI 插件就绪：{self._name} / {self._provider.model}")
+            return True
+        except Exception as e:
+            log.warning(f"加载 AI 提供商失败：{e}")
+            return False
+
+    # ── 主功能 1：推断 Wolfram 函数名 ───────────────────────────
+    def suggest_mapping(self, python_path: str,
+                        context: str = "") -> Optional[str]:
+        """
+        给定 Python 函数路径，返回最可能对应的 Wolfram 函数名（仅函数名，无括号）。
+        context 可附加参数示例或错误信息辅助判断。
+        """
+        if not self._ensure_provider():
+            return None
+        try:
+            prompt = (
+                f"你是 Wolfram Language 专家，熟悉 Python 科学计算生态（NumPy/SciPy/pandas/PyTorch 等）。\n"
+                f"用户调用了 Python 函数：{python_path}\n"
+                + (f"上下文：{context}\n" if context else "")
+                + f"\n只回答对应的 Wolfram Language 内置函数名（如 Fourier、LinearSolve），"
+                  f"不要括号，不要参数，不要解释，不要换行。"
+            )
+            result = self._provider.generate(prompt, max_tokens=40, temperature=0.1)
+            # 取第一行，去掉可能残留的括号
+            return result.splitlines()[0].split("[")[0].strip()
+        except Exception as e:
+            log.warning(f"AI 函数名建议失败：{e}")
+            return None
+
+    # ── 主功能 2：候选重排（供 candidate_finder 调用）───────────
+    def rerank(self, python_path: str, error_hint: str,
+               candidates: list) -> Optional[str]:
+        """
+        给定错误上下文和候选列表，返回"最合适候选"的编号序列，如 "2,1,4"。
+        candidates: [(score, rule), ...]
+        """
+        if not self._ensure_provider():
+            return None
+        try:
+            lines = "\n".join(
+                f"  [{i+1}] {r['python_path']} → {r['wolfram_function']}"
+                f"  （{r.get('description', '')}）"
+                for i, (_, r) in enumerate(candidates)
+            )
+            prompt = (
+                f"用户在 py2wl 中调用了 `{python_path}` 但失败了。\n"
+                f"错误信息：{error_hint}\n\n"
+                f"以下是按编辑距离预筛的 Python→Wolfram 候选映射：\n{lines}\n\n"
+                f"请只输出编号序列（如 2,1,4），按'最可能是用户真正意图'排序，不要解释。"
+            )
+            return self._provider.generate(prompt, max_tokens=30, temperature=0.1)
+        except Exception as e:
+            log.warning(f"AI 重排失败：{e}")
+            return None
+
+    # ── 主功能 3：解释映射（供交互式 UI 调用）──────────────────
+    def explain(self, python_path: str, rule: dict) -> Optional[str]:
+        """向用户解释一条 Python→Wolfram 映射的语义和注意事项。"""
+        if not self._ensure_provider():
+            return None
+        try:
+            return self._provider.explain_mapping(python_path, rule)
+        except Exception as e:
+            log.warning(f"AI 映射解释失败：{e}")
+            return None

py2wl-0.6.1/py2wl/compat/_core/ai_providers/base.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+from abc import ABC, abstractmethod
+
+
+class AIProvider(ABC):
+    """
+    AI 服务提供商抽象基类。
+    py2wl 使用场景：
+      - suggest_mapping : 根据 Python 函数路径推断 Wolfram 等价函数名
+      - rerank_candidates: 对预筛候选列表按语义相关度重排
+      - explain_mapping  : 向用户解释某条 Python→WL 映射的含义与注意事项
+    """
+
+    @abstractmethod
+    def generate(self, prompt: str, **kwargs) -> str:
+        """向模型发送原始 prompt，返回文本响应。"""
+        pass
+
+    @abstractmethod
+    def explain_mapping(self, python_path: str, rule: dict) -> str:
+        """
+        解释一条 Python→Wolfram 映射规则。
+
+        Args:
+            python_path : 如 "numpy.linalg.eig"
+            rule        : YAML 映射规则 dict，含 wolfram_function / description / tags 等
+        Returns:
+            面向开发者的说明文字（可含注意事项 / 坑）
+        """
+        pass

py2wl-0.6.1/py2wl/compat/_core/ai_providers/claude.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+import os
+import requests
+from .base import AIProvider
+
+
+class ClaudeProvider(AIProvider):
+    """Anthropic Claude — py2wl AI 插件实现。"""
+
+    def __init__(self, api_key: str = None):
+        self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+        if not self.api_key:
+            raise ValueError("需要提供 ANTHROPIC_API_KEY")
+        self.api_endpoint = "https://api.anthropic.com/v1/messages"
+        self.model = "claude-3-5-sonnet-20241022"
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        headers = {
+            "x-api-key": self.api_key,
+            "anthropic-version": "2023-06-01",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": kwargs.get("temperature", 0.2),
+            "max_tokens": kwargs.get("max_tokens", 256),
+        }
+        resp = requests.post(self.api_endpoint, headers=headers,
+                             json=payload, timeout=15)
+        resp.raise_for_status()
+        return resp.json()["content"][0]["text"].strip()
+
+    def explain_mapping(self, python_path: str, rule: dict) -> str:
+        wf   = rule.get("wolfram_function", "?")
+        desc = rule.get("description", "")
+        tags = ", ".join(rule.get("tags") or [])
+        prompt = (
+            f"你是 Wolfram Language 和 Python 科学计算双栖专家。\n"
+            f"请用 2-4 句话解释以下映射关系，重点说明两侧语义差异和使用注意事项：\n\n"
+            f"  Python  : {python_path}\n"
+            f"  Wolfram : {wf}\n"
+            f"  简介    : {desc}\n"
+            f"  标签    : {tags}\n\n"
+            f"如有数值精度差异、索引约定不同、广播行为差异等坑，请务必提醒。"
+        )
+        return self.generate(prompt, max_tokens=256, temperature=0.3)

py2wl-0.6.1/py2wl/compat/_core/ai_providers/deepseek.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+import os
+import requests
+from .base import AIProvider
+
+
+class DeepSeekProvider(AIProvider):
+    """DeepSeek Chat — py2wl AI 插件实现。"""
+
+    def __init__(self, api_key: str = None):
+        self.api_key = api_key or os.getenv("DEEPSEEK_API_KEY")
+        if not self.api_key:
+            raise ValueError("需要提供 DEEPSEEK_API_KEY")
+        self.api_endpoint = "https://api.deepseek.com/v1/chat/completions"
+        self.model = "deepseek-chat"
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": kwargs.get("temperature", 0.2),
+            "max_tokens": kwargs.get("max_tokens", 256),
+        }
+        resp = requests.post(self.api_endpoint, headers=headers,
+                             json=payload, timeout=15)
+        resp.raise_for_status()
+        return resp.json()["choices"][0]["message"]["content"].strip()
+
+    def explain_mapping(self, python_path: str, rule: dict) -> str:
+        wf   = rule.get("wolfram_function", "?")
+        desc = rule.get("description", "")
+        tags = ", ".join(rule.get("tags") or [])
+        prompt = (
+            f"你是 Wolfram Language 和 Python 科学计算双栖专家。\n"
+            f"请用 2-4 句话解释以下映射关系，重点说明两侧语义差异和使用注意事项：\n\n"
+            f"  Python  : {python_path}\n"
+            f"  Wolfram : {wf}\n"
+            f"  简介    : {desc}\n"
+            f"  标签    : {tags}\n\n"
+            f"如有数值精度差异、索引约定不同、广播行为差异等坑，请务必提醒。"
+        )
+        return self.generate(prompt, max_tokens=256, temperature=0.3)

py2wl-0.6.1/py2wl/compat/_core/ai_providers/gemini.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+import os
+import requests
+from .base import AIProvider
+
+
+class GeminiProvider(AIProvider):
+    """Google Gemini — py2wl AI 插件实现。"""
+
+    def __init__(self, api_key: str = None):
+        self.api_key = api_key or os.getenv("GOOGLE_API_KEY")
+        if not self.api_key:
+            raise ValueError("需要提供 GOOGLE_API_KEY")
+        self.model = "gemini-1.5-flash"
+        self.api_endpoint = (
+            f"https://generativelanguage.googleapis.com/v1beta/"
+            f"models/{self.model}:generateContent"
+        )
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        url = f"{self.api_endpoint}?key={self.api_key}"
+        payload = {
+            "contents": [{"parts": [{"text": prompt}]}],
+            "generationConfig": {
+                "temperature": kwargs.get("temperature", 0.2),
+                "maxOutputTokens": kwargs.get("max_tokens", 256),
+            },
+        }
+        resp = requests.post(url, json=payload, timeout=15)
+        resp.raise_for_status()
+        return resp.json()["candidates"][0]["content"]["parts"][0]["text"].strip()
+
+    def explain_mapping(self, python_path: str, rule: dict) -> str:
+        wf   = rule.get("wolfram_function", "?")
+        desc = rule.get("description", "")
+        tags = ", ".join(rule.get("tags") or [])
+        prompt = (
+            f"你是 Wolfram Language 和 Python 科学计算双栖专家。\n"
+            f"请用 2-4 句话解释以下映射关系，重点说明两侧语义差异和使用注意事项：\n\n"
+            f"  Python  : {python_path}\n"
+            f"  Wolfram : {wf}\n"
+            f"  简介    : {desc}\n"
+            f"  标签    : {tags}\n\n"
+            f"如有数值精度差异、索引约定不同、广播行为差异等坑，请务必提醒。"
+        )
+        return self.generate(prompt, max_tokens=256, temperature=0.3)

py2wl-0.6.1/py2wl/compat/_core/ai_providers/groq.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+import os
+import requests
+from .base import AIProvider
+
+
+class GroqProvider(AIProvider):
+    """
+    Groq (Llama 3.3 70B) — py2wl AI 插件实现。
+    Groq 的推理延迟极低，适合容错系统的实时交互场景。
+    使用 REST API 而非 groq 库，保持零额外依赖。
+    """
+
+    def __init__(self, api_key: str = None):
+        self.api_key = api_key or os.getenv("GROQ_API_KEY")
+        if not self.api_key:
+            raise ValueError("需要提供 GROQ_API_KEY")
+        self.api_endpoint = "https://api.groq.com/openai/v1/chat/completions"
+        self.model = "llama-3.3-70b-versatile"
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "model": self.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": kwargs.get("temperature", 0.2),
+            "max_tokens": kwargs.get("max_tokens", 256),
+        }
+        resp = requests.post(self.api_endpoint, headers=headers,
+                             json=payload, timeout=15)
+        resp.raise_for_status()
+        return resp.json()["choices"][0]["message"]["content"].strip()
+
+    def explain_mapping(self, python_path: str, rule: dict) -> str:
+        wf   = rule.get("wolfram_function", "?")
+        desc = rule.get("description", "")
+        tags = ", ".join(rule.get("tags") or [])
+        prompt = (
+            f"你是 Wolfram Language 和 Python 科学计算双栖专家。\n"
+            f"请用 2-4 句话解释以下映射关系，重点说明两侧语义差异和使用注意事项：\n\n"
+            f"  Python  : {python_path}\n"
+            f"  Wolfram : {wf}\n"
+            f"  简介    : {desc}\n"
+            f"  标签    : {tags}\n\n"
+            f"如有数值精度差异、索引约定不同、广播行为差异等坑，请务必提醒。"
+        )
+        return self.generate(prompt, max_tokens=256, temperature=0.3)

py2wl-0.6.1/py2wl/compat/_core/candidate_finder.py

@@ -0,0 +1,154 @@
+"""
+compat/_core/candidate_finder.py
+----------------------------------
+候选函数查找器：在出错时，从元数据库 + AI 两路找出最相似的备选规则。
+
+评分策略（综合得分 0-1）：
+  1. 编辑距离（Levenshtein）相似度  ×0.4
+  2. 标签 / 关键词匹配数              ×0.4
+  3. AI 语义排名（可选）              ×0.2
+
+返回按得分降序排列的 [(score, rule), ...]。
+"""
+
+from __future__ import annotations
+import logging
+from typing import List, Tuple, Dict, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .metadata import MetadataRepository
+    from .ai_plugin import AIPlugin
+
+log = logging.getLogger("py2wl.compat")
+
+
+# ── 轻量 Levenshtein（零依赖）──────────────────────────────────
+def _lev(a: str, b: str) -> int:
+    if len(a) < len(b):
+        a, b = b, a
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a, 1):
+        curr = [i]
+        for j, cb in enumerate(b, 1):
+            curr.append(min(prev[j] + 1, curr[j - 1] + 1,
+                            prev[j - 1] + (ca != cb)))
+        prev = curr
+    return prev[-1]
+
+
+def _lev_sim(a: str, b: str) -> float:
+    max_len = max(len(a), len(b), 1)
+    return 1.0 - _lev(a, b) / max_len
+
+
+# ── 路径分词（对点分路径拆成词组进行匹配）──────────────────────
+def _tokens(path: str) -> set:
+    """numpy.fft.fft  →  {'numpy', 'fft'}"""
+    return set(path.replace("_", ".").split("."))
+
+
+class CandidateFinder:
+    """
+    给定一个 python_path（可能拼错 / 不存在）和错误上下文，
+    返回按相关度排序的备选规则列表。
+    """
+
+    def __init__(self, repo: "MetadataRepository",
+                 ai_plugin: Optional["AIPlugin"] = None,
+                 top_k: int = 6):
+        self._repo      = repo
+        self._ai        = ai_plugin
+        self._top_k     = top_k
+
+    def find(self, python_path: str,
+             error_hint: str = "",
+             args: tuple = (),
+             kwargs: dict = None,
+             use_ai: bool = True) -> List[Tuple[float, Dict]]:
+        """
+        返回 [(score, rule), ...]，按 score 降序。
+        """
+        kwargs = kwargs or {}
+        scored: Dict[str, Tuple[float, Dict]] = {}
+
+        target_tokens = _tokens(python_path)
+        target_ns     = python_path.split(".")[0]   # e.g. "numpy"
+
+        for rule in self._repo.all_rules:
+            path   = rule["python_path"]
+            rule_ns = path.split(".")[0]
+
+            # ── 1. 编辑距离相似度 ────────────────────────────
+            lev_sc = _lev_sim(python_path, path)
+
+            # ── 2. 词集合 Jaccard 相似度 ──────────────────────
+            rule_tokens = _tokens(path)
+            union   = target_tokens | rule_tokens
+            inter   = target_tokens & rule_tokens
+            jac_sc  = len(inter) / len(union) if union else 0.0
+
+            # ── 3. 命名空间加成（同一库优先）─────────────────
+            ns_bonus = 0.15 if rule_ns == target_ns else 0.0
+
+            # ── 4. 关键词 / 错误提示匹配 ─────────────────────
+            desc  = (rule.get("description") or "").lower()
+            tags  = " ".join(rule.get("tags") or []).lower()
+            hint_words = set(error_hint.lower().split())
+            hint_sc = sum(1 for w in hint_words if w in desc or w in tags) * 0.05
+
+            score = lev_sc * 0.45 + jac_sc * 0.35 + ns_bonus + min(hint_sc, 0.15)
+            if score > 0.05:  # 过滤完全无关的
+                scored[path] = (score, rule)
+
+        # 按分数降序取 top_k
+        ranked = sorted(scored.values(), key=lambda x: -x[0])[: self._top_k]
+
+        # ── AI 二次排名（可选）───────────────────────────────
+        if use_ai and self._ai and ranked:
+            ranked = self._ai_rerank(python_path, error_hint, ranked)
+
+        return ranked
+
+    # ── AI 重排：让 AI 从 top_k 候选里选最合适的并排序 ──────
+    def _ai_rerank(self, python_path: str, error_hint: str,
+                   candidates: List[Tuple[float, Dict]]) -> List[Tuple[float, Dict]]:
+        try:
+            candidate_lines = "\n".join(
+                f"  [{i+1}] {r['python_path']} → {r['wolfram_function']}  ({r.get('description','')})"
+                for i, (_, r) in enumerate(candidates)
+            )
+            prompt = (
+                f"用户调用了 Python 函数 `{python_path}` 但失败了（{error_hint}）。\n"
+                f"以下是按编辑距离预筛的候选映射：\n{candidate_lines}\n\n"
+                f"请只输出编号列表（如 2,1,4），按'最可能是用户真正意图'的顺序排列，不要解释。"
+            )
+            resp = self._ai._ensure_provider() and self._ai._provider.generate(
+                prompt, max_tokens=60)
+            if not resp or not isinstance(resp, str):
+                return candidates
+
+            # 解析 "2,1,4" 格式
+            import re
+            nums = [int(x) - 1 for x in re.findall(r"\d+", resp)
+                    if 0 < int(x) <= len(candidates)]
+            if not nums:
+                return candidates
+
+            seen = set()
+            reordered = []
+            for n in nums:
+                if n not in seen:
+                    seen.add(n)
+                    # 稍微抬高 AI 排到前面的分数
+                    sc, rule = candidates[n]
+                    boost = (len(nums) - len(reordered)) * 0.03
+                    reordered.append((min(sc + boost, 1.0), rule))
+            # 把未被 AI 提及的追加在后
+            for i, (sc, rule) in enumerate(candidates):
+                if i not in seen:
+                    reordered.append((sc * 0.9, rule))
+            return reordered
+
+        except Exception as e:
+            log.debug(f"AI 重排失败（无影响）：{e}")
+            return candidates