wst-library 0.1.0__tar.gz

wst_library-0.1.0/LICENSE

@@ -0,0 +1,50 @@
+MIT License with Commons Clause
+
+Copyright (c) 2026 cnexans
+
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as
+defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights
+under the License will not include, and the License does not grant to
+you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of
+the rights granted to you under the License to provide to third
+parties, for a fee or other consideration (including without
+limitation fees for hosting or consulting/support services related to
+the Software), a product or service whose value derives, entirely or
+substantially, from the functionality of the Software. Any license
+notice or attribution required by the License must also include this
+Commons Clause License Condition notice.
+
+Software: wst
+
+License: MIT License
+
+Licensor: cnexans
+
+---
+
+MIT License
+
+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, and/or sublicense 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.

wst_library-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: wst-library
+Version: 0.1.0
+Summary: CLI tool for organizing books and PDFs with AI-powered metadata
+Author: cnexans
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/cnexans/wst
+Project-URL: Repository, https://github.com/cnexans/wst
+Project-URL: Issues, https://github.com/cnexans/wst/issues
+Keywords: pdf,books,library,metadata,cli,organizer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: InquirerPy>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# wst — Wan Shi Tong
+
+<div align="center">
+
+<img src="docs/images/wan-shi-tong.png" alt="Wan Shi Tong" width="300">
+
+*"I am Wan Shi Tong, he who knows ten thousand things."*
+
+<sub>Character from Avatar: The Last Airbender. Avatar: The Last Airbender is a trademark of Viacom International Inc. Image used for illustrative purposes only.</sub>
+
+</div>
+
+---
+
+CLI tool for organizing books and PDFs with AI-powered metadata generation.
+
+Named after **Wan Shi Tong**, the ancient spirit who collected every piece of knowledge in the world and guarded the great library in the desert. This tool aspires to do the same for your PDFs — just with less hostility toward humans.
+
+## Features
+
+- **AI-powered metadata**: Automatically extracts and completes metadata (title, author, type, year, summary, tags, etc.) using Claude CLI with web search for missing fields (year, ISBN, publisher)
+- **Organized library**: Files sorted by type (`books/`, `papers/`, `notes/`, `exercises/`, `guides/`) with consistent naming (`Author - Title (Year).pdf`)
+- **SQLite search index**: Full-text search across title, author, tags, subject, and summary via FTS5
+- **Interactive browser**: Fuzzy-search your library, view and edit metadata interactively
+- **Cloud backup**: Backup files to iCloud Drive (macOS/Windows), with extensible provider system for future S3 support
+- **Extensible backends**: Abstract layers for AI (Claude CLI, future API/SDK) and storage (local filesystem, future S3)
+
+## Installation
+
+### pipx (recommended, all platforms)
+
+```bash
+pipx install wst-library
+```
+
+### pip
+
+```bash
+pip install wst-library
+```
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew tap cnexans/tap
+brew install wst
+```
+
+### Chocolatey (Windows)
+
+```powershell
+choco install wst
+```
+
+### From source
+
+```bash
+git clone https://github.com/cnexans/wst.git
+cd wst
+make install
+```
+
+## Quick Start
+
+```bash
+# Ingest PDFs from a folder
+wst ingest ~/Documents/papers/
+
+# Ingest from current directory
+wst ingest .
+
+# Ingest from default inbox (~/wst/inbox/)
+wst ingest
+
+# Ingest with manual confirmation for each file
+wst ingest --confirm
+
+# Re-ingest files with fresh AI metadata (e.g. after enabling web search)
+wst ingest --reprocess
+
+# Search
+wst search "machine learning"
+wst search --author "Knuth"
+wst search --type textbook
+wst search --subject "Mathematics"
+
+# List all documents
+wst list
+wst list --type paper --sort year
+
+# Show full details
+wst show 1
+wst show "Design Patterns"
+
+# Interactive browser — fuzzy search, view and edit metadata
+wst browse
+
+# Edit a specific document
+wst edit 1
+wst edit "Player's Handbook"
+
+# Backup to iCloud
+wst backup icloud                    # interactive: all or select file
+wst backup icloud 1                  # backup specific file by ID
+wst backup icloud "Player's Handbook" # backup by title
+wst backup                           # interactive: choose provider
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `wst ingest [PATH] [--confirm] [--reprocess]` | Ingest PDFs from a path or the inbox, generate metadata with AI |
+| `wst search <query> [--author] [--type] [--subject]` | Full-text search across the index |
+| `wst list [--type] [--sort]` | List all documents in the library |
+| `wst show <id-or-title>` | Show complete metadata for a document |
+| `wst edit <id-or-title>` | Interactively edit metadata for a document |
+| `wst browse` | Interactive TUI for browsing and editing documents |
+| `wst backup [provider] [id-or-title]` | Backup files to a cloud provider (iCloud, future S3) |
+
+## Library Structure
+
+```
+~/wst/
+├── inbox/           # PDFs pending ingestion
+└── library/
+    ├── books/       # book, novel, textbook
+    ├── papers/      # paper
+    ├── notes/       # class-notes
+    ├── exercises/   # exercises
+    ├── guides/      # guide-theory, guide-practice
+    └── wst.db       # SQLite index
+```
+
+## Documentation
+
+See [docs/README.md](docs/README.md) for architecture details and diagrams.
+
+## Requirements
+
+- Python 3.11+
+- `claude` CLI (authenticated) for AI metadata generation
+- macOS, Windows, or Linux
+
+## License
+
+MIT with Commons Clause — free to use, modify, and distribute. Commercial sale rights reserved to the author. See [LICENSE](LICENSE).

wst_library-0.1.0/README.md

@@ -0,0 +1,147 @@
+# wst — Wan Shi Tong
+
+<div align="center">
+
+<img src="docs/images/wan-shi-tong.png" alt="Wan Shi Tong" width="300">
+
+*"I am Wan Shi Tong, he who knows ten thousand things."*
+
+<sub>Character from Avatar: The Last Airbender. Avatar: The Last Airbender is a trademark of Viacom International Inc. Image used for illustrative purposes only.</sub>
+
+</div>
+
+---
+
+CLI tool for organizing books and PDFs with AI-powered metadata generation.
+
+Named after **Wan Shi Tong**, the ancient spirit who collected every piece of knowledge in the world and guarded the great library in the desert. This tool aspires to do the same for your PDFs — just with less hostility toward humans.
+
+## Features
+
+- **AI-powered metadata**: Automatically extracts and completes metadata (title, author, type, year, summary, tags, etc.) using Claude CLI with web search for missing fields (year, ISBN, publisher)
+- **Organized library**: Files sorted by type (`books/`, `papers/`, `notes/`, `exercises/`, `guides/`) with consistent naming (`Author - Title (Year).pdf`)
+- **SQLite search index**: Full-text search across title, author, tags, subject, and summary via FTS5
+- **Interactive browser**: Fuzzy-search your library, view and edit metadata interactively
+- **Cloud backup**: Backup files to iCloud Drive (macOS/Windows), with extensible provider system for future S3 support
+- **Extensible backends**: Abstract layers for AI (Claude CLI, future API/SDK) and storage (local filesystem, future S3)
+
+## Installation
+
+### pipx (recommended, all platforms)
+
+```bash
+pipx install wst-library
+```
+
+### pip
+
+```bash
+pip install wst-library
+```
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew tap cnexans/tap
+brew install wst
+```
+
+### Chocolatey (Windows)
+
+```powershell
+choco install wst
+```
+
+### From source
+
+```bash
+git clone https://github.com/cnexans/wst.git
+cd wst
+make install
+```
+
+## Quick Start
+
+```bash
+# Ingest PDFs from a folder
+wst ingest ~/Documents/papers/
+
+# Ingest from current directory
+wst ingest .
+
+# Ingest from default inbox (~/wst/inbox/)
+wst ingest
+
+# Ingest with manual confirmation for each file
+wst ingest --confirm
+
+# Re-ingest files with fresh AI metadata (e.g. after enabling web search)
+wst ingest --reprocess
+
+# Search
+wst search "machine learning"
+wst search --author "Knuth"
+wst search --type textbook
+wst search --subject "Mathematics"
+
+# List all documents
+wst list
+wst list --type paper --sort year
+
+# Show full details
+wst show 1
+wst show "Design Patterns"
+
+# Interactive browser — fuzzy search, view and edit metadata
+wst browse
+
+# Edit a specific document
+wst edit 1
+wst edit "Player's Handbook"
+
+# Backup to iCloud
+wst backup icloud                    # interactive: all or select file
+wst backup icloud 1                  # backup specific file by ID
+wst backup icloud "Player's Handbook" # backup by title
+wst backup                           # interactive: choose provider
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `wst ingest [PATH] [--confirm] [--reprocess]` | Ingest PDFs from a path or the inbox, generate metadata with AI |
+| `wst search <query> [--author] [--type] [--subject]` | Full-text search across the index |
+| `wst list [--type] [--sort]` | List all documents in the library |
+| `wst show <id-or-title>` | Show complete metadata for a document |
+| `wst edit <id-or-title>` | Interactively edit metadata for a document |
+| `wst browse` | Interactive TUI for browsing and editing documents |
+| `wst backup [provider] [id-or-title]` | Backup files to a cloud provider (iCloud, future S3) |
+
+## Library Structure
+
+```
+~/wst/
+├── inbox/           # PDFs pending ingestion
+└── library/
+    ├── books/       # book, novel, textbook
+    ├── papers/      # paper
+    ├── notes/       # class-notes
+    ├── exercises/   # exercises
+    ├── guides/      # guide-theory, guide-practice
+    └── wst.db       # SQLite index
+```
+
+## Documentation
+
+See [docs/README.md](docs/README.md) for architecture details and diagrams.
+
+## Requirements
+
+- Python 3.11+
+- `claude` CLI (authenticated) for AI metadata generation
+- macOS, Windows, or Linux
+
+## License
+
+MIT with Commons Clause — free to use, modify, and distribute. Commercial sale rights reserved to the author. See [LICENSE](LICENSE).

wst_library-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "wst-library"
+version = "0.1.0"
+description = "CLI tool for organizing books and PDFs with AI-powered metadata"
+readme = "README.md"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{name = "cnexans"}]
+keywords = ["pdf", "books", "library", "metadata", "cli", "organizer"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "click>=8.0",
+    "pymupdf>=1.24",
+    "pydantic>=2.0",
+    "InquirerPy>=0.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/cnexans/wst"
+Repository = "https://github.com/cnexans/wst"
+Issues = "https://github.com/cnexans/wst/issues"
+
+[project.scripts]
+wst = "wst.cli:cli"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wst_library-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wst_library-0.1.0/src/wst/__init__.py

@@ -0,0 +1 @@
+"""wst — CLI tool for organizing books and PDFs."""

wst_library-0.1.0/src/wst/ai.py

@@ -0,0 +1,110 @@
+import json
+import re
+import subprocess
+from abc import ABC, abstractmethod
+
+from wst.models import DocumentMetadata
+
+
+class AIBackend(ABC):
+    @abstractmethod
+    def generate_metadata(
+        self, existing_meta: dict, text_sample: str, filename: str
+    ) -> DocumentMetadata: ...
+
+
+class ClaudeCLIBackend(AIBackend):
+    def __init__(self, model: str = "sonnet"):
+        self.model = model
+
+    def generate_metadata(
+        self, existing_meta: dict, text_sample: str, filename: str
+    ) -> DocumentMetadata:
+        schema = json.dumps(DocumentMetadata.model_json_schema())
+        prompt = self._build_prompt(existing_meta, text_sample, filename, schema)
+
+        result = subprocess.run(
+            [
+                "claude",
+                "-p",
+                "--model",
+                self.model,
+                "--output-format",
+                "json",
+                "--allowedTools",
+                "WebSearch",
+                "WebFetch",
+            ],
+            input=prompt,
+            capture_output=True,
+            text=True,
+            timeout=180,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"claude CLI failed: {result.stderr}")
+
+        wrapper = json.loads(result.stdout)
+        raw = wrapper.get("result", "")
+
+        return DocumentMetadata.model_validate(self._extract_json(raw))
+
+    @staticmethod
+    def _extract_json(text: str) -> dict:
+        """Extract JSON object from a response that may contain markdown fences."""
+        # Try direct parse first
+        text = text.strip()
+        if text.startswith("{"):
+            return json.loads(text)
+        # Extract from ```json ... ``` block
+        match = re.search(r"```(?:json)?\s*\n?(.*?)\n?```", text, re.DOTALL)
+        if match:
+            return json.loads(match.group(1))
+        raise ValueError(f"Could not extract JSON from AI response: {text[:200]}")
+
+    def _build_prompt(
+        self, existing_meta: dict, text_sample: str, filename: str, schema: str
+    ) -> str:
+        meta_str = json.dumps({k: v for k, v in existing_meta.items() if v}, indent=2)
+        max_chars = 8000
+        if len(text_sample) > max_chars:
+            text_sample = text_sample[:max_chars] + "\n[...truncated]"
+
+        return f"""Analyze this PDF and return ONLY a JSON object matching the schema below.
+No explanation, no markdown, just the raw JSON.
+
+## JSON Schema
+{schema}
+
+## Filename
+{filename}
+
+## Existing PDF metadata
+{meta_str}
+
+## Text from first pages
+{text_sample}
+
+## Field guidelines
+- doc_type: one of book, novel, textbook, paper, class-notes, exercises,
+  guide-theory, guide-practice
+- language: ISO 639-1 code (e.g. "en", "es")
+- tags: relevant topics and keywords
+- summary: 2-3 sentence description
+- table_of_contents: chapter titles if visible, otherwise null
+- subject: broad knowledge area (e.g. "Mathematics", "Computer Science")
+- Use null for fields that cannot be determined
+- Always provide title and author — infer from content if needed
+- IMPORTANT: If year, publisher, or ISBN are missing from the PDF text,
+  use web search to find the correct publication year, publisher, and ISBN.
+  Search for the book title and author to find this information."""
+
+
+def get_ai_backend(name: str, model: str = "sonnet") -> AIBackend:
+    backends = {
+        "claude": ClaudeCLIBackend,
+    }
+    cls = backends.get(name)
+    if cls is None:
+        raise ValueError(f"Unknown AI backend: {name}. Available: {', '.join(backends)}")
+    return cls(model=model)