Metadata-Version: 2.4
Name: poiesis
Version: 0.1.1
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: 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 key**; it talks to any OpenAI-compatible endpoint (OpenRouter,
  OpenAI, DeepSeek, …) and is scoped to workspace tools, not a raw shell.
- **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
├── 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** on your `PATH`:
  - **Tectonic** (recommended) — see https://tectonic-typesetting.github.io/install.html
  - or a TeX distribution providing `latexmk` / `pdflatex` (TeX Live, MiKTeX)
- *(Optional)* An API key for any OpenAI-compatible AI provider, entered in-app.
- **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>

## 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.
- [ ] First-run onboarding: detect a missing LaTeX engine and offer to install it.
- [ ] 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).
