Metadata-Version: 2.4
Name: protocol-drawing-studio
Version: 0.1.0
Summary: Editable scientific SVG drawings with a shared ai-ify assistant
Author: Brancaccio Lab
License-Expression: MIT AND Apache-2.0 AND BSD-3-Clause AND CC0-1.0 AND CC-BY-3.0 AND CC-BY-4.0
Keywords: svg,scientific illustration,editor,ai-ify
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Graphics :: Editors :: Vector-Based
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: src/protocol_drawing/static/licenses/ARTWORK-ATTRIBUTIONS.txt
License-File: src/protocol_drawing/static/licenses/BUNDLED-DEPENDENCIES.json
License-File: src/protocol_drawing/static/licenses/CC-BY-3.0.txt
License-File: src/protocol_drawing/static/licenses/CC-BY-4.0.txt
License-File: src/protocol_drawing/static/licenses/CC0-1.0.txt
License-File: src/protocol_drawing/static/licenses/SVGEdit-MIT.txt
License-File: src/protocol_drawing/static/licenses/SVGEdit-dependencies.json
License-File: src/protocol_drawing/static/licenses/THIRD_PARTY_NOTICES.md
License-File: src/protocol_drawing/static/licenses/npm-babel-runtime-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-browser-fs-access-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-canvg-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-core-js-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-dompurify-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-dompurify-LICENSE-MPL
License-File: src/protocol_drawing/static/licenses/npm-elix-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-fflate-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-html2canvas-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-i18next-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-jspdf-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-pathseg-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-raf-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-rgbcolor-FEEL-FREE.md
License-File: src/protocol_drawing/static/licenses/npm-rgbcolor-LICENSE.md
License-File: src/protocol_drawing/static/licenses/npm-stackblur-canvas-LICENSE-MIT.txt
License-File: src/protocol_drawing/static/licenses/npm-svg2pdf.js-LICENSE
License-File: src/protocol_drawing/static/licenses/npm-utrie-LICENSE
Requires-Dist: ai-ify[web]<0.4,>=0.3
Requires-Dist: httpx>=0.27
Requires-Dist: lxml>=5
Requires-Dist: platformdirs>=4
Requires-Dist: tinycss2>=1.4
Requires-Dist: cssselect2>=0.8
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: playwright<2,>=1.49; extra == "test"
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: twine>=6; extra == "test"
Dynamic: license-file

# Protocol Drawing Studio

Draw scientific diagrams with code, then edit their vectors in your browser.
The browser editor uses SVGEdit; the embedded assistant uses the original
shared ai-ify package. Python serves the complete editor locally. Node.js is
not required to open, edit, insert library images, save, or publish an agent revision.

## Install and open

```powershell
python -m pip install protocol-drawing-studio
protocol-drawing drawing.svg
```

Run `protocol-drawing` without a filename to start a blank drawing. The command
reuses one local server and opens the user's default browser. Use
`protocol-drawing-server --port 3017` for a foreground server.

Requires Python 3.11 or later. Windows is the verified desktop platform;
Linux and macOS use portable paths and launch logic but are not yet desktop-tested.
The package provides a Windows command launcher; a standalone desktop installer
and Explorer file association are separate distribution work.

## Manual editing

Select objects on the canvas or in the Objects tree. Delete/Backspace removes
selected objects; arrows move them and Shift makes larger movements. Native
undo and redo cover edits, inserted components, layout and attached arrows.
Ungroup splits artwork into editable parts. The Components view can insert an
image into the current editor, or open it as a separate drawing.

Save working copy creates a new SVG under the user's application-data directory;
it never overwrites an opened original. Unsaved recovery, named styles and
favourite images are stored in that browser. Interface preferences follow the
browser origin rather than an account.

## Generate drawings in Python

```python
from pathlib import Path
from protocol_drawing.library import components, compose

matches = components('pipette')
svg = compose([{'component': matches[0]['id'], 'x': 100, 'y': 100, 'width': 200}])
Path('drawing.svg').write_text(svg, encoding='utf-8')
```

`components(query)` returns catalogue metadata including exact IDs and licences.
`compose` gives each instance independent vector IDs and retains attribution
inside a non-visible description. Agents can create arbitrary SVG paths, text
and groups; using a library image is optional. Keep text editable and concise.
SVG exports must be self-contained vectors, not scripts, embedded raster images
or external resources. Do not remove attribution when editing borrowed artwork.

Register newly made artwork for local reuse:

```python
from protocol_drawing.library import register_component
register_component('my-vector.svg', id='user.pipette', title='My pipette', tags=['pipette'])
```

Local components appear in the editor's library and in `components(query)`.
They live exclusively in user data. To revise a frozen component, register a
new ID. Supply the `attribution` argument with the original creator/source/licence
when registering borrowed artwork; registering does not change its licence.

## Assistant and marked feedback

The assistant panel, provider selection, conversation and browser command bridge
come from the separately maintained `ai-ify` dependency. AI use additionally
requires a configured supported provider/agent command and its own authentication;
installing the editor does not supply an AI account. Manual editing works without one.
See [ai-ify](https://github.com/Jay2owe/ai-ify) for provider setup.

Draw feedback marks over the picture, add a concise request, then send it through
the shared panel. Background mode works from the exact manually edited snapshot.
An agent writes a candidate into the supplied candidate directory and calls
`drawing.publish`. The preview applies it only if the working revision still
matches; concurrent user edits are preserved. Marks remain outside the saved SVG.
Live commands also require the current revision.

The assistant can discover images using `protocol_drawing.library.components` or
the editor's `/api/components` endpoint, and compose vectors with the Python API.
For optional React/Remotion authoring, set `PROTOCOL_DRAWING_REMOTION` to a separate
compatible project containing `tools/draw.tsx`, with Node.js and its dependencies
installed. Such a project is not part of this distribution.

## Library and licences

The public catalogue contains selected downloaded BioIcons and Health Icons
artwork. Every included record has an allowed individual licence, source URL,
creator, original source hash and recorded modifications. Full licence texts
and per-image attribution ship with the package. The Components view displays
the credits; inserted SVG groups retain them as non-visible descriptions.

This distribution contains no private experiment figures, custom reusable
components, agreed templates, output folders or local scene projects.
Images larger than the editor's 5 MiB limit, unsupported vectors, and records
outside the release licence policy are excluded by the preparation script.
See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

Original editor code: MIT, Copyright 2026 Brancaccio Lab. Third-party images
and vendor code retain their own licences; MIT does not replace those terms.

## Storage and troubleshooting

State and working files use the user's application-data directory, never the
installed package. Set `PROTOCOL_DRAWING_STATE` to override it. Server logs are
written there. Close the originating editor before using its Components tab;
an orphaned library tab cannot insert into a closed editor.

The server listens only on this computer. If startup fails, inspect
`desktop-server.log` in the state directory. A unavailable AI provider does not
require reinstalling the editor; configure it through ai-ify.

## Release development

The browser files are prepared from the maintained editor, not a second fork.
Run the parent project's `tools/prepare_public_package.py` to synchronise the
explicit source allowlist and licensed catalogue. Build wheels and source
archives with `python -m build`; check metadata with `python -m twine check dist/*`.
Test a wheel in an isolated environment outside the source checkout.
