ivoryos-edge 0.1.1__tar.gz

ivoryos_edge-0.1.1/MANIFEST.in

@@ -0,0 +1,2 @@
+# The build backend itself, so a wheel can be built from the sdist.
+include build_backend.py

ivoryos_edge-0.1.1/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: ivoryos-edge
+Version: 0.1.1
+Summary: IvoryOS Edge Server
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ivoryos-ai/ivoryos-next
+Project-URL: Documentation, https://ivoryos-ai.github.io/ivoryos-next/
+Project-URL: Issues, https://github.com/ivoryos-ai/ivoryos-next/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: python-socketio[client]
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: aiohttp
+Requires-Dist: sqlalchemy[asyncio]
+Requires-Dist: aiosqlite
+Requires-Dist: paho-mqtt
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pandas
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: httpx; extra == "test"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == "mcp"
+Provides-Extra: claude
+Requires-Dist: anthropic>=1.0; extra == "claude"
+
+# ivoryos-edge
+
+The IvoryOS edge: it runs next to your instruments, reads the Python classes that drive them, and
+serves a web page to design, run and optimize experiments with them. Every method becomes a step
+you can drag into a workflow, and every argument a field of the right type. Runs, results and
+workflows are kept on that computer.
+
+Most people use it through the [IvoryOS desktop app](https://github.com/ivoryos-ai/ivoryos-next/releases),
+which installs this package itself. Install it on its own to run a deck from your own Python
+environment, such as one your editor uses.
+
+## Install
+
+```bash
+pip install ivoryos-edge
+```
+
+Python 3.10 or newer. The web interface is inside the package; nothing else is needed.
+
+## Run your instruments
+
+End a script that creates your instrument objects with `ivoryos_edge.run(__name__)`:
+
+```python
+import ivoryos_edge
+from my_lab import SyringePump
+
+pump = SyringePump(port="COM3")  # each object becomes an instrument
+
+ivoryos_edge.run(__name__)       # http://localhost:8080
+```
+
+Then open `http://localhost:8080` in a browser on that computer. A deck can also be a JSON file,
+run with `ivoryos-edge --deck deck.json`.
+
+## Links
+
+- [Documentation](https://ivoryos-ai.github.io/ivoryos-next/)
+- [Automation Hub](https://ivoryos.ai): drivers, platforms and workflow templates
+- [Source and issues](https://github.com/ivoryos-ai/ivoryos-next)

ivoryos_edge-0.1.1/README.md

@@ -0,0 +1,40 @@
+# ivoryos-edge
+
+The IvoryOS edge: it runs next to your instruments, reads the Python classes that drive them, and
+serves a web page to design, run and optimize experiments with them. Every method becomes a step
+you can drag into a workflow, and every argument a field of the right type. Runs, results and
+workflows are kept on that computer.
+
+Most people use it through the [IvoryOS desktop app](https://github.com/ivoryos-ai/ivoryos-next/releases),
+which installs this package itself. Install it on its own to run a deck from your own Python
+environment, such as one your editor uses.
+
+## Install
+
+```bash
+pip install ivoryos-edge
+```
+
+Python 3.10 or newer. The web interface is inside the package; nothing else is needed.
+
+## Run your instruments
+
+End a script that creates your instrument objects with `ivoryos_edge.run(__name__)`:
+
+```python
+import ivoryos_edge
+from my_lab import SyringePump
+
+pump = SyringePump(port="COM3")  # each object becomes an instrument
+
+ivoryos_edge.run(__name__)       # http://localhost:8080
+```
+
+Then open `http://localhost:8080` in a browser on that computer. A deck can also be a JSON file,
+run with `ivoryos-edge --deck deck.json`.
+
+## Links
+
+- [Documentation](https://ivoryos-ai.github.io/ivoryos-next/)
+- [Automation Hub](https://ivoryos.ai): drivers, platforms and workflow templates
+- [Source and issues](https://github.com/ivoryos-ai/ivoryos-next)

ivoryos_edge-0.1.1/build_backend.py

@@ -0,0 +1,66 @@
+"""The build backend of ivoryos-edge: setuptools, refusing a wheel or sdist with no web UI in it.
+
+A wheel or sdist is the edge as people install it (`pip install ivoryos-edge`, the desktop app's
+bundled wheel), and it serves the pages it carries in `ivoryos_edge/ui/`, which are the same
+version as its API. That folder is a build output, not source: scripts/build-edge.js at the
+repository root builds the frontend, copies frontend/out into it and builds. Building without it
+used to succeed and gave an edge that starts with an API and no pages, so it is refused here, and
+the built file is checked to hold the pages too (a package-data rule that stops matching would
+otherwise drop them silently).
+
+An editable install (`pip install -e`, a source checkout in development) needs no copy: the edge
+serves frontend/out from the checkout (`_frontend_dirs` in ivoryos_edge/server.py).
+"""
+import os
+import shutil
+import tarfile
+import zipfile
+
+from setuptools import build_meta as _setuptools
+from setuptools.build_meta import *  # noqa: F401,F403  every other hook, editable installs included
+
+_UI_INDEX = "ivoryos_edge/ui/index.html"
+
+
+def _refuse(message):
+    raise RuntimeError(
+        f"{message}\nA wheel or sdist of ivoryos-edge must carry the web UI, or the edge it installs "
+        "starts with no pages. Build it with `npm run build:edge` from the repository root, which "
+        "builds frontend/ and copies frontend/out into ivoryos_edge/ui/ first. (In development, "
+        "`pip install -e ./edge_server` needs no copy: it serves frontend/out from the checkout.)"
+    )
+
+
+def _require_ui():
+    if not os.path.isfile(_UI_INDEX):
+        _refuse(f"No web UI to package: {os.path.abspath(_UI_INDEX)} does not exist.")
+
+
+def _check_built(path, names):
+    if not any(name == _UI_INDEX or name.endswith("/" + _UI_INDEX) for name in names):
+        os.remove(path)
+        _refuse(f"{os.path.basename(path)} came out without {_UI_INDEX}, so it was removed. "
+                "Check [tool.setuptools.package-data] in edge_server/pyproject.toml.")
+
+
+def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+    _require_ui()
+    # setuptools copies the package into build/lib and packs everything there, earlier builds'
+    # files too: the UI's script names change with every frontend build, so old ones would pile up.
+    shutil.rmtree(os.path.join("build", "lib", "ivoryos_edge", "ui"), ignore_errors=True)
+    name = _setuptools.build_wheel(wheel_directory, config_settings, metadata_directory)
+    path = os.path.join(wheel_directory, name)
+    with zipfile.ZipFile(path) as wheel:
+        names = wheel.namelist()
+    _check_built(path, names)
+    return name
+
+
+def build_sdist(sdist_directory, config_settings=None):
+    _require_ui()
+    name = _setuptools.build_sdist(sdist_directory, config_settings)
+    path = os.path.join(sdist_directory, name)
+    with tarfile.open(path) as sdist:
+        names = sdist.getnames()
+    _check_built(path, names)
+    return name

ivoryos_edge-0.1.1/ivoryos_edge/__init__.py

@@ -0,0 +1,22 @@
+"""IvoryOS edge server.
+
+`ivoryos_edge.run(__name__)` is resolved lazily (PEP 562) rather than imported here. Importing the
+server fixes every data path (see paths.py) and creates the database engine, and the command-line
+entry point has to set `IVORYOS_DATA_DIR` before that happens -- which it cannot do if merely
+importing the package has already imported the server.
+"""
+
+__all__ = ["run", "Unit"]
+
+
+def __getattr__(name):
+    if name == "run":
+        from .server import run
+        return run
+    if name == "Unit":
+        # `from ivoryos_edge import Unit`, for a driver's annotations (units.py). Lazy like `run`,
+        # for the opposite reason: units.py imports nothing, and a driver module importing it
+        # must not drag the server in.
+        from .units import Unit
+        return Unit
+    raise AttributeError(f"module 'ivoryos_edge' has no attribute {name!r}")

ivoryos_edge-0.1.1/ivoryos_edge/__main__.py

@@ -0,0 +1,4 @@
+"""`python -m ivoryos_edge`: see cli.py."""
+from .cli import main
+
+main()

ivoryos_edge-0.1.1/ivoryos_edge/agent/__init__.py

@@ -0,0 +1,13 @@
+"""The agent tool layer: what an assistant is allowed to know and to ask for.
+
+One layer, two surfaces. `routes.py` publishes it over HTTP under /api/agent; the MCP server
+(`ivoryos_edge.agent.mcp_server`) is a thin stdio process that calls those same endpoints, and
+the Designer's chat panel calls them from the browser. Adding a third surface, or swapping which
+model is driving, should never mean reimplementing what a tool *does* — which is the whole
+reason this is a module and not a pile of route handlers.
+"""
+
+from ivoryos_edge.agent.deck import describe_deck, describe_method
+from ivoryos_edge.agent.validate import validate_body, summarise
+
+__all__ = ["describe_deck", "describe_method", "validate_body", "summarise"]

ivoryos_edge-0.1.1/ivoryos_edge/agent/ask.py

@@ -0,0 +1,130 @@
+"""Answering questions about this lab's runs and deck, from its own records.
+
+Small local models are unreliable at a tool-calling protocol and fine at emitting one JSON object
+(see providers.py), so tools are offered the same way workflows are written: each reply is one
+JSON object, either a tool to run or the answer. The tool runs here, its result goes back as the
+next message, and after a few rounds the model must answer with what it has.
+
+Read-only by construction: the tools are history.search / read / compare and nothing else. An
+answer that should change something (a workflow, a run, a safety rule) is the other modes' job,
+which file proposals for a person to accept.
+"""
+
+import json
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from ivoryos_edge.agent import history
+from ivoryos_edge.agent.providers import extract_json_object
+
+MAX_TOOL_CALLS = 5
+MAX_RESULT_CHARS = 12000
+
+SYSTEM_PROMPT = """You answer questions about this lab's experiments, using its own records.
+
+You can look things up. Reply with exactly one JSON object and nothing else, either a lookup:
+
+  {"tool": "search_runs", "args": {"q": "<words in the run's name, columns or instruments>", "status": "<completed, error, cancelled or all>", "limit": 20}}
+  {"tool": "run_table", "args": {"run_id": <id>}}
+  {"tool": "compare_runs", "args": {"run_ids": [<id>, <id>], "columns": ["<column>"]}}
+
+or, when you can answer:
+
+  {"answer": "<your answer, in plain language; short markdown lists and tables are fine>", "runs": [<ids of the runs your answer is about>]}
+
+How to work:
+- run_table gives one run's columns, rows and per-column numbers (n, min, max, mean, and the best
+  row for an optimization objective). compare_runs computes the same across runs. Use those
+  numbers; do not compute statistics yourself from rows.
+- Every number in your answer must come from a lookup result in this conversation. If the records
+  do not hold what was asked, say so plainly and say what they do hold.
+- Name runs as "<name> (#<id>)" so the person can open them.
+- A column ending in "(objective)" is what an optimization was trying to improve.
+- Prefer one or two lookups. You may make at most %d.""" % MAX_TOOL_CALLS
+
+
+def _clip_json(value: Any) -> str:
+    text = json.dumps(value, default=str)
+    if len(text) > MAX_RESULT_CHARS:
+        text = text[:MAX_RESULT_CHARS] + ' ... (cut: ask for fewer rows or one run at a time)'
+    return text
+
+
+async def _run_tool(queue_manager, name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+    if name == "search_runs":
+        return await history.search(queue_manager, q=str(args.get("q") or ""), status=str(args.get("status") or "all"),
+                                    limit=args.get("limit") or 20, offset=args.get("offset") or 0,
+                                    sort=str(args.get("sort") or "newest"))
+    if name == "run_table":
+        table = await history.read(queue_manager, args.get("run_id"))
+        return table or {"error": f"No run #{args.get('run_id')}."}
+    if name == "compare_runs":
+        columns = args.get("columns")
+        return await history.compare(queue_manager, args.get("run_ids") or [],
+                                     [str(c) for c in columns] if isinstance(columns, list) and columns else None)
+    return {"error": f"There is no tool called '{name}'. Use search_runs, run_table or compare_runs."}
+
+
+async def answer(provider, queue_manager, question: str, history_turns: Optional[List[dict]] = None,
+                 page_context: str = "", deck_names: Optional[List[str]] = None,
+                 on_progress: Optional[Callable[[dict], Awaitable[None]]] = None):
+    """Run the look-up-then-answer loop. Returns (result, transcript); result is
+    {answer, runs, lookups: [{tool, args}], ok}."""
+    async def report(**event):
+        if on_progress is not None:
+            await on_progress(event)
+
+    recent = await history.search(queue_manager, limit=15)
+    context = ["The 15 most recent runs on this deck (newest first):\n" + _clip_json(recent)]
+    if deck_names:
+        context.append("Instruments on this deck: " + ", ".join(deck_names))
+    if page_context:
+        context.append("Where the person is in the app right now: " + page_context)
+    messages: List[dict] = [
+        {"role": "user", "content": "\n\n".join(context)},
+        {"role": "assistant", "content": "Understood. I will reply with one JSON object: a lookup or the answer."},
+    ]
+    for turn in history_turns or []:
+        if turn.get("role") in ("user", "assistant") and turn.get("content"):
+            messages.append({"role": turn["role"], "content": str(turn["content"])[:8000]})
+    messages.append({"role": "user", "content": question})
+
+    lookups: List[dict] = []
+    transcript: List[dict] = []
+    await report(phase="thinking")
+    for turn in range(MAX_TOOL_CALLS + 2):
+        raw = await provider.complete(SYSTEM_PROMPT, messages, json_mode=True)
+        transcript.append({"turn": turn, "raw": raw})
+        try:
+            reply = extract_json_object(raw)
+        except ValueError:
+            messages += [{"role": "assistant", "content": raw[:4000]},
+                         {"role": "user", "content": "That was not one JSON object. Reply with a lookup or an answer, as JSON only."}]
+            continue
+
+        if reply.get("answer") is not None:
+            runs = [r for r in (reply.get("runs") or []) if isinstance(r, int)]
+            await report(phase="answered")
+            return {"answer": str(reply["answer"]).strip(), "runs": runs, "lookups": lookups, "ok": True}, transcript
+
+        tool = str(reply.get("tool") or "")
+        if not tool:
+            messages += [{"role": "assistant", "content": raw[:4000]},
+                         {"role": "user", "content": 'Reply with {"tool": ..., "args": {...}} or {"answer": ..., "runs": [...]}.'}]
+            continue
+        if len(lookups) >= MAX_TOOL_CALLS:
+            messages += [{"role": "assistant", "content": raw[:4000]},
+                         {"role": "user", "content": "No more lookups. Answer now with what you have, and say what is missing."}]
+            continue
+        args = reply.get("args") if isinstance(reply.get("args"), dict) else {}
+        lookups.append({"tool": tool, "args": args})
+        await report(phase="looking_up", tool=tool, args=args)
+        try:
+            result = await _run_tool(queue_manager, tool, args)
+        except Exception as e:  # a bad argument from the model is its to fix, not a failure here
+            result = {"error": str(e)}
+        messages += [{"role": "assistant", "content": json.dumps(reply)[:4000]},
+                     {"role": "user", "content": f"Result of {tool}:\n{_clip_json(result)}"}]
+
+    await report(phase="gave_up")
+    return {"answer": "I could not get to an answer from the records. Try asking about one run, or name the runs to compare.",
+            "runs": [], "lookups": lookups, "ok": False}, transcript

ivoryos_edge-0.1.1/ivoryos_edge/agent/chat.py

@@ -0,0 +1,200 @@
+"""Turning a paragraph of protocol into a reviewable workflow.
+
+The loop is: describe the deck, ask for one JSON workflow body, validate it against that same
+deck, and hand the errors back to the model to fix — up to a small number of attempts. The
+retry is what makes this usable with a local model: a 8B model asked cold gets an argument name
+or a unit wrong perhaps half the time, and gets it right when told precisely what was wrong,
+because `validate_body`'s messages name the offending field and list the legal alternatives.
+
+What comes out is never applied. It is filed as a proposal for the scientist to accept, so the
+worst case of a bad translation is a rejected diff rather than a wrong reaction.
+"""
+
+import json
+
+from ivoryos_edge.agent.deck import describe_deck
+from ivoryos_edge.agent.providers import ProviderError, extract_json_object
+from ivoryos_edge.agent.validate import validate_body, summarise
+
+MAX_ATTEMPTS = 3
+
+SYSTEM_PROMPT = """You translate laboratory protocols into IvoryOS workflows.
+
+You are given the exact set of instruments and methods available on this lab's deck. You must
+use only those. Never invent an instrument, a method or an argument name: if the protocol asks
+for something the deck cannot do, say so in your summary and leave that step out rather than
+approximating it with a method that does something else.
+
+Reply with a single JSON object and nothing else:
+
+{
+  "summary": "<plain language: what this does, and for an edit, what you changed and why>",
+  "body": {
+    "name": "<short name>",
+    "description": "<one line>",
+    "prep": [ ...steps... ],
+    "script": [ ...steps... ],
+    "cleanup": [ ...steps... ]
+  },
+  "questions": ["<anything the protocol left ambiguous that a person must decide>"]
+}
+
+A step is {"instrument": "<name>", "action": "<method>", "args": {"<arg>": <value>}}.
+
+Rules that matter:
+- Numbers are bare numbers. Write 65, never "65 C" or "65 degrees". A parameter's `unit` says
+  what the number is in: a volume whose unit is mL takes 2.5 for 2.5 mL, never 2500.
+- `prep` runs once at the start, `script` is the part repeated per sample or per optimization
+  trial, and `cleanup` runs once at the end. If the protocol does not distinguish them, put
+  everything in `script`.
+- To save a result for a later step or as an optimization objective, add to that step:
+  "return": "name", "return_bindings": [{"path": "<a save_from value from the deck>", "var": "name"}].
+  Use the exact `save_from` strings the deck lists. Only numeric results can be optimized.
+- To use a saved value later, write it as a string "#name" in an argument.
+- A value the protocol leaves to the operator should be "#name" and listed in `questions`,
+  or read with a Flow_Control User_Input step.
+- To compute a value from earlier ones (a counter, a dilution), use a Flow_Control Set_Variable
+  step: "args": {"variable_name": "dilution", "value": "volume / 2"}, earlier variables by bare
+  name in "value", then "#dilution" in later arguments.
+- Every Flow_Control "If" needs a matching "End_If", and every "While" a matching "End_While".
+- Prefer fewer, correct steps. Do not invent safety, washing or calibration steps the protocol
+  does not mention.
+
+If you are editing an existing workflow, keep every step the scientist did not ask you to
+change, exactly as it was."""
+
+
+def _deck_prompt(schema, workflows):
+    return (
+        "This lab's deck, as JSON. These are the only instruments and methods that exist:\n\n"
+        + json.dumps(describe_deck(schema, workflows=workflows), indent=1)
+    )
+
+
+def _existing_prompt(name, body):
+    return (
+        f"You are editing the saved workflow '{name}'. Its current body is:\n\n"
+        + json.dumps(body, indent=1)
+        + "\n\nReturn the complete new body, not a patch."
+    )
+
+
+def _retry_prompt(issues):
+    errors = [i for i in issues if i["severity"] == "error"]
+    lines = []
+    for issue in errors:
+        line = f"- {issue['where']}: {issue['message']}"
+        if issue.get("hint"):
+            line += f" ({issue['hint']})"
+        lines.append(line)
+    return (
+        "That workflow does not validate against the deck. Fix exactly these problems and "
+        "return the corrected JSON object:\n\n" + "\n".join(lines)
+    )
+
+
+async def translate(provider, schema, user_message, history=None, workflows=(),
+                    existing_name=None, existing_body=None, max_attempts=MAX_ATTEMPTS,
+                    on_progress=None, resolve_workflow=None, check_fields=None):
+    """Run the translate-validate-correct loop.
+
+    Returns (result, transcript) where result is {summary, body, questions, issues, ok,
+    attempts} and transcript is the raw exchange, kept so a failure can be shown to the
+    scientist rather than swallowed.
+
+    `on_progress` is awaited with a dict at each phase. The interesting part of this loop is not
+    the tokens, it is the check-and-correct cycle — "wrote 9 steps, two were wrong, fixing" is
+    what tells a waiting scientist the thing is working and roughly how well. A local model
+    takes tens of seconds per attempt, which is far too long to show nothing.
+    """
+    async def report(**event):
+        if on_progress is not None:
+            await on_progress(event)
+    messages = []
+    context = [_deck_prompt(schema, workflows)]
+    if existing_body:
+        context.append(_existing_prompt(existing_name, existing_body))
+    messages.append({"role": "user", "content": "\n\n".join(context)})
+    messages.append({
+        "role": "assistant",
+        "content": "Understood. I will use only those instruments and methods, and reply with a single JSON object.",
+    })
+
+    for turn in (history or []):
+        role = turn.get("role")
+        content = turn.get("content")
+        if role in ("user", "assistant") and content:
+            messages.append({"role": role, "content": str(content)[:20000]})
+
+    messages.append({"role": "user", "content": user_message})
+
+    await report(phase="reading_deck", instruments=len(schema),
+                 editing=existing_name or None)
+
+    transcript = []
+    last_error = None
+    for attempt in range(1, max_attempts + 1):
+        await report(phase="drafting", attempt=attempt, max_attempts=max_attempts)
+        raw = await provider.complete(SYSTEM_PROMPT, messages, json_mode=True)
+        transcript.append({"attempt": attempt, "raw": raw})
+
+        try:
+            parsed = extract_json_object(raw)
+        except ValueError as e:
+            last_error = str(e)
+            await report(phase="unreadable", attempt=attempt, detail=str(e))
+            messages.append({"role": "assistant", "content": raw[:4000]})
+            messages.append({
+                "role": "user",
+                "content": "That was not valid JSON. Reply with a single JSON object and nothing else.",
+            })
+            continue
+
+        body = parsed.get("body")
+        if not isinstance(body, dict):
+            last_error = "The reply had no 'body' object."
+            await report(phase="unreadable", attempt=attempt, detail=last_error)
+            messages.append({"role": "assistant", "content": raw[:4000]})
+            messages.append({
+                "role": "user",
+                "content": "The JSON object must contain a 'body' with prep/script/cleanup arrays.",
+            })
+            continue
+
+        body.setdefault("name", existing_name or parsed.get("name") or "Untitled protocol")
+        for phase in ("prep", "script", "cleanup"):
+            body.setdefault(phase, [])
+
+        step_count = sum(len(body.get(phase) or []) for phase in ("prep", "script", "cleanup"))
+        await report(phase="validating", attempt=attempt, steps=step_count,
+                     name=body.get("name"))
+
+        issues = validate_body(body, schema, workflows, resolve_workflow, check_fields)
+        errors = [i for i in issues if i["severity"] == "error"]
+        result = {
+            "summary": str(parsed.get("summary") or "").strip(),
+            "body": body,
+            "questions": [str(q) for q in (parsed.get("questions") or [])][:10],
+            "issues": issues,
+            "validation_summary": summarise(issues),
+            "ok": not errors,
+            "attempts": attempt,
+        }
+        if not errors:
+            await report(phase="valid", attempt=attempt, steps=step_count)
+            return result, transcript
+
+        await report(phase="found_problems", attempt=attempt,
+                     errors=[f"{i['where']}: {i['message']}" for i in errors])
+
+        if attempt == max_attempts:
+            await report(phase="gave_up", attempt=attempt, remaining=len(errors))
+            # Out of attempts, but the draft still goes back: a workflow with two bad arguments
+            # and the errors named against it is a far better starting point for the scientist
+            # than an apology, and the Designer shows the issues inline.
+            return result, transcript
+
+        messages.append({"role": "assistant", "content": json.dumps(parsed)[:8000]})
+        messages.append({"role": "user", "content": _retry_prompt(issues)})
+
+    raise ProviderError(last_error or "The model did not return a usable workflow.")