orbitr 0.1.1__tar.gz

orbitr-0.1.1/.env.example

@@ -0,0 +1,33 @@
+# lumen environment variables
+# Copy to .env and fill in values, or run `lumen init` for guided setup.
+# These override settings in ~/.config/lumen/config.toml.
+
+# Semantic Scholar API key (optional — increases rate limits)
+# Get one at: https://www.semanticscholar.org/product/api
+SEMANTIC_SCHOLAR_API_KEY=
+
+# Zotero credentials (required for `lumen zotero` commands)
+# Get your User ID and API key at: https://www.zotero.org/settings/keys
+ZOTERO_USER_ID=
+ZOTERO_API_KEY=
+
+# Override default search sources (comma-separated)
+# LUMEN_SOURCES=arxiv,semantic_scholar
+
+# Override default max results
+# LUMEN_MAX_RESULTS=10
+
+# Override default output format (table, list, json)
+# LUMEN_FORMAT=table
+
+# Override cache directory
+# LUMEN_CACHE_DIR=~/.cache/lumen
+
+# Disable caching entirely
+# LUMEN_NO_CACHE=1
+
+# Disable pager for long output
+# LUMEN_NO_PAGER=1
+
+# Disable all color output (also respected: NO_COLOR=1)
+# NO_COLOR=1

orbitr-0.1.1/.envrc

@@ -0,0 +1 @@
+use flake .

orbitr-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [published]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --group dev
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run ruff check src/ tests/
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --group dev
+      - run: uv run pyright src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run pytest --tb=short -q
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --group dev
+      - run: uv run pytest --cov=orbitr --cov-report=term-missing --cov-fail-under=80 -q
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv build
+      - name: Check wheel installs and --version works
+        run: |
+          uv tool install dist/*.whl
+          orbitr --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'release'
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v5
+      - run: uv publish --trusted-publishing always

orbitr-0.1.1/.gitignore

@@ -0,0 +1,23 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/
+.env
+.env.local
+*.pem
+credentials.json
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.pyright/
+htmlcov/
+.coverage
+coverage.xml
+.direnv/
+.aider*

orbitr-0.1.1/AGENTS.md

@@ -0,0 +1,114 @@
+# orbitr — Agent Project Context
+
+## Software Purpose
+
+`orbitr` is a Python CLI tool for academic literature search and reference management. It queries arXiv, Semantic Scholar, and Google Scholar concurrently, deduplicates and ranks results, and integrates with the Zotero reference manager. Target users: researchers, academics, and students who prefer terminal-based workflows.
+
+## Architecture Overview
+
+CLI pipeline: command dispatch → concurrent async API clients → core processing (dedup, ranking, cache) → display layer (Rich or JSON).
+
+**Key components:**
+
+- `src/orbitr/cli.py` — Typer root app; global flags; injects config into context
+- `src/orbitr/config.py` — layered config: CLI flags > env vars > `~/.config/orbitr/config.toml` > defaults
+- `src/orbitr/commands/` — one module per command (`search`, `paper`, `cite`, `author`, `recommend`, `export`, `query`, `zotero`, `cache`, `init`, `doctor`)
+- `src/orbitr/clients/` — async httpx clients: `arxiv.py`, `semantic_scholar.py`; all extend `base.py` (retry, rate limiting, circuit break); Google Scholar deferred to v1.1
+- `src/orbitr/core/` — `models.py` (Pydantic), `deduplication.py`, `ranking.py`, `cache.py` (SQLite), `export.py` (BibTeX/RIS/CSL-JSON)
+- `src/orbitr/zotero/client.py` — pyzotero wrapper
+- `src/orbitr/display/` — `table.py`, `list.py`, `detail.py`, `json_fmt.py`
+
+## Dev Environment
+
+The project uses a **Nix flake** to pin the dev environment (Python 3.12, uv, ruff,
+pyright) and **direnv** to activate it automatically on `cd`. A **justfile** provides
+all common workflow recipes.
+
+Entry point:
+
+```bash
+cd orbitr          # direnv runs `use flake .` — activates pinned shell
+just setup        # uv sync inside the flake environment
+```
+
+Without direnv: `nix develop` then `just setup`.
+
+## Build, Test, and Run
+
+```bash
+just setup        # uv sync — install deps and editable package
+just run -- --help           # run orbitr via uv run
+just build        # uv build — produces dist/ wheel + sdist
+
+just fmt          # ruff format src/ tests/
+just lint         # ruff check --fix src/ tests/
+just check        # fmt + lint, no writes (use in CI)
+just types        # pyright src/
+just qa           # check + types
+
+just test         # pytest — full suite
+just test-unit    # pytest -m "not integration"
+just cov          # pytest --cov with term-missing report
+just test-mod core/test_deduplication  # single module
+
+just clean        # remove build artifacts and caches
+just reset        # wipe .venv and reinstall from scratch
+```
+
+Run `just` with no arguments to list all recipes.
+
+## Language and Stack
+
+- **Python** ≥ 3.10; `uv` for deps and packaging; `hatchling` build backend
+- **CLI:** Typer + Click
+- **Terminal output:** Rich
+- **HTTP:** httpx (async)
+- **Models:** Pydantic v2
+- **Cache:** SQLite (stdlib `sqlite3`)
+- **Zotero:** pyzotero
+- **Code style:** `ruff format` (88 chars), `ruff check` (rules: E, F, UP, B, SIM, I), `pyright` basic
+
+## Directory Structure
+
+```
+orbitr/
+├── pyproject.toml
+├── flake.nix
+├── CLAUDE.md
+├── README.md
+├── .env.example
+├── specs/               # planning.md, progress.md, implementation.md
+├── logs/                # session and weekly review logs
+├── src/orbitr/           # source package
+├── tests/               # pytest suite + fixtures/
+└── .gitignore
+```
+
+## Development Workflow
+
+- Conventional commits: `type(scope): message` (feat, fix, chore, docs, test, refactor)
+- All commands must have complete `--help` text with a usage example before merging
+- Errors go to stderr; data goes to stdout — enforce at every command boundary
+- All new commands: add entry to `cli.py`, stub in `commands/`, unit test in `tests/test_<command>.py`
+- Run `just check` before committing; run `just qa` before opening a PR
+- Check `specs/planning.md` for the current phase and open tasks
+- Update `specs/progress.md` after completing a milestone or feature
+
+## Key Conventions
+
+- **Exit codes:** 0 success, 1 general error, 2 usage error, 3 config error, 4 no results
+- **Config path:** `~/.config/orbitr/config.toml` (XDG); cache at `~/.cache/orbitr/`
+- **Credentials file permissions:** `0600` — enforced in `orbitr init`
+- **TTY detection:** when stdout is not a TTY, default `--format` to `json` automatically
+- **`NO_COLOR`** env var disables all Rich color; `--no-color` flag does the same
+- **Async in Typer:** wrap async work in `asyncio.run()` at the command level; no persistent event loop
+- **Google Scholar:** deferred to v1.1 — do not implement in v1
+- **Deduplication threshold:** 85% fuzzy title similarity (configurable internally)
+
+## How to Use Claude Effectively Here
+
+- **Before implementing a command:** read `specs/implementation.md` for the module structure and key interfaces; check `specs/progress.md` for current status
+- **Error messages:** always include what failed, why, and a fix suggestion — see `specs/implementation.md` § Error Handling for the pattern
+- **Adding a new command:** follow the pattern in existing `commands/` modules; register in `cli.py`; add `--help` text with a real example
+- **Tests:** use `tests/fixtures/` for API responses; mock with `respx`; never make live API calls in tests
+- **Display:** add new renderers in `display/`; always accept `format: Literal["table","list","detail","json"]` and honor `NO_COLOR`

orbitr-0.1.1/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] — 2026-04-06
+
+Initial release.
+
+### Added
+
+**Core pipeline**
+
+- Multi-source concurrent search across arXiv (Atom feed) and Semantic Scholar
+  (Graph API v1) via `orbitr search`
+- Intelligent deduplication: exact DOI match → exact arXiv ID match → fuzzy
+  title similarity (rapidfuzz, 85% threshold) with author-overlap gating
+- Five ranking criteria: `relevance` (TF-IDF), `citations` (log-scaled),
+  `date` (recency), `impact` (citations × date), `combined` (weighted blend)
+- SQLite TTL cache with three independent tiers:
+  `search` (1 h), `paper` (24 h), `citations` (6 h)
+
+**Commands**
+
+- `orbitr search` — keyword + `field:value` syntax, field flags (`--title`,
+  `--author`, `--venue`), year range (`--from`, `--to`), sort, format
+- `orbitr paper` — fetch by arXiv ID, DOI, or Semantic Scholar ID; auto-detects
+  ID type; accepts `arxiv:`, `abs/`, URL, and bare ID forms
+- `orbitr cite` — citing papers via Semantic Scholar
+- `orbitr author` — author search via Semantic Scholar two-step (search → papers)
+- `orbitr recommend` — content/citation/hybrid recommendations via SS
+- `orbitr export` — BibTeX, RIS, CSL-JSON; reads ndjson from stdin or `--query`
+- `orbitr query` — heuristic NL-to-query translator with `--run` flag
+- `orbitr zotero add/collections/new` — Zotero Web API integration via pyzotero
+- `orbitr cache stats/clean/clear` — cache inspection and management
+- `orbitr init` — interactive credential and defaults setup (writes `config.toml`
+  with mode `0600`)
+- `orbitr doctor` — async connectivity checks for arXiv, SS, and Zotero
+
+**Display layer**
+
+- Four output formats: `table` (Rich Table), `list` (Rich Panels), `detail`
+  (full single-paper layout with abstract, metadata, links), `json` (ndjson)
+- TTY auto-detection: `--format` defaults to `json` when stdout is not a TTY
+- Pager integration: long output routed through `$PAGER` (`less -R`) on TTY;
+  disabled with `LUMEN_NO_PAGER=1`
+
+**Error handling**
+
+- `LumenError` hierarchy with exit codes: 1 (source), 2 (usage), 3 (config),
+  4 (no results)
+- HTTP errors converted to clean `SourceError` in `BaseClient._get`; no raw
+  httpx messages surface to users
+- 5xx errors retried up to 3× with exponential backoff; 403 directs to
+  `orbitr init` for API key setup
+- Dim suggestion lines on all error messages
+
+**Infrastructure**
+
+- Layered config: CLI flags > env vars > `~/.config/orbitr/config.toml` > defaults
+- Nix flake dev environment (Python 3.12, uv, ruff, pyright)
+- `justfile` with test, lint, format, coverage, build, and install recipes
+- GitHub Actions CI: lint, typecheck, test (Python 3.10–3.12), coverage, build,
+  publish-on-release
+
+### Test coverage
+
+- 343 tests; `core/` at 100%, `display/` at 97% overall
+- Offline API tests via `respx` fixtures (no live network calls in CI)
+- Smoke test script (`tests/smoke_test.sh`) for pre-release live-API validation
+
+### Known limitations
+
+- Google Scholar support deferred to v1.1 (scraping fragility)
+- `orbitr recommend --method` flag is accepted but all methods use the same
+  SS endpoint; method distinctions planned for v1.1
+- `display/detail.py` falls back to list view for multi-paper input in some
+  edge cases
+
+---
+
+## [0.1.1] — 2026-04-06
+
+### Fixed
+
+- **`orbitr init` — env-var credential protection** (`commands/init.py`, `config.py`):
+  - Credentials supplied via `SEMANTIC_SCHOLAR_API_KEY`, `ZOTERO_USER_ID`, or
+    `ZOTERO_API_KEY` environment variables are now detected at init time.
+  - A clear dim note is shown for each active env var: *"Already set via
+    ENV_VAR — leave blank to keep using the env var."*
+  - Prompts for env-var-sourced credentials default to blank instead of
+    pre-filling with the resolved (env) value, preventing accidental plain-text
+    exposure in `config.toml`.
+  - If the user leaves a credential blank and an env var is active, the
+    existing `config.toml` value for that field is preserved rather than
+    overwritten with an empty string.
+  - Entering a new value at the prompt always writes it to `config.toml`,
+    regardless of whether an env var is also set.
+  - Config loading (`load_config`) was already correct (env vars take
+    precedence over `config.toml` at runtime); this fix closes the init-time
+    loophole.
+
+## Unreleased
+
+_Nothing yet._

orbitr-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerid Francom
+
+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.