Metadata-Version: 2.4
Name: aems-agent
Version: 0.3.2
Summary: AEMS Local Bridge Agent — local filesystem access for exam PDFs
Project-URL: Homepage, https://aems.app
Project-URL: Repository, https://github.com/aems-app/aems-agent
Project-URL: Issues, https://github.com/aems-app/aems-agent/issues
Project-URL: Changelog, https://github.com/aems-app/aems-agent/blob/main/CHANGELOG.md
Author-email: AEMS Team <contact@aems.app>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: aems,agent,grading,local-bridge,pdf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Education
Requires-Python: >=3.10
Requires-Dist: aems-pdf-annotator<0.3.0,>=0.2.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pymupdf>=1.25.0
Requires-Dist: pynacl>=1.5.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: build
Requires-Dist: pyinstaller<7.0.0,>=6.0.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: httpx>=0.25.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: tray
Requires-Dist: pillow>=10.0.0; extra == 'tray'
Requires-Dist: pystray>=0.19.0; extra == 'tray'
Description-Content-Type: text/markdown

# AEMS Local Bridge Agent

> **As of v0.3.2 (2026-05-11), this package is licensed under AGPL-3.0-or-later (previously MIT).** The agent links [PyMuPDF](https://github.com/pymupdf/PyMuPDF) in-process via [`aems-pdf-annotator`](https://github.com/aems-app/aems-pdf-annotator), and AGPL applies to the combined work. See [LICENSE](LICENSE) for the full text.

A lightweight companion service that runs on `localhost` and provides REST API access to the local filesystem, enabling the [AEMS](https://aems.app) hosted app to read/write exam PDFs to a user-chosen folder without ever uploading source PDFs to the server.

## What it does

- Runs as a local service on `127.0.0.1:61234` (default).
- Exposes an authenticated REST API the AEMS web app uses to read source PDFs and write annotated PDFs from your local storage folder.
- Optional system-tray icon so it's visible while running.
- Optional offline grading bundle support for fully-local workflows.
- Never sends PDF content out unless the user explicitly attaches a Canvas / offline workflow in the hosted app.

## Installation

### Binary installers (recommended for end users)

Pre-built installers — no Python needed — are on the [Releases page](https://github.com/aems-app/aems-agent/releases/latest).

| Platform | File | Notes |
|----------|------|-------|
| Windows | `aems-agent-setup.exe` | Installs to `%LOCALAPPDATA%\AEMS Agent` |
| macOS   | `AEMS-Agent.dmg`       | Drag to Applications |
| Linux   | `aems-agent-linux.tar.gz` | Extract and run `./aems-agent run` |

### pip (for developers)

```bash
pip install aems-agent
```

Requires Python 3.10+.

## Usage

```bash
# Print version and exit
aems-agent --version

# Start the agent (default: http://127.0.0.1:61234)
aems-agent run

# Start with system tray icon
aems-agent run --tray

# Custom port/host
aems-agent run --port 9000 --host 0.0.0.0

# Show auth token (the hosted app pairs against this token)
aems-agent token

# Set storage path
aems-agent set-path /path/to/exam/folder

# Show config directory
aems-agent config-dir
```

After `aems-agent run`, open AEMS in your browser, go to **Settings → Storage**, and pair the agent.

## License

AGPL-3.0-or-later. See [LICENSE](LICENSE).

**Relicense note (v0.3.2, 2026-05-11):** Versions ≤ 0.3.1 were licensed under MIT. From v0.3.2 the agent is AGPL-3.0-or-later because it links PyMuPDF (AGPL-3.0) in-process via `aems-pdf-annotator`. The MIT licence that previously applied to forks of v0.3.1 and earlier remains in effect for those versions.

## Links

- Homepage: [https://aems.app](https://aems.app)
- Source: [https://github.com/aems-app/aems-agent](https://github.com/aems-app/aems-agent)
- Issues: [https://github.com/aems-app/aems-agent/issues](https://github.com/aems-app/aems-agent/issues)
- Annotation engine: [aems-pdf-annotator](https://github.com/aems-app/aems-pdf-annotator)
