Metadata-Version: 2.4
Name: poiesis
Version: 0.1.5
Summary: An open-source, AI-assisted LaTeX editor with live preview and a Matplotlib figure builder.
Author-email: Tygo Poodt <tygopoodt2006@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/tygopoodt/poiesis
Project-URL: Repository, https://github.com/tygopoodt/poiesis
Project-URL: Issues, https://github.com/tygopoodt/poiesis/issues
Keywords: latex,editor,matplotlib,ai,research,overleaf,tectonic
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Text Editors :: Documentation
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.22.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pandas>=2.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: PyMuPDF>=1.23
Requires-Dist: dulwich>=0.22
Requires-Dist: merge3>=0.0.8
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Provides-Extra: ai
Requires-Dist: anthropic>=0.39; extra == "ai"
Provides-Extra: app
Requires-Dist: pywebview>=5.0; extra == "app"
Provides-Extra: desktop
Requires-Dist: PySide6>=6.6; extra == "desktop"
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Provides-Extra: dev-desktop
Requires-Dist: pytest-qt>=4.4; extra == "dev-desktop"
Requires-Dist: PySide6>=6.6; extra == "dev-desktop"
Dynamic: license-file

# Poiesis

**A local Overleaf, with your own GitHub as the backend and an AI that fixes
your LaTeX errors.**

[![CI](https://github.com/tygopoodt/Poiesis/actions/workflows/ci.yml/badge.svg)](https://github.com/tygopoodt/Poiesis/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

<!-- LAUNCH BLOCKER: uncomment once docs/media/demo.gif exists.
     See docs/media/README.md for what to capture. A broken image renders as a
     broken-link icon on GitHub, which is worse than no image at all.
     The URL is absolute on purpose: PyPI renders this same README, and a
     relative path resolves against pypi.org there.
![Poiesis: a compile error fixed by the AI assistant](https://raw.githubusercontent.com/tygopoodt/Poiesis/main/docs/media/demo.gif)
-->

```bash
pipx install poiesis && poiesis
```

> *poiesis* (ποίησις) — "to bring into existence." The act of making thought into form.

Poiesis runs **entirely on your machine**: a FastAPI backend and a React/Monaco
frontend. You bring your own AI key, and collaboration runs through **your own
private GitHub repos** — there is no Poiesis server, no account, and nothing to
sign up for.

> **Status:** active alpha. Everything listed under *What works today* is built
> and used daily, but APIs and UI still move quickly.

## Why not Overleaf?

| | Overleaf free tier | Poiesis |
|---|---|---|
| Full version history | Paid | Built in |
| Collaborators per project | 1 | As many as the GitHub repo has |
| Track changes | Paid | Team chat now, document comments on the roadmap |
| Git / GitHub integration | Paid | Every project *is* a git repo |
| Compile timeout | Yes | Your machine, your rules |
| AI that fixes compile errors | No | Yes |
| Works offline | No | Yes |
| Where your files live | Their servers | Your disk |

<sub>Reflects Overleaf's published free tier at the time of writing; check their
pricing page for the current terms. Poiesis is not affiliated with Overleaf.</sub>

## What works today

- **LaTeX editor** (Monaco) with syntax highlighting, a formatting toolbar, and
  LaTeX-aware autocompletion — `\cite{` completes from your `.bib` files,
  `\ref{` from every `\label{}` in the project, `\begin{` auto-closes its
  environment, and file paths complete inside `\includegraphics{`.
- **Live PDF preview** that recompiles as you type and refreshes in place.
- **Inline compile diagnostics** — log errors become red squiggles in the
  editor, and **"Fix with AI"** sends the error plus surrounding source to the
  assistant, which edits the file and recompiles until it builds.
- **SyncTeX** — click the PDF to jump to the source line, and vice versa.
- **Swappable compile backend** — [Tectonic](https://tectonic-typesetting.github.io/)
  by default (auto-downloads packages, no multi-GB TeX install), with `latexmk` /
  `pdflatex` as a fallback.
- **AI assistant** — an in-app chat that reads and edits files in your project.
  **Bring your own endpoint**: save as many OpenAI-compatible connections as you
  like (hosted gateways, a lab server, or Ollama / LM Studio / llama.cpp running
  locally with no key at all) and switch between them. The model list is read
  from the endpoint itself, and the assistant is scoped to workspace tools rather
  than a raw shell.
- **Three privacy stages** for what the assistant may see, shown in the chat
  header so you always know which one is live:
  1. **Open** — it reads the whole project.
  2. **Selective** — hide any file from its row in the file tree, or a single
     passage with <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>H</kbd> in the editor.
  3. **Structure only** — every word in every `.tex` and `.bib` is replaced by a
     meaningless one of the same length and all assets are withheld, so the
     model can still debug syntax, packages, references and line numbers without
     reading a sentence. Enforced on file reads, the file listing, the outline,
     compile logs and the Python tool alike. A model running locally is the only
     arrangement where nothing leaves your machine at all.
- **Matplotlib figure builder** — code-centric figure authoring with
  `\includegraphics` injection.
- **Version history** — commit list per project, per-file diffs, one-click
  restore. Works on synced projects and on local-only ones.
- **Citation picker** — searchable `\cite` insert over your `.bib` files; paste a
  DOI or arXiv link to fetch the BibTeX, append it, and cite it in one step.
- **arXiv-ready export** — comment-stripped sources, `.bbl` when present, styles
  and graphics only.
- **Multi-file projects** with a file tree and a workspace hub.

## Collaboration (GitHub sync)

Poiesis uses **GitHub as an invisible backend** for collaboration — each project
becomes its own **private GitHub repo**. No Poiesis servers, and every file stays
on your machine.

- **One-click GitHub sign-in** via OAuth **Device Flow** — click *Sign in with GitHub*, authorize once, and you're connected forever. No client IDs, secrets, or config (the public client ID is embedded; nothing sensitive ships).
- **Share a project** to a new private repo and **sync** automatically in the background (pure-Python git via [dulwich](https://github.com/jelmer/dulwich) — no system `git` required).
- **Invite collaborators** with a github.com-style **username autocomplete** (type a few letters, pick from a live dropdown of GitHub users).
- **See your team** — collaborator profile pictures appear on each shared project card in the hub.
- **Team chat** per project — a sidebar chat where collaborators talk and leave comments, stored persistently as comments on a dedicated GitHub Issue in the repo (history syncs to everyone, survives restarts).
- **Real-time co-editing** (optional) — live cursors and shared editing via Yjs/WebRTC, end-to-end encrypted between repo members.
- **Conflict resolution** — a visual, per-hunk merge picker (Mine / Theirs / Both) when two people edit the same lines.

## Architecture

```
src/poiesis/
├── web.py                    # `poiesis` entry point: serve + open a browser or window
├── server.py                 # FastAPI app: projects, files, compile, AI, sync
├── services/
│   ├── chat_service.py       # in-app AI assistant (OpenAI-compatible, stdlib urllib)
│   ├── sync_service.py       # GitHub-as-backend sync: OAuth device flow, dulwich git,
│   │                         #   collaborators, team chat (Issue comments), conflicts
│   ├── compile_service.py    # LaTeX compile pipeline
│   ├── synctex_service.py    # PDF ↔ source position mapping
│   └── history_service.py    # per-project commit list, diffs, restore
├── core/                     # compiler backends, document model, paths
├── static/                   # built frontend (generated; not in git)
└── ui/                       # legacy PySide6 desktop shell (app.py / main_window.py)

frontend/src/
├── App.tsx                   # editor shell, routing, shared state
├── Chat.tsx                  # AI assistant panel
├── PdfPreview.tsx            # live preview + inline PDF editing
├── FileTree.tsx              # project tree, context menus, drag/drop
├── latexIntelligence.ts      # completions, compile-log parsing, editor markers
├── sync/                     # GitHub sign-in, Share & Sync, collaborators
├── TeamChat.tsx              # per-project team chat panel
├── ConflictResolver.tsx      # visual per-hunk merge picker
└── realtime.ts               # Yjs/WebRTC live co-editing
```

**Design principle: separation of concerns.** The frontend talks only to the
FastAPI backend over HTTP. The sync engine never imports the server (it's wired in
via callables), GitHub REST/OAuth calls use only the stdlib, and git mechanics are
hidden behind a small API. A legacy PySide6 desktop shell (`poiesis.app`) is still
in the tree but the web app is the primary interface.

## Requirements

- **Python 3.10+**
- A **LaTeX engine** — but you don't have to install one yourself. On first run,
  if nothing is found, Poiesis offers to fetch its own private copy of
  [Tectonic](https://tectonic-typesetting.github.io/) (~20 MB), which downloads
  LaTeX packages on demand instead of installing several gigabytes up front.
  An engine already on your `PATH` — Tectonic, `latexmk` or `pdflatex` from TeX
  Live or MiKTeX — is used in preference and skips the prompt.
- *(Optional)* For the AI assistant: any OpenAI-compatible endpoint, added in-app.
  A hosted one needs an API key; a local runtime such as Ollama needs neither a
  key nor an internet connection.
- **Node.js 18+** — only to develop the frontend. Installing Poiesis does not
  need it; the UI ships prebuilt.

## Install

```bash
pipx install poiesis
poiesis
```

That's it — `poiesis` starts the server and opens the editor in your browser. The
UI ships prebuilt inside the package, so **Node is not required** to run it. Use
`--port`, `--host`, or `--no-browser` to change how it starts.

<sub>`pip install poiesis` works too; pipx just keeps it out of your global
environment.</sub>

### As a desktop app

Prefer a real window over a browser tab?

```bash
pipx install "poiesis[app]"
poiesis --app
```

This uses the webview your OS already ships — WebView2 on Windows, WKWebView on
macOS, WebKitGTK on Linux — so it adds about a megabyte rather than a second
browser engine, and renders the identical UI. `poiesis-app` is the same thing
without a console window, which is what you want behind a shortcut.

<sub>On Linux this also needs the system WebKitGTK packages (for example
`gir1.2-webkit2-4.1` on Debian/Ubuntu); pip cannot install those. If a window
can't be opened, Poiesis falls back to your browser instead of failing.</sub>

## Run from source (development)

```bash
git clone https://github.com/tygopoodt/Poiesis
cd Poiesis
python -m venv .venv && .venv\Scripts\activate     # macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"

python dev.py        # FastAPI backend (:8000) + Vite dev server (:5173)
```

Then open **http://localhost:5173**. `dev.py` runs `npm install` on first launch.
The backend API docs live at http://127.0.0.1:8000/docs.

To build the frontend into the package the way a release does:

```bash
python build_frontend.py && poiesis
```

> A legacy PySide6 desktop shell is still in the tree: `pip install poiesis[desktop]`,
> then `poiesis-desktop`. New features land in the web app.

## Testing

```bash
pytest                                  # backend
cd frontend && npm run build            # typecheck + build
```

CI runs both on every push, then builds a wheel, installs it into a clean
environment and checks that it actually serves the app.

## Roadmap

- [ ] LaTeX-aware spell check (ignoring commands, math and preamble).
- [ ] Comments anchored to line ranges in the document.
- [ ] Zotero integration in the citation picker.
- [ ] A WYSIWYG editing mode.
- [ ] Threaded replies / reactions in team chat.
- [ ] A guided tour of the keyboard shortcuts on first run.
- [ ] Packaged installers (`.exe` / `.dmg`) via GitHub Actions.

## Contributing

Issues and pull requests are welcome — the project is early enough that most
things are still up for discussion. Good places to start are labelled
[good first issue](https://github.com/tygopoodt/Poiesis/labels/good%20first%20issue).

## License

MIT — see [LICENSE](https://github.com/tygopoodt/Poiesis/blob/main/LICENSE).
