labpilot-ai 0.1.2__py3-none-any.whl

labpilot_ai/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

labpilot_ai/__main__.py

@@ -0,0 +1,4 @@
+from .main import main
+
+if __name__ == "__main__":
+    main()

labpilot_ai/ai/__init__.py

@@ -0,0 +1 @@
+

labpilot_ai/ai/co_sequence_prompt.py

@@ -0,0 +1,86 @@
+import json
+from pathlib import Path
+
+
+def _read_limited(path, max_chars):
+    path = Path(path)
+    text = path.read_text(encoding="utf-8", errors="replace")
+    truncated = len(text) > max_chars
+    if truncated:
+        text = text[:max_chars] + "\n\n# [LabPilot truncated this file for prompt budget]\n"
+    return text, truncated
+
+
+def build_co_sequence_prompt(
+    instruction,
+    sequence_path,
+    connection_table_path,
+    *,
+    project_context="",
+    max_file_chars=60000,
+):
+    sequence_text, sequence_truncated = _read_limited(sequence_path, max_file_chars)
+    connection_text, connection_truncated = _read_limited(connection_table_path, max_file_chars)
+    return f"""
+You are LabPilot Co-Sequence, a code editing assistant for labscript experiments.
+You may propose changes ONLY to the selected sequence file and selected connection table file.
+Do not propose changes to any other file. Do not run hardware. Do not include Markdown fences.
+
+User instruction:
+{instruction}
+
+Project knowledge snippets:
+{project_context or "No local knowledge snippets were retrieved."}
+
+Selected editable files:
+1. sequence_path={sequence_path}
+truncated={sequence_truncated}
+```python
+{sequence_text}
+```
+
+2. connection_table_path={connection_table_path}
+truncated={connection_truncated}
+```python
+{connection_text}
+```
+
+Return strict JSON with this shape:
+{{
+  "summary": "short summary",
+  "risk_level": "low|medium|high",
+  "files": [
+    {{"path": "...", "unified_diff": "unified diff for that exact file"}}
+  ],
+  "consistency_checks": ["how sequence and connection table stay consistent"],
+  "color_tags": ["yellow: reason", "red: reason"],
+  "warnings": ["operator-facing warning"]
+}}
+
+Rules:
+- Every file path must be exactly one of the two selected paths.
+- Use unified diffs only. No full file replacement.
+- Keep sequence and connection table device/channel/global names consistent.
+- Prefer small, reviewable patches.
+- If the request is unsafe or underspecified, return an empty files list and put the issue in warnings.
+""".strip()
+
+
+def mock_co_sequence_plan(instruction, sequence_path, connection_table_path):
+    return {
+        "summary": "Mock Co-Sequence did not modify code. Enable an API key to generate real diffs.",
+        "risk_level": "low",
+        "files": [],
+        "consistency_checks": [
+            "Mock mode keeps sequence and connection table unchanged.",
+            f"Sequence target: {Path(sequence_path).name if sequence_path else ''}",
+            f"Connection table target: {Path(connection_table_path).name if connection_table_path else ''}",
+        ],
+        "color_tags": ["gray: mock"],
+        "warnings": ["No patch was generated in Mock LLM mode."],
+        "instruction": instruction,
+    }
+
+
+def compact_plan_text(plan):
+    return json.dumps(plan or {}, ensure_ascii=False, indent=2)

labpilot_ai/ai/command_schema.py

@@ -0,0 +1,30 @@
+ALLOWED_ACTIONS = {
+    "set_global",
+    "set_blacs_manual",
+    "engage",
+    "get_globals",
+    "load_h5",
+    "load_h5_folder",
+    "run_single_lyse",
+    "run_multi_lyse",
+    "plot",
+    "fit",
+    "start_optimization",
+    "stop_optimization",
+    "tell_optimization_result",
+    "evaluate_optimization_result",
+    "generate_protocol",
+    "generate_report",
+}
+
+
+def action_summary(action: dict) -> str:
+    typ = action.get("type", "")
+    if typ in {"set_global", "set_blacs_manual"}:
+        return f"{typ}: {action.get('name')} = {action.get('value')!r}"
+    if typ == "start_optimization":
+        names = ", ".join((action.get("parameters") or {}).keys())
+        return f"{typ}: {action.get('method')} {action.get('mode')} {action.get('objective')} over {names}"
+    if typ in {"plot", "fit"}:
+        return f"{typ}: {action.get('plot_type', action.get('model', ''))}"
+    return typ

labpilot_ai/ai/error_advisor.py

@@ -0,0 +1,39 @@
+def advise_error(error_text: str) -> str:
+    text = (error_text or "").strip()
+    low = text.lower()
+    hints = []
+
+    if any(token in low for token in ["unicode", "utf-8", "codec", "mojibake", "encoding", "decode error", "�"]):
+        hints.append("Check source/document encoding. Save Python and Markdown files as UTF-8, then rerun compileall before release.")
+    if any(token in text for token in ["乱码", "鏄", "涓", "鎵", "寮"]):
+        hints.append("This looks like mojibake. Reopen the affected file as UTF-8, replace corrupted strings, and avoid mixed terminal encodings.")
+    if "not in global whitelist" in low or "global" in low and "whitelist" in low:
+        hints.append("Add the variable to configs/global_registry.yaml with type, range, risk, aliases, and description.")
+    if "importerror" in low or "modulenotfounderror" in low or "no module named" in low:
+        hints.append("Install the missing optional dependency, or disable the related feature in Settings before continuing.")
+    if "blacs" in low and ("connection" in low or "refused" in low or "bridge" in low or "localhost" in low):
+        hints.append("Check the BLACS localhost bridge, the registered channel name, and Mock BLACS mode before programming hardware.")
+    if "runmanager" in low and ("connection" in low or "timeout" in low or "remote" in low):
+        hints.append("Check that runmanager is running, remote access is available, and the timeout is long enough.")
+    if "h5py has already been imported" in low or "h5_lock" in low:
+        hints.append("Restart Python and ensure labpilot_ai.bootstrap_labscript.install_h5_lock() runs before importing h5py.")
+    if "cublas" in low or "cudnn" in low or "cuda runtime" in low:
+        hints.append("For GPU STT, run Diagnostics and verify CUDA/cuBLAS/cuDNN DLL paths; switch to CPU/int8 if the DLL stack is unstable.")
+    if "openmp" in low or "libiomp5md" in low or "omp: error" in low:
+        hints.append("Keep STT in isolated_release mode or CPU/int8 mode to isolate OpenMP runtime conflicts.")
+    if "pypdf" in low or "pdf import requires" in low or "pdf indexing requires" in low:
+        hints.append("Install PDF support with pip install -e .[docs] or pip install pypdf.")
+    if "module" in low and ("not registered" in low or "no module" in low or "path does not exist" in low):
+        hints.append("Register the single/multi analysis module in configs/lyse_registry.yaml and verify the module path.")
+    if "objective" in low and ("missing" in low or "unsafe" in low or "variable" in low):
+        hints.append("Choose an objective from lyse results or use a safe expression over registered result fields.")
+    if "scipy" in low or "curve_fit" in low:
+        hints.append("Install scipy fitting dependencies with pip install -e .[fit], or choose a simpler fit model.")
+    if "h5" in low and ("timeout" in low or "folder" in low or "not found" in low):
+        hints.append("Verify the H5 output folder, shot naming rule, and whether the experiment actually produced a new H5 file.")
+    if "knowledge" in low or "fts" in low or "sqlite" in low:
+        hints.append("Rebuild the Knowledge index and confirm the configured source folders are readable.")
+
+    if not hints:
+        hints.append("Check the traceback, then reproduce in Dry run or Mock mode before touching hardware.")
+    return "\n".join(f"- {hint}" for hint in hints)

labpilot_ai/ai/json_parser.py

@@ -0,0 +1,14 @@
+import json
+
+
+def extract_json_object(text: str) -> dict:
+    text = (text or "").strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    start = text.find("{")
+    end = text.rfind("}")
+    if start >= 0 and end > start:
+        return json.loads(text[start:end+1])
+    raise ValueError(f"无法解析 JSON：{text}")

labpilot_ai/ai/llm_client.py

@@ -0,0 +1,127 @@
+import os
+import re
+
+from .co_sequence_prompt import build_co_sequence_prompt, mock_co_sequence_plan
+from .json_parser import extract_json_object
+from .prompt_builder import build_command_prompt
+
+
+class LLMClient:
+    def __init__(self, api_key=None, base_url=None, model=None, use_thinking=True, mock=False):
+        self.api_key = api_key or os.getenv("DEEPSEEK_API_KEY") or os.getenv("OPENAI_API_KEY")
+        self.base_url = base_url or os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com")
+        self.model = model or os.getenv("DEEPSEEK_MODEL", "deepseek-v4-flash")
+        self.use_thinking = use_thinking
+        self.mock = mock
+
+    def parse_command(self, user_text: str, global_registry: dict, blacs_registry=None, lyse_registry=None, project_context=None) -> dict:
+        if self.mock or not self.api_key:
+            result = self._mock_parse(user_text, global_registry)
+            if project_context:
+                result["project_context_used"] = True
+            return result
+
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise RuntimeError("OpenAI-compatible SDK is not installed. Install the project dependencies or enable Mock LLM.") from exc
+
+        client = OpenAI(api_key=self.api_key, base_url=self.base_url, timeout=60.0)
+        kwargs = dict(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": build_command_prompt(global_registry, blacs_registry, lyse_registry, project_context=project_context)},
+                {"role": "user", "content": user_text},
+            ],
+            stream=False,
+            temperature=0,
+            response_format={"type": "json_object"},
+        )
+        if self.use_thinking:
+            kwargs["reasoning_effort"] = "high"
+            kwargs["extra_body"] = {"thinking": {"type": "enabled"}}
+        response = client.chat.completions.create(**kwargs)
+        return extract_json_object(response.choices[0].message.content)
+
+    def _mock_parse(self, text: str, global_registry: dict) -> dict:
+        """Small local parser for testing without API. It only handles common cases."""
+        actions = []
+        low = (text or "").lower()
+        no_run = any(token in low for token in ["do not run", "don't run", "no run", "not run", "dry run"])
+        no_run = no_run or any(token in (text or "") for token in ["不要运行", "不运行", "别运行", "不跑"])
+
+        if any(token in low for token in ["tof", "time of flight"]) or any(token in (text or "") for token in ["飞行时间"]):
+            m = re.search(r"(?:from|从)\s*([\d.]+)\s*(?:ms)?\s*(?:to|到)\s*([\d.]+)\s*(?:ms)?.*?(\d+)\s*(?:points|点)", text or "", re.I)
+            if m and "duration_tof_ms" in global_registry:
+                actions.append(
+                    {
+                        "type": "set_global",
+                        "name": "duration_tof_ms",
+                        "value": {"linspace": [float(m.group(1)), float(m.group(2)), int(m.group(3))]},
+                    }
+                )
+            else:
+                m = re.search(r"(?:tof|time of flight|飞行时间).*?(?:to|set to|设为|设置为|改成|=)\s*([\d.]+)", text or "", re.I)
+                if m and "duration_tof_ms" in global_registry:
+                    actions.append({"type": "set_global", "name": "duration_tof_ms", "value": float(m.group(1))})
+
+        bool_map = {
+            "lyse_do_SG_F1_masked": ["sg mask", "遮罩"],
+            "lyse_update_centers_json": ["update centers", "centers_json", "centers json", "更新中心"],
+            "do_Rabi": ["rabi", "拉比"],
+            "do_pure": ["pure", "清除"],
+            "do_Ramsey": ["ramsey"],
+        }
+        for name, keys in bool_map.items():
+            if name in global_registry and any(key.lower() in low or key in (text or "") for key in keys):
+                val = not any(token in low for token in ["disable", "off", "turn off"]) and not any(
+                    token in (text or "") for token in ["关闭", "关掉", "不要打开"]
+                )
+                actions.append({"type": "set_global", "name": name, "value": val})
+
+        if not no_run and (any(token in low for token in ["run", "submit", "engage"]) or any(token in (text or "") for token in ["运行", "跑一次", "提交"])):
+            actions.append({"type": "engage"})
+        if any(token in low for token in ["read", "current", "globals"]) or any(token in (text or "") for token in ["读取", "查看", "当前参数"]):
+            actions.append({"type": "get_globals"})
+        return {"actions": actions, "comment": "Mock LLM parser result. For serious use, enable API."}
+
+    def propose_co_sequence_patch(
+        self,
+        instruction: str,
+        sequence_path,
+        connection_table_path,
+        *,
+        project_context=None,
+        max_file_chars=60000,
+    ) -> dict:
+        if self.mock or not self.api_key:
+            return mock_co_sequence_plan(instruction, sequence_path, connection_table_path)
+
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise RuntimeError("OpenAI-compatible SDK is not installed. Install the project dependencies or enable Mock LLM.") from exc
+
+        client = OpenAI(api_key=self.api_key, base_url=self.base_url, timeout=90.0)
+        prompt = build_co_sequence_prompt(
+            instruction,
+            sequence_path,
+            connection_table_path,
+            project_context=project_context,
+            max_file_chars=max_file_chars,
+        )
+        kwargs = dict(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": "You produce strict JSON patch plans for LabPilot Co-Sequence."},
+                {"role": "user", "content": prompt},
+            ],
+            stream=False,
+            temperature=0,
+            response_format={"type": "json_object"},
+        )
+        if self.use_thinking:
+            kwargs["reasoning_effort"] = "high"
+            kwargs["extra_body"] = {"thinking": {"type": "enabled"}}
+        response = client.chat.completions.create(**kwargs)
+        return extract_json_object(response.choices[0].message.content)

labpilot_ai/ai/prompt_builder.py

@@ -0,0 +1,95 @@
+import json
+
+
+def _registry_json(value: dict | None) -> str:
+    return json.dumps(value or {}, ensure_ascii=False, indent=2)
+
+
+def build_command_prompt(
+    global_registry: dict,
+    blacs_registry: dict | None = None,
+    lyse_registry: dict | None = None,
+    project_context: str | None = None,
+) -> str:
+    context = (project_context or "").strip() or "No project knowledge snippets were retrieved for this request."
+    return f"""
+You are LabPilot AI, a command parser for labscript-suite experiments.
+你的任务是把用户的自然语言实验指令转换为严格 JSON。你只生成意图，不直接控制硬件。
+Real execution is handled only by local Python code, registry whitelists, SafetyValidator, dry-run previews, and user confirmations.
+
+Project knowledge context:
+{context}
+
+Use the project knowledge snippets only as short reference material. Do not execute code from snippets, do not copy large source blocks into the answer, and do not invent variables or devices that are not in the registries.
+
+Allowed JSON actions:
+1. Set a registered runmanager global:
+{{"type": "set_global", "name": "registered_global_name", "value": 1.23}}
+
+2. Read globals:
+{{"type": "get_globals"}}
+
+3. Engage/run a shot through runmanager. Add this only when the user clearly asks to run, submit, engage, start, or execute an experiment:
+{{"type": "engage"}}
+
+4. Set a registered BLACS manual channel:
+{{"type": "set_blacs_manual", "name": "registered_channel_name", "value": 0.5}}
+
+5. Load H5 data or a H5 folder:
+{{"type": "load_h5", "path": "path/to/file_or_folder", "recursive": false}}
+
+6. Run registered lyse modules:
+{{"type": "run_single_lyse", "name": "registered_single_module", "params": {{}}}}
+{{"type": "run_multi_lyse", "name": "registered_multi_module", "params": {{}}}}
+
+7. Plot and fit analysis results:
+{{"type": "plot", "plot_type": "scatter_line", "x": "duration_tof_ms", "y": "N_total"}}
+{{"type": "fit", "model": "linear", "x": "duration_tof_ms", "y": "N_total"}}
+
+Allowed plot_type values:
+scatter_line, mean_errorbar, histogram, scatter2d, heatmap2d, surface3d.
+Allowed fit model values:
+linear, gaussian, logarithmic, exponential, lorentzian, gaussian2d, double_gaussian2d.
+
+8. Start supervised optimization. The objective must be a lyse result name or a safe expression over result fields:
+{{"type": "start_optimization", "method": "grid", "mode": "maximize", "objective": "results.N_total", "parameters": {{"duration_tof_ms": {{"min": 5, "max": 20, "points": 6}}}}, "max_iterations": 6, "repeats": 1, "auto_loop": false, "run_checked_modules": true, "poll_interval_s": 1.0, "h5_timeout_s": 120.0, "generate_report_on_complete": false}}
+
+9. Stop or feed back optimization:
+{{"type": "stop_optimization"}}
+{{"type": "tell_optimization_result", "source": "latest_h5", "run_checked_modules": true}}
+{{"type": "tell_optimization_result", "values": {{"N_total": 1.23}}}}
+
+10. Generate suggestions or reports only:
+{{"type": "generate_protocol", "prompt": "short protocol-design request"}}
+{{"type": "generate_report", "title": "short report title", "include_errors": true, "include_knowledge_context": true, "include_optimizer_history": true}}
+
+runmanager globals whitelist:
+{_registry_json(global_registry)}
+
+BLACS manual whitelist:
+{_registry_json(blacs_registry)}
+
+lyse modules:
+{_registry_json(lyse_registry)}
+
+Output format:
+{{
+  "actions": [
+    {{"type": "..."}}
+  ],
+  "comment": "short bilingual explanation if useful"
+}}
+
+Hard rules:
+- Return strict JSON only. Do not use Markdown or code fences.
+- Every action must use the field name "type"; never use the old field name "action".
+- Only use names that appear in the whitelists above.
+- If the user asks for a parameter that is not registered, do not create a set_global/set_blacs_manual action for it; explain in comment that it must be added to the registry first.
+- bool values must be true or false. Accepted user wording includes on/off, enable/disable, 打开/关闭, 是/否, 启用/禁用.
+- Float and int values must be JSON numbers.
+- Array scans may use a JSON list, {{"linspace": [start, stop, num]}}, or {{"arange": [start, stop, step]}}.
+- Optimization parameters must be registered runmanager globals and must include min, max, and points.
+- Do not add engage if the user only asks to parse, preview, design, explain, optimize setup, or edit code.
+- Co-Sequence code editing is handled by a separate page; command parsing must not generate file patches.
+- Real hardware actions remain blocked by SafetyValidator and user confirmation.
+""".strip()

labpilot_ai/ai/protocol_designer.py

@@ -0,0 +1,23 @@
+def draft_protocol_suggestion(prompt: str, known_globals: dict | None = None, project_context: str | None = None) -> str:
+    known_globals = known_globals or {}
+    names = ", ".join(list(known_globals)[:12]) or "no registered globals yet"
+    text = (prompt or "").strip()
+    context = (project_context or "").strip()
+    parts = [
+        "# Protocol suggestion",
+        "This page generates an experimental design suggestion only; it does not execute hardware actions.",
+        f"Input summary: {text[:1200]}",
+    ]
+    if context:
+        parts.append(f"Relevant project context:\n{context[:1800]}")
+    parts.extend(
+        [
+            f"Available controllable globals include: {names}.",
+            "Recommended workflow:\n"
+            "1. Convert the scientific goal into a measurable lyse result.\n"
+            "2. Register every adjustable runmanager variable with conservative ranges.\n"
+            "3. Run a small grid scan in Dry run and then on hardware.\n"
+            "4. Promote the best region to Bayesian optimization only after the lyse result is stable.\n",
+        ]
+    )
+    return "\n\n".join(parts)

labpilot_ai/ai/protocol_importer.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+
+
+TEXT_EXTENSIONS = {".txt", ".md", ".markdown"}
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".bmp", ".gif", ".tif", ".tiff", ".webp"}
+
+
+def read_text_document(path):
+    path = Path(path)
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="utf-8-sig")
+
+
+def read_pdf_text(path):
+    path = Path(path)
+    try:
+        from pypdf import PdfReader
+    except Exception as exc:
+        raise RuntimeError("PDF import requires labpilot-ai[docs] or `pip install pypdf`.") from exc
+
+    reader = PdfReader(str(path))
+    parts = []
+    for index, page in enumerate(reader.pages, start=1):
+        text = page.extract_text() or ""
+        if text.strip():
+            parts.append(f"[PDF page {index}]\n{text.strip()}")
+    return "\n\n".join(parts)
+
+
+def import_protocol_file(path):
+    path = Path(path)
+    suffix = path.suffix.lower()
+    if suffix in TEXT_EXTENSIONS:
+        return read_text_document(path)
+    if suffix == ".pdf":
+        return read_pdf_text(path)
+    raise ValueError(f"Unsupported protocol import type: {suffix or path.name}")
+
+
+def describe_image_attachment(path, note=""):
+    path = Path(path)
+    if path.suffix.lower() not in IMAGE_EXTENSIONS:
+        raise ValueError(f"Unsupported image attachment type: {path.suffix or path.name}")
+    text = f"Image attachment: {path.name}\nPath: {path}"
+    if note:
+        text += f"\nHuman note: {note}"
+    return text
+
+
+def build_protocol_prompt(text, attachments=None):
+    sections = [(text or "").strip()]
+    attachments = [str(item).strip() for item in (attachments or []) if str(item).strip()]
+    if attachments:
+        sections.append("Attachments and operator notes:\n" + "\n\n".join(attachments))
+    return "\n\n".join([section for section in sections if section])

labpilot_ai/analysis/__init__.py

@@ -0,0 +1 @@
+