opencite 0.1.0__tar.gz

opencite-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "opencite",
+  "version": "0.1.0",
+  "description": "Academic literature search, citation management, and PDF retrieval using the opencite CLI",
+  "author": {
+    "name": "Seyed Yahya Shirazi",
+    "email": "shirazi@ieee.org"
+  },
+  "repository": "https://github.com/neuromechanist/opencite",
+  "license": "MIT",
+  "keywords": ["academic", "literature", "citations", "bibtex", "pdf", "pubmed", "openalex", "semantic-scholar"]
+}

opencite-0.1.0/.context/research.md

@@ -0,0 +1,197 @@
+# OpenCite API Research
+
+Comprehensive analysis of the three academic APIs for building the OpenCite CLI.
+
+## Capability Matrix
+
+| Capability | OpenAlex | Semantic Scholar | PubMed/PMC |
+|---|---|---|---|
+| **Keyword search** | Yes (title, abstract, fulltext) | Yes (relevance + bulk/boolean) | Yes (field tags, MeSH) |
+| **DOI lookup** | `/works/doi:X` | `/paper/DOI:X` | `X[lid]` or `X[aid]` search |
+| **PMID lookup** | `/works/pmid:X` | `/paper/PMID:X` | Native (efetch by ID) |
+| **PMCID lookup** | `/works/pmcid:X` | `/paper/PMCID:X` | Native (efetch by ID) |
+| **ArXiv lookup** | No direct | `/paper/ARXIV:X` | No |
+| **Batch lookup** | 50 IDs via filter pipe | POST 500 IDs `/paper/batch` | POST thousands via epost |
+| **Citing papers** | `filter=cites:W123` | `/paper/{id}/citations` | elink `pubmed_pubmed_citedin` |
+| **References** | `referenced_works` field or `filter=cited_by:W123` | `/paper/{id}/references` | elink `pubmed_pubmed_refs` |
+| **Related papers** | `related_works` field | Recommendations API | elink `pubmed_pubmed` (similarity) |
+| **PDF URLs** | `best_oa_location.pdf_url`, `locations[].pdf_url` | `openAccessPdf.url` | PMC OA Service |
+| **Full-text download** | `content_url` (100 credits) | No hosted content | PMC efetch XML, BioC API, FTP |
+| **BibTeX** | No native | `citationStyles` field | No native (parse XML) |
+| **TLDR summaries** | No | `tldr` field (~60M papers) | No |
+| **Paper embeddings** | No | SPECTER v1/v2 | No |
+| **Author search** | `/authors?search=X` | `/author/search?query=X` | `smith j[au]` |
+| **Author profiles** | h-index, i10-index, works_count | h-index, paperCount, citationCount | No profiles |
+| **ORCID support** | `author.orcid` | `externalIds.ORCID` | No |
+| **MeSH terms** | `mesh` field (PubMed-indexed) | No | Native, hierarchical |
+| **Topics/concepts** | Topics (domain>field>subfield) | `s2FieldsOfStudy` | MeSH hierarchy |
+| **Publication types** | `type` field | `publicationTypes` | 70+ pub types via `[pt]` |
+| **Retraction status** | `is_retracted` (Retraction Watch) | No | `"retracted publication"[pt]` |
+| **Funder/grants** | `grants.funder`, `grants.award_id` | No | `[gr]` field tag |
+| **ID conversion** | Implicit (accepts pmid, pmcid, doi) | Implicit (accepts all) | Dedicated ID Converter API |
+| **Autocomplete** | `/autocomplete/{entity}` | `/paper/autocomplete` | No |
+| **Aggregations** | `group_by` parameter | No | No |
+| **Rate limit (no key)** | Not allowed (key required as of Feb 2026) | Shared pool, unreliable | 3 req/sec |
+| **Rate limit (with key)** | 100 req/sec, 100K credits/day | 1 req/sec | 10 req/sec |
+| **Pagination max** | Unlimited (cursor) | 1K (relevance), 10M (bulk) | 10K per search |
+
+## PDF Retrieval Strategy
+
+### Tier 1: Direct PDF URLs (fastest)
+
+**OpenAlex** is the richest source for PDF URLs:
+- `best_oa_location.pdf_url` -- algorithmically chosen best OA copy
+- `locations[].pdf_url` -- all known PDF locations
+- Priority: published version > accepted > submitted
+- `content_url` field for OpenAlex-hosted PDFs (costs 100 credits)
+- Filter: `has_content.pdf:true` or `is_oa:true`
+
+**Semantic Scholar**:
+- `openAccessPdf.url` -- direct PDF link when available
+- `isOpenAccess` -- boolean flag
+- Can filter search results: `openAccessPdf` parameter
+
+### Tier 2: PMC Full Text
+
+**PMC OA Web Service** (`https://www.ncbi.nlm.nih.gov/pmc/utils/oa/oa.fcgi`):
+- Query by PMCID: `?id=PMC5334499`
+- Returns PDF and tgz (XML + images) download links
+- Only works for PMC Open Access Subset (~3M articles)
+- Filter by format: `&format=pdf`
+
+**PMC BioC API** (structured full text):
+- `https://www.ncbi.nlm.nih.gov/research/bionlp/RESTful/pmcoa.cgi/BioC_json/{PMID}/unicode`
+- Returns structured JSON with sections, paragraphs, annotations
+- Good for text extraction without PDF parsing
+
+**PMC efetch** (full text XML):
+- `efetch.fcgi?db=pmc&id=PMC1234567&retmode=xml`
+- Returns JATS XML for OA articles
+
+### Tier 3: DOI Content Negotiation (fallback)
+
+Already implemented in current code:
+- `GET https://doi.org/{doi}` with `Accept: application/x-bibtex` for BibTeX
+- Can also request `Accept: application/pdf` for PDFs (publisher-dependent)
+
+### Recommended PDF Retrieval Pipeline
+
+```
+1. Check OpenAlex best_oa_location.pdf_url
+2. Check Semantic Scholar openAccessPdf.url
+3. If PMCID available, try PMC OA Service for PDF
+4. If PMCID available, try BioC API for structured text
+5. Fall back to DOI content negotiation
+6. If all fail, return landing page URL for manual download
+```
+
+### ID Conversion for Cross-API Lookup
+
+To maximize PDF retrieval, convert between ID types:
+- **PMC ID Converter**: `https://pmc.ncbi.nlm.nih.gov/tools/id-converter-api/?tool=opencite&email=X&ids=PMID1,PMID2&format=json`
+- Up to 200 IDs per request
+- Converts PMID <-> PMCID <-> DOI <-> Manuscript ID
+- OpenAlex also accepts `/works/pmid:X` and `/works/pmcid:X` directly
+
+## Search Strategy by Use Case
+
+### Keyword Search
+Best approach: query all three in parallel (current design is good)
+- **OpenAlex**: Broadest coverage (~250M works), fulltext search available
+- **Semantic Scholar**: Good relevance ranking, TLDR summaries, boolean bulk search
+- **PubMed**: Best for biomedical, MeSH term precision, structured field tags
+
+### DOI Lookup
+- **Semantic Scholar** `/paper/DOI:X` is fastest for single lookups
+- **OpenAlex** `/works/doi:X` provides richest metadata (locations, topics, grants)
+- Use both; merge results
+
+### Citation Graph Traversal
+- **OpenAlex**: `filter=cites:W123` returns citing works with full filtering/sorting
+- **Semantic Scholar**: `/paper/{id}/citations` with up to 1K results, includes `influentialCitationCount`
+- **PubMed**: elink `pubmed_pubmed_citedin` for biomedical citation chains
+
+### Batch DOI Lookup
+- **Semantic Scholar** POST `/paper/batch` with up to 500 IDs is most efficient
+- **OpenAlex** filter pipe: up to 50 DOIs per request
+- **PubMed** epost + efetch: thousands of PMIDs
+
+## BibTeX Generation Strategy
+
+```
+1. Semantic Scholar citationStyles field (if available)
+2. DOI content negotiation: GET doi.org/{doi} Accept: application/x-bibtex
+3. Generate from metadata (current fallback, already implemented)
+```
+
+## PDF-to-Markdown Conversion
+
+Two backends available:
+
+### markit-mistral (Mistral AI OCR)
+- Location: `../markit-mistral`
+- CLI: `markit-mistral document.pdf -o output.md`
+- Python: `MarkItMistral(api_key=KEY).convert_file("doc.pdf")`
+- Strengths: math/LaTeX preservation, complex layouts, tables
+- Requires: `MISTRAL_API_KEY`
+- Cost: API usage fees
+
+### markitdown (Microsoft, open source)
+- Repo: https://github.com/microsoft/markitdown
+- CLI: `markitdown document.pdf -o output.md`
+- Strengths: free, no API key, good for simple documents
+- Weaknesses: less accurate on math, complex layouts
+
+### Recommended Strategy
+```
+1. Try markitdown first (free, no API costs)
+2. If document has math/complex layout, use markit-mistral
+3. Let user choose via CLI flag: --converter markitdown|mistral
+```
+
+## Rate Limit Management
+
+| API | Strategy |
+|---|---|
+| OpenAlex | 100 req/sec is generous; batch via filter pipes; use `select` to reduce payload |
+| Semantic Scholar | 1 req/sec is the bottleneck; use batch endpoint for multi-ID lookups; queue requests |
+| PubMed | 10 req/sec is reasonable; use History Server for large jobs; batch efetch up to 500 records |
+
+### Recommended: Async with per-API rate limiters
+```python
+# Per-API semaphores
+openalex_limiter = AsyncLimiter(100, 1)    # 100/sec
+s2_limiter = AsyncLimiter(1, 1)            # 1/sec
+pubmed_limiter = AsyncLimiter(10, 1)       # 10/sec
+```
+
+## Unique Strengths Per API
+
+### OpenAlex -- Use for:
+- Broadest coverage (250M+ works)
+- PDF URL discovery (best_oa_location)
+- Rich filtering (90+ filters)
+- Funder/grant information
+- Aggregations/analytics (group_by)
+- Institution and country-level analysis
+- Retraction status (Retraction Watch)
+
+### Semantic Scholar -- Use for:
+- TLDR auto-summaries
+- Paper embeddings (SPECTER v2) for similarity
+- Recommendations API
+- Influential citation count
+- Boolean bulk search (10M results)
+- Batch lookup (500 IDs at once)
+- ArXiv paper lookup
+- BibTeX via citationStyles field
+
+### PubMed/PMC -- Use for:
+- Biomedical literature (gold standard)
+- MeSH term searching (hierarchical, exploded)
+- PMC full-text access (XML, PDF, BioC)
+- Publication type precision (70+ types)
+- Proximity searching ("term1 term2"[tiab:~3])
+- ID conversion service (PMID/PMCID/DOI)
+- Free full text filter
+- Clinical trial and systematic review filters

opencite-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,109 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Create venv and install build dependencies
+      run: |
+        uv venv --python 3.12
+        uv pip install build twine
+
+    - name: Build package
+      run: uv run python -m build
+
+    - name: Check package
+      run: uv run twine check dist/*
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  test-install:
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Create venv and install from wheel
+      run: |
+        uv venv --python ${{ matrix.python-version }}
+        uv pip install dist/*.whl
+
+    - name: Test import
+      run: |
+        uv run python -c "import opencite; print(f'opencite version: {opencite.__version__}')"
+        uv run python -c "from opencite import Paper, Config; print('Core imports successful')"
+
+  publish-testpypi:
+    needs: [build, test-install]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/opencite
+    permissions:
+      id-token: write
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        skip-existing: true
+
+  publish-pypi:
+    needs: [build, test-install]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/opencite
+    permissions:
+      id-token: write
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

opencite-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,43 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Create venv and install dependencies
+      run: |
+        uv venv --python ${{ matrix.python-version }}
+        uv pip install -e ".[dev]"
+
+    - name: Lint with ruff
+      run: |
+        uv run ruff check src/ tests/
+
+    - name: Run tests with coverage
+      run: |
+        uv run pytest --ignore=tests/test_clients --cov=opencite --cov-report=xml
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v5
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+        token: ${{ secrets.CODECOV_TOKEN }}

opencite-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+.cursor/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Linting/type checking
+.ruff_cache/
+.mypy_cache/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Plan files
+.plan
+
+# UV
+uv.lock

opencite-0.1.0/.serena/.gitignore

@@ -0,0 +1 @@
+/cache

opencite-0.1.0/.serena/project.yml

@@ -0,0 +1,84 @@
+# list of languages for which language servers are started; choose from:
+#   al               bash             clojure          cpp              csharp           csharp_omnisharp
+#   dart             elixir           elm              erlang           fortran          go
+#   haskell          java             julia            kotlin           lua              markdown
+#   nix              perl             php              python           python_jedi      r
+#   rego             ruby             ruby_solargraph  rust             scala            swift
+#   terraform        typescript       typescript_vts   yaml             zig
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+# Special requirements:
+#   - csharp: Requires the presence of a .sln file in the project folder.
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- python
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "opencite"
+included_optional_tools: []

opencite-0.1.0/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OpenCite is a Python CLI tool and library for academic literature search and citation management. It aggregates results from three academic APIs (Semantic Scholar, OpenAlex, PubMed), deduplicates them, and outputs results as formatted text, JSON, BibTeX, or CSV. It also supports PDF retrieval and PDF-to-markdown conversion.
+
+## Build and Run
+
+```bash
+uv sync --extra dev              # install package + dev deps
+uv run opencite --version        # verify CLI works
+uv run opencite search "query"   # search for papers
+uv run opencite lookup DOI       # look up a specific paper
+uv run opencite cite DOI         # citation graph
+uv run opencite canonical "topic"  # most-cited papers in a field
+```
+
+## Testing and Linting
+
+```bash
+uv run pytest                    # run all tests
+uv run pytest tests/test_models.py -v    # single test file
+uv run pytest -k "test_doi"      # single test by name
+uv run pytest -m integration     # API integration tests only
+uv run ruff check src/ tests/    # lint
+uv run ruff check --fix src/ tests/  # auto-fix lint
+uv run ruff format src/ tests/   # format
+```
+
+## Architecture
+
+### Package Layout (`src/opencite/`)
+- `models.py` -- central data models: `Paper`, `Author`, `IDSet` (frozen), `Source`, `PDFLocation`, `SearchResult`, `CitationResult`, `parse_identifier()`
+- `config.py` -- `Config` dataclass with `from_env()`, manual `.env` loading
+- `exceptions.py` -- `OpenCiteError` hierarchy: `APIError`, `RateLimitError`, `APIKeyError`, etc.
+- `cli.py` -- argparse with subcommands: search, lookup, cite, canonical, pdf, convert, ids
+- `utils.py` -- title normalization, fuzzy matching, author name parsing, abstract reconstruction
+- `clients/` -- per-API async clients with rate limiting (base.py, openalex.py, semantic_scholar.py, pubmed.py, id_converter.py)
+- `search.py` -- `SearchOrchestrator` for parallel multi-source search with dedup/merge
+- `citations.py` -- `CitationExplorer` for citation graph traversal and canonical paper discovery
+- `dedup.py` -- DOI + fuzzy title deduplication with paper merging
+- `bibtex.py` -- BibTeX fetch (S2 citationStyles, DOI negotiation) and generation
+- `pdf.py` -- multi-source PDF retrieval pipeline
+- `convert.py` -- PDF-to-markdown (markitdown, markit-mistral)
+- `formatters/` -- output formatters (text, json, bibtex, csv)
+
+### Key Design Patterns
+- **IDSet** is frozen (immutable) and centralizes all identifier types (DOI, PMID, PMCID, OpenAlex, S2, ArXiv) for cross-API lookup
+- **Paper.data_sources** tracks which APIs contributed data (provenance)
+- **BaseClient** ABC provides rate limiting (token bucket), retry with backoff, httpx session management
+- Rate limits: OpenAlex 100 req/sec, PubMed 10 req/sec, Semantic Scholar 1 req/sec
+- PDF retrieval tries sources in priority: OpenAlex -> S2 -> PMC OA -> DOI negotiation
+- PDF-to-markdown `auto` mode: if `MISTRAL_API_KEY` is set, use markit-mistral (better for math/complex layouts); otherwise fall back to markitdown (free)
+- `scripts/lit_search.py` is the original prototype, kept as reference
+
+### API Integrations
+- **OpenAlex** -- `pyalex` library; broadest coverage (250M+ works); best for PDF URLs, filtering, citation counts
+- **Semantic Scholar** -- `httpx` REST; TLDR summaries, SPECTER embeddings, batch 500 IDs, `citationStyles` for BibTeX
+- **PubMed/PMC** -- NCBI eutils XML; MeSH terms, PMC full text, ID Converter API
+
+## Environment Variables
+
+Required in `.env` (gitignored):
+- `SEMANTIC_SCHOLAR_API_KEY` -- Semantic Scholar API
+- `PUBMED_API_KEY` -- NCBI/PubMed API
+- `OPENALEX_API_KEY` -- OpenAlex API (required since Feb 2026)
+- `MISTRAL_API_KEY` -- Mistral AI for PDF-to-markdown conversion
+
+## Dependencies
+
+Core: `httpx`, `pyalex`
+Optional [convert]: `markitdown`, `markit-mistral` (local, not on PyPI)
+Dev: `pytest`, `pytest-asyncio`, `pytest-cov`, `ruff`, `pre-commit`

opencite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seyed Yahya Shirazi
+
+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.

opencite-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: opencite
+Version: 0.1.0
+Summary: Academic literature search, citation management, and PDF retrieval CLI
+Project-URL: Repository, https://github.com/neuromechanist/opencite
+Project-URL: Issues, https://github.com/neuromechanist/opencite/issues
+Author-email: Seyed Yahya Shirazi <shirazi@ieee.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: academic,bibtex,citations,literature,openalex,pdf,pubmed,search,semantic-scholar
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyalex>=0.15
+Provides-Extra: convert
+Requires-Dist: markit-mistral; extra == 'convert'
+Requires-Dist: markitdown>=0.1.0; extra == 'convert'
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenCite
+
+Academic literature search, citation management, and PDF retrieval CLI.
+
+Searches Semantic Scholar, OpenAlex, and PubMed in parallel, deduplicates results, and supports BibTeX output, citation graph traversal, PDF retrieval, and PDF-to-markdown conversion.
+
+## Installation
+
+```bash
+uv pip install -e .
+```
+
+With PDF conversion support:
+
+```bash
+uv pip install -e ".[convert]"
+```
+
+## Quick Start
+
+```bash
+# Search for papers
+opencite search "transformer attention mechanism"
+
+# Look up a paper by DOI
+opencite lookup 10.1038/nature12345
+
+# Find most-cited papers in a field
+opencite canonical "deep learning for neuroscience" --min-citations 500
+
+# Get papers citing a specific work
+opencite cite 10.1038/nature12345
+
+# Download a PDF
+opencite pdf 10.1038/nature12345 -o papers/
+```
+
+## Configuration
+
+Set API keys in a `.env` file or as environment variables:
+
+```
+SEMANTIC_SCHOLAR_API_KEY=your_key
+PUBMED_API_KEY=your_key
+OPENALEX_API_KEY=your_key
+MISTRAL_API_KEY=your_key          # for PDF-to-markdown via Mistral OCR
+```