annals 0.0.3__tar.gz

annals-0.0.3/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

annals-0.0.3/.gitignore

@@ -0,0 +1,119 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

annals-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

annals-0.0.3/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: annals
+Version: 0.0.3
+Summary: Annals for AI agents: publish markdown, html, images, video, audio, PDFs and folders to a private page the owner reads on the phone, and get back a link.
+Project-URL: Homepage, https://github.com/thorwhalen/annals
+Project-URL: Repository, https://github.com/thorwhalen/annals
+Project-URL: Documentation, https://thorwhalen.github.io/annals
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude-code,html,in-tray,markdown,media,page,private,publish
+Requires-Python: >=3.11
+Requires-Dist: cw<0.2,>=0.1
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pillow>=10; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: mcp
+Requires-Dist: py2mcp; extra == 'mcp'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.100; extra == 'server'
+Requires-Dist: pillow>=10; extra == 'server'
+Requires-Dist: uvicorn>=0.20; extra == 'server'
+Description-Content-Type: text/markdown
+
+# annals
+
+Annals for AI agents. An agent publishes a document (markdown, html, an image, a video, a PDF, or a whole folder of renders) with one command and gets back a link; the owner opens their annals on a phone and finds everything their agents left for them, newest first, searchable, with a recycle bin.
+
+```bash
+pip install annals
+annals publish report.md --session my-agent
+# https://apps.example.com/annals/d/20261003-203301-quarterly-report-3f9a
+```
+
+Documents are plain files in a directory. The directory can be on this machine or on another one over ssh, and the page that serves it reads it directly, so publishing never redeploys anything. No database, no build step, no API token.
+
+## For agents
+
+Load the shipped skill, `annals-publish`, and you have the whole protocol: one command, one link, put the link in your reply.
+
+```bash
+annals publish report.md                          # one document, prints its link
+annals publish a.md b.md c.html --group "Review"  # one link for a set (the group link prints first)
+annals publish ./renders                          # a folder: a gallery with inline images, video, audio
+annals publish ./site_dir                         # an html page with its assets, as one document
+annals publish clip.mp4                           # media plays inline (streamed, seekable)
+some-command | annals publish - --title "Log"     # from stdin
+annals ls "search words"                          # what is there, newest first
+annals trash <id>  /  annals restore <id>         # the recycle bin
+```
+
+What each kind looks like on the page:
+
+| Published | Shown as |
+|---|---|
+| a `.md` file | rendered markdown, with a toggle to the source and a copy button; its relative images and links resolve to its own files |
+| an `.html` file, or a folder with `index.html` | the page itself, in a sandboxed frame |
+| an image, video, audio file or PDF | inline: image, player (byte-range streaming, so video seeks), PDF viewer |
+| a folder with one page in it | that page, with the other files below it |
+| any other folder | a gallery: image thumbnails (a page at a time), players, a file list; every file opens on its own with prev/next |
+| anything else | a download |
+
+A folder skips hidden files and caches (`.*`, `__pycache__`, `*.pyc`); `--all-files` keeps them.
+
+With `pip install 'annals[mcp]'`, the same operations are an MCP server: `python -m annals.mcp`.
+
+## Where documents go
+
+```bash
+annals configure --target tw:/root/.local/share/annals --base-url https://apps.example.com/annals
+```
+
+That writes `~/.config/annals/config.toml`. `target` is a directory, or `host:/path` for a directory on another machine reached by `ssh host` (keys, no prompt; `host` can be an alias from `~/.ssh/config`). `ANNALS_TARGET` and `ANNALS_BASE_URL` override it per shell. With no configuration, documents go to `~/.local/share/annals` and the link points at a local `annals serve`.
+
+## Hosting the page
+
+**Inside an app platform** (the usual case). Mount the API under the platform's prefix and let the platform's login gate it:
+
+```python
+# server.py of the host app; the platform serves frontend/ at /annals/ and this at /api/annals
+from annals.api import mk_api
+app = mk_api(data_dir="/root/.local/share/annals")
+```
+
+and write the page shell once as the app's frontend:
+
+```bash
+annals page-shell --api /api/annals --base /annals > frontend/index.html
+```
+
+The shell only names those two paths; the page's script and style load from the API, so upgrading the package upgrades the page. Gallery thumbnails are made with Pillow when it is installed (cached under the data root's `cache/`), and fall back to the original image when it is not.
+
+**Standalone**, for a machine with no platform:
+
+```bash
+pip install 'annals[server]'
+ANNALS_DATA_DIR=~/.local/share/annals annals serve --host 127.0.0.1 --port 8765
+```
+
+The page is at `http://127.0.0.1:8765/annals/`, its API under `/annals/api/`. Auth is chosen by environment variables:
+
+| Situation | Set | Effect |
+|---|---|---|
+| Behind an existing login that exposes a who-am-I endpoint | `ANNALS_WHOAMI_URL`, `ANNALS_ALLOWED_USERS=me@example.com`, optionally `ANNALS_LOGIN_URL=/auth/login` | the browser's cookies are forwarded to that endpoint and the listed emails are allowed; anyone else is sent to the login page |
+| No platform login | `ANNALS_BASIC_USER`, `ANNALS_BASIC_PASSWORD` | HTTP Basic |
+| Localhost only | nothing | open |
+
+## Python API
+
+```python
+from annals import DocStore, publish
+meta = DocStore("~/.local/share/annals").publish("report.md", tags=["q3"])
+publish(["report.md"], tags="q3")["url"]          # same, through the configured target
+```
+
+`annals.api.mk_api(...)` is the mountable API; `annals.api.mk_app(data_dir=..., authorizer=...)` the standalone app.
+
+## Design notes
+
+Flat store with tags and groups, not a hierarchy: agents from many projects do not share one, and every placement decision costs tokens. A document is `docs/<id>/meta.json` plus its files; the bin is `trash/<id>/`; a group is `groups/<gid>.json`. Ids are `YYYYMMDD-HHMMSS-<slug>-<4 hex>`, so a listing is already in time order and a URL says what it points to. The transport is a seam (`annals.target`): local directory, ssh, and later an http ingest endpoint. More in `misc/docs/design.md`.
+
+## Skills
+
+```bash
+gh skill install thorwhalen/annals annals-publish
+```
+
+The skill also ships inside the package at `annals/data/skills/annals-publish/`.

annals-0.0.3/README.md

@@ -0,0 +1,104 @@
+# annals
+
+Annals for AI agents. An agent publishes a document (markdown, html, an image, a video, a PDF, or a whole folder of renders) with one command and gets back a link; the owner opens their annals on a phone and finds everything their agents left for them, newest first, searchable, with a recycle bin.
+
+```bash
+pip install annals
+annals publish report.md --session my-agent
+# https://apps.example.com/annals/d/20261003-203301-quarterly-report-3f9a
+```
+
+Documents are plain files in a directory. The directory can be on this machine or on another one over ssh, and the page that serves it reads it directly, so publishing never redeploys anything. No database, no build step, no API token.
+
+## For agents
+
+Load the shipped skill, `annals-publish`, and you have the whole protocol: one command, one link, put the link in your reply.
+
+```bash
+annals publish report.md                          # one document, prints its link
+annals publish a.md b.md c.html --group "Review"  # one link for a set (the group link prints first)
+annals publish ./renders                          # a folder: a gallery with inline images, video, audio
+annals publish ./site_dir                         # an html page with its assets, as one document
+annals publish clip.mp4                           # media plays inline (streamed, seekable)
+some-command | annals publish - --title "Log"     # from stdin
+annals ls "search words"                          # what is there, newest first
+annals trash <id>  /  annals restore <id>         # the recycle bin
+```
+
+What each kind looks like on the page:
+
+| Published | Shown as |
+|---|---|
+| a `.md` file | rendered markdown, with a toggle to the source and a copy button; its relative images and links resolve to its own files |
+| an `.html` file, or a folder with `index.html` | the page itself, in a sandboxed frame |
+| an image, video, audio file or PDF | inline: image, player (byte-range streaming, so video seeks), PDF viewer |
+| a folder with one page in it | that page, with the other files below it |
+| any other folder | a gallery: image thumbnails (a page at a time), players, a file list; every file opens on its own with prev/next |
+| anything else | a download |
+
+A folder skips hidden files and caches (`.*`, `__pycache__`, `*.pyc`); `--all-files` keeps them.
+
+With `pip install 'annals[mcp]'`, the same operations are an MCP server: `python -m annals.mcp`.
+
+## Where documents go
+
+```bash
+annals configure --target tw:/root/.local/share/annals --base-url https://apps.example.com/annals
+```
+
+That writes `~/.config/annals/config.toml`. `target` is a directory, or `host:/path` for a directory on another machine reached by `ssh host` (keys, no prompt; `host` can be an alias from `~/.ssh/config`). `ANNALS_TARGET` and `ANNALS_BASE_URL` override it per shell. With no configuration, documents go to `~/.local/share/annals` and the link points at a local `annals serve`.
+
+## Hosting the page
+
+**Inside an app platform** (the usual case). Mount the API under the platform's prefix and let the platform's login gate it:
+
+```python
+# server.py of the host app; the platform serves frontend/ at /annals/ and this at /api/annals
+from annals.api import mk_api
+app = mk_api(data_dir="/root/.local/share/annals")
+```
+
+and write the page shell once as the app's frontend:
+
+```bash
+annals page-shell --api /api/annals --base /annals > frontend/index.html
+```
+
+The shell only names those two paths; the page's script and style load from the API, so upgrading the package upgrades the page. Gallery thumbnails are made with Pillow when it is installed (cached under the data root's `cache/`), and fall back to the original image when it is not.
+
+**Standalone**, for a machine with no platform:
+
+```bash
+pip install 'annals[server]'
+ANNALS_DATA_DIR=~/.local/share/annals annals serve --host 127.0.0.1 --port 8765
+```
+
+The page is at `http://127.0.0.1:8765/annals/`, its API under `/annals/api/`. Auth is chosen by environment variables:
+
+| Situation | Set | Effect |
+|---|---|---|
+| Behind an existing login that exposes a who-am-I endpoint | `ANNALS_WHOAMI_URL`, `ANNALS_ALLOWED_USERS=me@example.com`, optionally `ANNALS_LOGIN_URL=/auth/login` | the browser's cookies are forwarded to that endpoint and the listed emails are allowed; anyone else is sent to the login page |
+| No platform login | `ANNALS_BASIC_USER`, `ANNALS_BASIC_PASSWORD` | HTTP Basic |
+| Localhost only | nothing | open |
+
+## Python API
+
+```python
+from annals import DocStore, publish
+meta = DocStore("~/.local/share/annals").publish("report.md", tags=["q3"])
+publish(["report.md"], tags="q3")["url"]          # same, through the configured target
+```
+
+`annals.api.mk_api(...)` is the mountable API; `annals.api.mk_app(data_dir=..., authorizer=...)` the standalone app.
+
+## Design notes
+
+Flat store with tags and groups, not a hierarchy: agents from many projects do not share one, and every placement decision costs tokens. A document is `docs/<id>/meta.json` plus its files; the bin is `trash/<id>/`; a group is `groups/<gid>.json`. Ids are `YYYYMMDD-HHMMSS-<slug>-<4 hex>`, so a listing is already in time order and a URL says what it points to. The transport is a seam (`annals.target`): local directory, ssh, and later an http ingest endpoint. More in `misc/docs/design.md`.
+
+## Skills
+
+```bash
+gh skill install thorwhalen/annals annals-publish
+```
+
+The skill also ships inside the package at `annals/data/skills/annals-publish/`.

annals-0.0.3/annals/__init__.py

@@ -0,0 +1,29 @@
+"""annals: an in-tray for AI agents. Publish documents and media to a private page; get a link.
+
+Agents call :func:`annals.tools.publish` (or ``annals publish file.md`` from a shell) and hand
+the printed URL to their human, who opens it on a phone. The documents are plain files in a
+directory, local or on another machine over ssh; :func:`annals.api.mk_app` serves that
+directory as a private page with search, sort, groups and a recycle bin.
+"""
+
+from annals.config import Settings, load_settings
+from annals.store import DocStore
+from annals.target import LocalTarget, SshTarget, parse_target
+from annals.tools import configure, group, groups, ls, publish, restore, show, trash
+
+__all__ = [
+    "DocStore",
+    "LocalTarget",
+    "Settings",
+    "SshTarget",
+    "configure",
+    "group",
+    "groups",
+    "load_settings",
+    "ls",
+    "parse_target",
+    "publish",
+    "restore",
+    "show",
+    "trash",
+]

annals-0.0.3/annals/__main__.py

@@ -0,0 +1,72 @@
+# PYTHON_ARGCOMPLETE_OK
+"""CLI entry point: ``annals publish report.md`` prints a link. Built by ``cw`` over :mod:`annals.tools`."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import cw
+
+from annals.tools import _dispatch_funcs
+
+#: the shape ``publish`` returns for one document; only that shape prints as a bare link
+PUBLISH_KEYS = frozenset({"id", "title", "url", "group_id", "group_url", "warning"})
+#: expected failures: one line on stderr and exit 1, no traceback
+EXPECTED_ERRORS = (
+    ValueError,
+    KeyError,
+    FileNotFoundError,
+    PermissionError,
+    RuntimeError,
+)
+
+
+def _egress(result, *, out=None, err=None) -> int:
+    """Print a link when there is one (that is what an agent wants back), else JSON."""
+    out = out or sys.stdout
+    if result is None:
+        return 0
+    if isinstance(result, dict) and result.get("warning"):
+        print(f"annals: warning: {result.pop('warning')}", file=err or sys.stderr)
+    if isinstance(result, str):
+        print(result, file=out, end="" if result.endswith("\n") else "\n")
+        return 0
+    if isinstance(result, dict) and "url" in result and set(result) <= PUBLISH_KEYS:
+        print(result["url"], file=out)
+        if "group_url" in result and result["group_url"] != result["url"]:
+            print(result["group_url"], file=out)
+        return 0
+    if isinstance(result, dict) and "docs" in result and "group_url" in result:
+        print(result["group_url"], file=out)
+        for d in result["docs"]:
+            print(f"  {d['url']}  {d['title']}", file=out)
+        return 0
+    print(json.dumps(result, indent=1, ensure_ascii=False), file=out)
+    return 0
+
+
+def run(argv=None, *, out=None, err=None) -> int:
+    """Dispatch ``argv`` (default ``sys.argv[1:]``) and return the exit code."""
+    try:
+        return cw.dispatch(
+            _dispatch_funcs,
+            argv,
+            prog="annals",
+            convention=cw.MODERN,
+            egress=_egress,
+            out=out,
+            err=err,
+        )
+    except EXPECTED_ERRORS as e:
+        print(f"annals: {type(e).__name__}: {e}", file=err or sys.stderr)
+        return 1
+
+
+def main() -> None:
+    """Console-script entry point."""
+    raise SystemExit(run())
+
+
+if __name__ == "__main__":
+    main()