paperus 0.0.8__tar.gz

paperus-0.0.8/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: paperus
+Version: 0.0.8
+Summary: Self-hosted research library for groups
+Keywords: research,library,papers,semantic search,self-hosted
+Author: paperus contributors
+License-Expression: Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: alembic>=1.20.1
+Requires-Dist: argon2-cffi>=25.1.0
+Requires-Dist: boto3>=1.43.124
+Requires-Dist: fastapi>=0.162.0
+Requires-Dist: httpx2>=2.16.0
+Requires-Dist: markdownify>=1.2.3
+Requires-Dist: mcp>=2.3.0,<3
+Requires-Dist: pgvector>=0.5.1
+Requires-Dist: procrastinate>=3.10,<3.11
+Requires-Dist: prometheus-client>=0.26.0
+Requires-Dist: psycopg[binary]>=3.3.8
+Requires-Dist: pybtex>=0.26.1
+Requires-Dist: pydantic-settings>=2.16.2
+Requires-Dist: pylatexenc>=2.11
+Requires-Dist: pypdfium2>=5.14.0
+Requires-Dist: python-multipart>=0.0.33
+Requires-Dist: rdflib>=7.6.0
+Requires-Dist: rispy>=0.10.0
+Requires-Dist: sqlalchemy>=2.1.8
+Requires-Dist: uvicorn[standard]>=0.54.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/qcode-uni-a/paperus
+Project-URL: Source, https://github.com/qcode-uni-a/paperus
+Project-URL: Issues, https://github.com/qcode-uni-a/paperus/issues
+Description-Content-Type: text/markdown
+
+# paperus
+
+Server of [paperus](https://github.com/qcode-uni-a/paperus), a self-hosted
+research library for groups: papers and notes in one shared library,
+searchable by words and by meaning, with your own AI assistant connected.
+
+This package contains the API, the background worker and the `paperus`
+command. Most installations use the container images instead; see the
+[installation guide](https://github.com/qcode-uni-a/paperus#installation).
+
+```sh
+pip install paperus
+paperus migrate                     # needs PAPERUS_DATABASE_URL (Postgres + pgvector)
+paperus user create alice --admin
+paperus serve                       # API on port 8000
+paperus worker                      # background jobs
+```
+
+Status: early version (0.0.x) for a pilot; expect breaking changes.

paperus-0.0.8/README.md

@@ -0,0 +1,19 @@
+# paperus
+
+Server of [paperus](https://github.com/qcode-uni-a/paperus), a self-hosted
+research library for groups: papers and notes in one shared library,
+searchable by words and by meaning, with your own AI assistant connected.
+
+This package contains the API, the background worker and the `paperus`
+command. Most installations use the container images instead; see the
+[installation guide](https://github.com/qcode-uni-a/paperus#installation).
+
+```sh
+pip install paperus
+paperus migrate                     # needs PAPERUS_DATABASE_URL (Postgres + pgvector)
+paperus user create alice --admin
+paperus serve                       # API on port 8000
+paperus worker                      # background jobs
+```
+
+Status: early version (0.0.x) for a pilot; expect breaking changes.

paperus-0.0.8/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "paperus"
+version = "0.0.8"
+description = "Self-hosted research library for groups"
+readme = "README.md"
+license = "Apache-2.0"
+keywords = [
+    "research",
+    "library",
+    "papers",
+    "semantic search",
+    "self-hosted",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "alembic>=1.20.1",
+    "argon2-cffi>=25.1.0",
+    "boto3>=1.43.124",
+    "fastapi>=0.162.0",
+    "httpx2>=2.16.0",
+    "markdownify>=1.2.3",
+    "mcp>=2.3.0,<3",
+    "pgvector>=0.5.1",
+    "procrastinate>=3.10,<3.11",
+    "prometheus-client>=0.26.0",
+    "psycopg[binary]>=3.3.8",
+    "pybtex>=0.26.1",
+    "pydantic-settings>=2.16.2",
+    "pylatexenc>=2.11",
+    "pypdfium2>=5.14.0",
+    "python-multipart>=0.0.33",
+    "rdflib>=7.6.0",
+    "rispy>=0.10.0",
+    "sqlalchemy>=2.1.8",
+    "uvicorn[standard]>=0.54.0",
+]
+
+[[project.authors]]
+name = "paperus contributors"
+
+[project.urls]
+Homepage = "https://github.com/qcode-uni-a/paperus"
+Source = "https://github.com/qcode-uni-a/paperus"
+Issues = "https://github.com/qcode-uni-a/paperus/issues"
+
+[project.scripts]
+paperus = "paperus.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13,<0.14"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "RUF",
+    "ANN",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[dependency-groups]
+dev = [
+    "moto[s3]>=5.2.5",
+    "pytest>=9.2.0",
+    "ruff>=0.17.3",
+    "ty>=0.0.97",
+    "types-boto3[s3]>=1.43.123",
+]

paperus-0.0.8/pyproject.toml.orig

@@ -0,0 +1,69 @@
+[project]
+name = "paperus"
+version = "0.0.8"
+description = "Self-hosted research library for groups"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "paperus contributors" }]
+keywords = ["research", "library", "papers", "semantic search", "self-hosted"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "alembic>=1.20.1",
+    "argon2-cffi>=25.1.0",
+    "boto3>=1.43.124",
+    "fastapi>=0.162.0",
+    "httpx2>=2.16.0",
+    "markdownify>=1.2.3",
+    "mcp>=2.3.0,<3",
+    "pgvector>=0.5.1",
+    "procrastinate>=3.10,<3.11",  # schema frozen in src/paperus/migrations/
+    "prometheus-client>=0.26.0",
+    "psycopg[binary]>=3.3.8",
+    "pybtex>=0.26.1",
+    "pydantic-settings>=2.16.2",
+    "pylatexenc>=2.11",
+    "pypdfium2>=5.14.0",
+    "python-multipart>=0.0.33",
+    "rdflib>=7.6.0",
+    "rispy>=0.10.0",
+    "sqlalchemy>=2.1.8",
+    "uvicorn[standard]>=0.54.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/qcode-uni-a/paperus"
+Source = "https://github.com/qcode-uni-a/paperus"
+Issues = "https://github.com/qcode-uni-a/paperus/issues"
+
+[project.scripts]
+paperus = "paperus.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13,<0.14"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "ANN"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error"]
+
+[dependency-groups]
+dev = [
+    "moto[s3]>=5.2.5",
+    "pytest>=9.2.0",
+    "ruff>=0.17.3",
+    "ty>=0.0.97",
+    "types-boto3[s3]>=1.43.123",
+]

paperus-0.0.8/src/paperus/__init__.py

@@ -0,0 +1,5 @@
+"""paperus: a self-hosted research library for groups."""
+
+from importlib.metadata import version
+
+__version__ = version("paperus")

paperus-0.0.8/src/paperus/access.py

@@ -0,0 +1,202 @@
+"""Who may read and change which library.
+
+A person reads their own library and those of the groups they belong to,
+including every group inside those (membership is inherited downwards, and a
+subgroup can only raise a role). Site administrators manage users and groups
+but read no library because of it. All of this is worked out once per
+request (``Access.of``) from the group tree, which is small, and the person's
+memberships; lists and searches then filter by library ID in SQL.
+"""
+
+import uuid
+from dataclasses import dataclass, field
+
+from sqlalchemy import ColumnElement, select
+from sqlalchemy.orm import Session
+
+from paperus.models import (
+    ROLE_RANK,
+    Group,
+    Item,
+    Library,
+    Membership,
+    Note,
+    Role,
+    User,
+)
+
+
+class Forbidden(Exception):
+    """The person may see this but not change it (HTTP 403)."""
+
+
+class NotVisible(Exception):
+    """The person may not see this; answered like a missing object (404)."""
+
+
+@dataclass
+class Access:
+    user: User
+    own_library: uuid.UUID
+    roles: dict[uuid.UUID, Role] = field(default_factory=dict)
+    """Effective role per group (direct or inherited)."""
+    group_libraries: dict[uuid.UUID, uuid.UUID] = field(default_factory=dict)
+    """Library of each group the person belongs to."""
+    own_allowed: bool = True
+    """False for an access token limited to some groups' libraries."""
+    site_admin: bool = False
+    """A site administrator acting in person (never through a token, which
+    gets no administration)."""
+
+    @classmethod
+    def of(
+        cls,
+        db: Session,
+        user: User,
+        only: list[uuid.UUID] | None = None,
+        *,
+        token: bool = False,
+    ) -> "Access":
+        """What ``user`` may do; with ``only`` (an access token's owner limit),
+        nothing outside these libraries; ``token``: through an access token."""
+        own = db.scalar(select(Library.id).where(Library.user_id == user.id))
+        if own is None:  # users from before libraries existed get one now
+            library = Library(user_id=user.id)
+            db.add(library)
+            db.flush()
+            own = library.id
+        parents: dict[uuid.UUID, uuid.UUID | None] = {
+            group_id: parent
+            for group_id, parent in db.execute(select(Group.id, Group.parent_id))
+        }
+        direct = {
+            group_id: Role(role)
+            for group_id, role in db.execute(
+                select(Membership.group_id, Membership.role).where(
+                    Membership.user_id == user.id
+                )
+            )
+        }
+        roles: dict[uuid.UUID, Role] = {}
+        for group_id in parents:
+            # The highest role on the way up to the top.
+            best: Role | None = None
+            current: uuid.UUID | None = group_id
+            while current is not None:
+                role = direct.get(current)
+                if role and (best is None or ROLE_RANK[role] > ROLE_RANK[best]):
+                    best = role
+                current = parents.get(current)
+            if best is not None:
+                roles[group_id] = best
+        libraries = {
+            group_id: library_id
+            for group_id, library_id in db.execute(
+                select(Library.group_id, Library.id).where(Library.group_id.in_(roles))
+            )
+            if group_id is not None
+        }
+        site_admin = user.is_admin and not token
+        if only is None:
+            return cls(user, own, roles, libraries, site_admin=site_admin)
+        allowed = set(only)
+        libraries = {g: lib for g, lib in libraries.items() if lib in allowed}
+        roles = {g: r for g, r in roles.items() if g in libraries}
+        return cls(
+            user,
+            own,
+            roles,
+            libraries,
+            own_allowed=own in allowed,
+            site_admin=site_admin,
+        )
+
+    @property
+    def readable(self) -> list[uuid.UUID]:
+        """Libraries this person may read: their own and their groups'."""
+        own = [self.own_library] if self.own_allowed else []
+        return [*own, *self.group_libraries.values()]
+
+    def role_in_library(self, library_id: uuid.UUID) -> Role | None:
+        for group_id, group_library in self.group_libraries.items():
+            if group_library == library_id:
+                return self.roles[group_id]
+        return None
+
+    def can_read(self, library_id: uuid.UUID) -> bool:
+        """The person's own library (unless a token is limited to others) or
+        one of their groups' (only those a limited token allows)."""
+        if library_id == self.own_library:
+            return self.own_allowed
+        return library_id in self.group_libraries.values()
+
+    def can_write(self, library_id: uuid.UUID) -> bool:
+        """Add, change and delete items, tags and collections."""
+        if library_id == self.own_library:
+            return self.own_allowed
+        role = self.role_in_library(library_id)
+        return role is not None and ROLE_RANK[role] >= ROLE_RANK[Role.MEMBER]
+
+    @property
+    def writable(self) -> list[uuid.UUID]:
+        return [library for library in self.readable if self.can_write(library)]
+
+    def is_group_admin(self, group_id: uuid.UUID) -> bool:
+        return self.roles.get(group_id) == Role.ADMIN
+
+    def require_write(self, library_id: uuid.UUID) -> None:
+        if not self.can_write(library_id):
+            raise Forbidden("readers cannot change this library")
+
+    # Items have one owner (``Item.library_id``): a person or a group.
+
+    def can_read_item(self, item: Item) -> bool:
+        return self.can_read(item.library_id)
+
+    def can_write_item(self, item: Item) -> bool:
+        return self.can_write(item.library_id)
+
+    def require_write_item(self, item: Item) -> None:
+        if not self.can_write_item(item):
+            raise Forbidden("readers cannot change this item")
+
+    def item_filter(
+        self, libraries: list[uuid.UUID] | None = None
+    ) -> ColumnElement[bool]:
+        """Items owned by these (by default: everything the person reads)."""
+        return Item.library_id.in_(self.readable if libraries is None else libraries)
+
+    def may_tag(self, library_id: uuid.UUID, item: Item) -> bool:
+        """Whether the person may put a tag of ``library_id`` on (or take it
+        off) the item: their private tags on any item they see; a group's
+        tags (they read) on any item they may change, e.g. their own papers
+        with the group's vocabulary."""
+        if library_id == self.own_library:
+            return self.own_allowed and self.can_read_item(item)
+        return self.can_read(library_id) and self.can_write_item(item)
+
+    def may_hold(self, library_id: uuid.UUID, item: Item | Note) -> bool:
+        """Whether a collection of ``library_id`` may hold the item (or note):
+        a group's only the group's own, a person's private ones anything the
+        person can read."""
+        if library_id == self.own_library:
+            return self.own_allowed and self.can_read(item.library_id)
+        return library_id == item.library_id
+
+    def target_library(self, requested: uuid.UUID | None) -> uuid.UUID:
+        """Where something new goes: the library asked for (if the person may
+        add to it), else their default library, else their own."""
+        if requested is not None:
+            if not self.can_read(requested):
+                raise NotVisible("library not found")
+            self.require_write(requested)
+            return requested
+        default = self.user.default_library_id
+        if default is not None and self.can_write(default):
+            return default
+        if self.own_allowed:
+            return self.own_library
+        writable = self.writable
+        if not writable:
+            raise Forbidden("this token may not add anything")
+        return writable[0]

paperus-0.0.8/src/paperus/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API routes."""