Metadata-Version: 2.4
Name: poiesis
Version: 0.1.8
Summary: A local Overleaf alternative: LaTeX editor with live preview, version history, GitHub collaboration and a bring-your-own-model AI.
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,latex-editor,overleaf,overleaf-alternative,tectonic,ai,ai-assistant,local-first,privacy,self-hosted,collaboration,academic-writing,research,pdf
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
Requires-Dist: pywebview>=5.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.39; extra == "ai"
Provides-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"
Requires-Dist: httpx2>=0.28; 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 alternative — a LaTeX editor that runs entirely on your
machine, with your own GitHub as the backend and an AI you actually control.**

[![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. There is **no Poiesis server, no account, and nothing to sign up for**.
Collaboration goes through **your own private GitHub repos**, and the AI
assistant talks to whichever endpoint you point it at — a hosted gateway on your
own key, or a model running on your own hardware with no internet at all.

> **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 is good software, and this isn't a takedown. But the free tier is where
most people actually live, and it is where the gaps are.

| | Overleaf free tier | Poiesis |
|---|---|---|
| Full version history | Paid — free keeps 24 hours | Built in, unlimited |
| 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 | Yes — 5 AI uses/day, their model | Your endpoint, your key, or fully local |
| What the AI reads | Your document, on their servers | Three privacy stages, down to scrambled text |
| Works offline | No | Yes |
| Account required | Yes | None |
| Where your files live | Their servers | Your disk |

<sub>Checked against Overleaf's published free tier on 2026-08-10 — their plans
change, so verify before relying on any row. Poiesis is not affiliated with
Overleaf.</sub>

### "Doesn't Overleaf already fix compile errors?"

Yes. [Error Assist](https://docs.overleaf.com/integrations-and-add-ons/ai-features/error-assist)
explains an error, shows a suggested fix and applies it — genuinely the same
loop. The difference is not the feature, it's the terms: on the free tier it
draws from an allowance of five AI uses per day across all their AI tools, and
it runs on their model, on their servers, over your document.

Poiesis puts that loop on an endpoint you choose. Your own key with no daily
cap, or Ollama on localhost where the paper never leaves the building.

### "Isn't Overleaf open source?"

[Community Edition](https://github.com/overleaf/overleaf) is, under AGPL, and
you can self-host it. It's a real option and worth knowing about.

The difference is what you end up running. CE is a Docker stack with MongoDB and
Redis that you maintain; Poiesis is `pipx install poiesis`. CE ships no AI
features. And Poiesis has no server to host in the first place — it's a local
app, so "self-hosting" is just running it.

If you want one shared instance for a whole department, run Overleaf CE. If you
want an editor on your own laptop that syncs through GitHub, that's this.

## 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.
- **Data figures the assistant draws itself** — point it at the CSV or Excel
  file already in your project and it reads the data, plots it with matplotlib,
  saves the image into `assets/` and includes it in the document. It stays in
  TikZ for diagrams and small hand-typed plots, and reaches for Python only when
  the figure is real data. Switch it off under *Settings › Permissions* and every
  figure it makes is TikZ.
- **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.

<!-- LAUNCH BLOCKER: uncomment each block once the file exists. Briefs are in
     docs/media/README.md. URLs are absolute on purpose — PyPI renders this same
     README, and a relative path resolves against pypi.org there. A broken image
     renders as a broken-link icon, which is worse than no image at all.

## Screenshots

### The editor
![The Poiesis editor: file tree, LaTeX source, and live PDF preview side by side](https://raw.githubusercontent.com/tygopoodt/Poiesis/main/docs/media/editor.png)

### Version history
![Per-file diffs in the version history pane, with one-click restore](https://raw.githubusercontent.com/tygopoodt/Poiesis/main/docs/media/history.png)

### Collaboration
![Team chat beside the editor, with collaborator avatars on the project](https://raw.githubusercontent.com/tygopoodt/Poiesis/main/docs/media/collab.png)
-->

## Architecture

```
src/poiesis/
├── web.py                    # `poiesis` entry point: serve + open a browser or window
├── server.py                 # stable import surface; re-exports from api/
├── api/
│   ├── app.py                # builds the FastAPI app and mounts the frontend
│   ├── routes/               # endpoints by feature: compile, files, projects,
│   │                         #   history, intel, snippets, sync, engines, ai
│   ├── assistant/            # the AI tool layer: prompt, tools, dispatch, skills
│   ├── workspace.py          # the open project and its path-containment rules
│   └── runtime.py            # background sync daemon + activity ledger
├── services/
│   ├── chat_service.py       # in-app AI assistant (OpenAI-compatible, stdlib urllib)
│   ├── sync_service/         # GitHub-as-backend sync: OAuth device flow, dulwich git,
│   │                         #   collaborators, team chat (Issue comments), conflicts
│   ├── privacy_service/      # what the assistant may see: redaction, hidden passages
│   ├── python_runner.py      # runs one matplotlib script in a sandboxed subprocess
│   ├── compile_service.py    # LaTeX compile pipeline
│   ├── synctex_service.py    # PDF ↔ source position mapping
│   └── history_service.py    # per-project commit list, diffs, restore
├── documents/                # template spec, renderers, new-project scaffolding
├── 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
├── index.css                 # import manifest; the rules live in styles/
├── styles/                   # the stylesheet, split by UI area (order matters)
├── chat/                     # assistant panel internals: messages, thought trail
├── sync/                     # GitHub sign-in, Share & Sync, collaborators
├── settings/                 # settings modal: engines, connections, privacy
├── modals/                   # shared dialogs (create item, unsaved changes, ...)
├── tikz/                     # TikZ figure builder canvas and interactions
├── pdfEdit/                  # direct-on-PDF text editing
├── 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.

`poiesis.server` used to hold all of this in one 4,000-line module. It is now a
thin re-export over `poiesis.api` and stays put because it is the import string
uvicorn is pointed at — but new code should import from the module that actually
defines the name.

## 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` opens the editor **in its own window**, not a browser tab.
The UI ships prebuilt inside the package, so **Node is not required** to run it.

The window is the webview your OS already ships — WebView2 on Windows, WKWebView
on macOS, WebKitGTK on Linux — so Poiesis bundles no second browser engine.
`poiesis-app` is the same thing with no console behind it, which is what you
want on a shortcut.

| | |
|---|---|
| `poiesis` | native window (falls back to the browser if none is available) |
| `poiesis --browser` | your web browser instead |
| `poiesis --no-browser` | serve only, open nothing |
| `--host`, `--port` | change where it binds |

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

<sub>**Linux:** the window needs a GTK binding that pip does not pull in by
default. Install the system packages first (`sudo apt install
python3-gi gir1.2-webkit2-4.1` on Debian/Ubuntu), then `pip install
'pywebview[gtk]'`. Skip it if you don't care — without a usable webview,
Poiesis opens your browser instead of failing. macOS and Windows need nothing
extra.</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).
