aristotle-py 0.1.0__py3-none-any.whl

aristotle/__init__.py

@@ -0,0 +1,26 @@
+"""Aristotle academic-paper client."""
+
+from aristotle.models import (
+    Author,
+    AuthorWork,
+    Download,
+    ExportFormat,
+    Paper,
+    SearchFilters,
+    SearchMatch,
+    SearchSort,
+)
+from aristotle.service import Aristotle
+
+__all__ = [
+    "Aristotle",
+    "Author",
+    "AuthorWork",
+    "Download",
+    "ExportFormat",
+    "Paper",
+    "SearchFilters",
+    "SearchMatch",
+    "SearchSort",
+]
+__version__ = "0.1.0"

aristotle/agent_skills/aristotle-cli/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: aristotle-cli
+description: Use the Aristotle command-line tool to search, inspect, and download scholarly papers, or search public ORCID profiles. Use when a user asks you to find or inspect academic literature with the installed `aristotle` command.
+---
+
+# Aristotle CLI
+
+Use this skill when the `aristotle` command is installed and the user wants paper
+discovery, metadata, citations, PDFs, or public ORCID profile information.
+
+## Start with the installed CLI
+
+Check availability with `aristotle --help`. Read command-specific help before
+using an unfamiliar command, for example `aristotle search --help` or
+`aristotle config --help`. Installed versions can differ from this document.
+Treat the CLI's help output as authoritative if it conflicts with these examples.
+
+The main command groups are:
+
+- `search [QUERY]`: search the configured default source, or all paper providers
+  concurrently when no default is set. Choose a source with `--provider` (`doi`,
+  `ssrn`, `arxiv`, `openalex`, `semantic-scholar`, or `zenodo`); `all` bypasses the
+  default. Query may be omitted for author-only paper searches.
+- `view IDENTIFIER`: inspect a paper identified by DOI, arXiv ID, provider ID, or
+  supported provider URL.
+- `download IDENTIFIER`: save an available PDF. The default destination is the
+  configured `download_dir` (current directory by default); `--output` overrides it.
+- `providers`: list installed paper and author providers. `--check` makes live
+  test searches; use it only when live network checks are useful.
+- `author search QUERY` and `author view ORCID`: search or inspect public author
+  profiles. ORCID public data does not require credentials.
+- `doctor`: inspect local setup without network access, file writes, or browser launch.
+  `--check` adds live metadata searches; JSON output is available.
+- `history`: list recent search requests; `--run N` repeats a request, and
+  `--clear` deletes history when requested.
+- `config`: inspect or edit settings. See Configuration below.
+
+## Search and inspect
+
+Start with a focused query and a reasonable limit. Searches run across providers
+unless `default_provider` or `--provider` is set; `-p all` explicitly searches all
+sources. Examples:
+
+```bash
+aristotle search "graph neural networks" --limit 10
+aristotle search "market liquidity" --provider ssrn
+aristotle search "climate adaptation" --from 2020 --to 2024
+aristotle search "machine learning" --author "Jane Smith" --has-pdf
+aristotle search "market microstructure" --sort citations
+aristotle view 10.1038/s41586-023-06004-9
+```
+
+Useful filters include `--author`, `--from`/`--from-date`, `--to`/`--to-date`,
+`--has-pdf` (also `--open-access`), and `--match` (`all`, `phrase`, `title`, or
+`provider`). The default `provider` match policy trusts each provider's ranking.
+Future-dated records are hidden unless `--include-future` is passed. Results are
+deduplicated across providers by default; `--no-deduplicate` exposes provider
+duplicates. Sorting supports `relevance`, `newest`, `oldest`, and `citations`.
+
+Every command accepts `--format json`, or use the root `--json` flag before the
+command. This includes downloads, config reads/writes, history replay/clear, errors,
+and help. JSON mode emits one document on stdout without colors/progress; runtime
+and usage errors preserve nonzero exit codes. Batch JSON includes per-item failures.
+Secrets remain masked; config writes never echo values and require a value without
+interactive prompting.
+
+Search and view also support `bibtex`, `ris`, or `csv` with `--format`.
+JSON and citation exports are useful for downstream processing; keep normal
+human-readable output when the user wants a concise inspection. Exported data is
+written to stdout, so it can be redirected to a file when requested.
+
+Search results are saved locally for selection by number. After a search, the
+CLI prints examples using `--result N`; use `aristotle view --result N` or
+`aristotle download --result N` only while that saved result set is the one the
+user intends. Numbers refer to the last displayed page. `search --next` advances
+saved pages, then fetches another native provider batch. Rankings and coverage are
+limited to the current batch; do not describe them as exhaustive. Prefer a stable
+identifier when resuming later. Human-readable searches also store bounded query
+history; exports do not replace the active snapshot or add history entries unless
+`--paginate` is supplied. For JSON pagination, use `search QUERY --paginate --format
+json`, then `search --next --format json`. The response includes `results`,
+`pagination`, and `summary`. Follow `pagination.can_continue`; `has_more: null`
+means another provider batch must be fetched to find out. Pagination shares the
+local saved snapshot with interactive searches; another saved search replaces it.
+Exhaustion returns empty results and preserves the last selected page.
+
+## Downloads and access boundaries
+
+Only download when the user asks for a PDF or otherwise clearly authorizes saving
+one. Check that the result has a known PDF when possible. Use a destination
+directory such as `~/Papers` or an explicit `.pdf` filename:
+
+```bash
+aristotle download 1706.03762 --output ~/Papers
+aristotle download 10.1038/s41586-023-06004-9 --output paper.pdf
+```
+
+For user-authorized batches, `download --results 1,3-5` selects the current page and
+`download --input identifiers.txt` reads one identifier per line (up to 100). Use an
+output directory. Individual failures do not stop remaining downloads; exit code 1
+and the summary indicate partial failure. Report failed identifiers to the user.
+
+Existing files are protected by default. Do not use `--force` unless the user
+explicitly wants an existing file replaced. Aristotle can try an exact DOI or
+arXiv identifier through compatible providers when its primary provider has no
+PDF. A DOI does not guarantee a free PDF. The tool does not circumvent publisher
+paywalls; report when an openly accessible copy is unavailable. SSRN challenge
+handling uses local Chromium or an optional configured CapSolver service; comply
+with SSRN's terms and respect access controls.
+
+## Configuration
+
+Configuration precedence, per setting, is:
+
+1. `ARISTOTLE_*` process environment variable
+2. nearest `.env` file from the current directory upward
+3. global YAML at `$XDG_CONFIG_HOME/aristotle/config.yaml`, or
+   `~/.config/aristotle/config.yaml`
+4. built-in default
+
+Use `aristotle config path` to locate the global file and `aristotle config show`
+to inspect effective values and their sources. Secrets are masked by default.
+Never pass `--show-secrets`, read secret values, copy them into a response, or
+print `.env` contents. `config set` and `config unset` write the global config;
+perform them only when requested. Omitting a value for a secret prompts securely:
+
+```bash
+aristotle config set openalex_api_key
+aristotle config set timeout 45
+aristotle config unset timeout
+```
+
+Available setting names and accepted values can change; consult `config set
+--help` and `config show` before making a change. API keys may increase provider
+limits but are not needed for every source. Workflow settings include
+`default_provider`, `download_dir`, and `history_limit` (0–100; zero disables new
+history writes). Explicit options override defaults; saved history replays its
+original provider and filters.
+
+## Agent operating notes
+
+- Use exact identifiers supplied by the user when they ask about a specific work.
+- Do not claim a result is peer reviewed, authoritative, or open access based only
+  on a search result title. Inspect metadata and describe uncertainty plainly.
+- Provider searches use public metadata services. A provider can fail or time out
+  while others still return results; report that limitation when relevant.
+- Put `--verbose` before the subcommand to show structured diagnostics on stderr.
+  Diagnostics can contain request metadata; do not include unnecessary output in
+  the response.
+- Cite retrieved papers with their identifiers and URLs from Aristotle's output.
+  Do not treat search ranking or citation counts as evidence of quality.

aristotle/authors/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in author-profile providers."""
+
+from aristotle.authors.base import AuthorProvider
+from aristotle.authors.orcid import ORCIDProvider
+
+__all__ = ["AuthorProvider", "ORCIDProvider"]

aristotle/authors/base.py

@@ -0,0 +1,32 @@
+"""Interface implemented by author-profile providers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+import httpx
+
+from aristotle.models import Author
+
+
+class AuthorProvider(ABC):
+    """Implement this interface to add an author-profile source."""
+
+    name: ClassVar[str]
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self.client = client
+
+    @classmethod
+    @abstractmethod
+    def accepts(cls, identifier: str) -> bool:
+        """Return whether this provider recognizes an author identifier."""
+
+    @abstractmethod
+    async def search(self, query: str, limit: int = 10) -> list[Author]:
+        """Search public author profiles."""
+
+    @abstractmethod
+    async def get(self, identifier: str) -> Author:
+        """Fetch one public author profile."""

aristotle/authors/orcid.py

@@ -0,0 +1,179 @@
+"""ORCID public author search and profile provider."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, ClassVar
+
+from aristotle.authors.base import AuthorProvider
+from aristotle.exceptions import PaperNotFound
+from aristotle.models import Author, AuthorWork
+
+_ORCID = re.compile(
+    r"^(?:(?:https?://)?orcid\.org/|orcid:)?"
+    r"(?P<id>\d{4}-\d{4}-\d{4}-[\dX]{4})$",
+    re.IGNORECASE,
+)
+
+
+class ORCIDProvider(AuthorProvider):
+    """Use ORCID's anonymous public API; private profile data is never requested."""
+
+    name: ClassVar[str] = "orcid"
+    api_url: ClassVar[str] = "https://pub.orcid.org/v3.0"
+    headers: ClassVar[dict[str, str]] = {"Accept": "application/json"}
+
+    @classmethod
+    def accepts(cls, identifier: str) -> bool:
+        return bool(_ORCID.match(identifier.strip()))
+
+    @classmethod
+    def clean_id(cls, identifier: str) -> str:
+        match = _ORCID.match(identifier.strip())
+        if not match:
+            raise PaperNotFound(f"Not a valid ORCID iD: {identifier}")
+        return match.group("id").upper()
+
+    async def search(self, query: str, limit: int = 10) -> list[Author]:
+        response = await self.client.get(
+            f"{self.api_url}/expanded-search/",
+            params={"q": query, "rows": limit},
+            headers=self.headers,
+        )
+        response.raise_for_status()
+        return [self._expanded(result) for result in response.json().get("expanded-result", [])]
+
+    async def get(self, identifier: str) -> Author:
+        orcid_id = self.clean_id(identifier)
+        response = await self.client.get(f"{self.api_url}/{orcid_id}/record", headers=self.headers)
+        if response.status_code == 404:
+            raise PaperNotFound(f"ORCID profile not found: {orcid_id}")
+        response.raise_for_status()
+        return self._record(response.json(), orcid_id)
+
+    @classmethod
+    def _expanded(cls, result: dict[str, Any]) -> Author:
+        orcid_id = str(result["orcid-id"])
+        name = cls._name(
+            result.get("given-names"), result.get("family-names"), result.get("credit-name")
+        )
+        aliases = tuple(str(value) for value in result.get("other-name") or [])
+        affiliations = tuple(dict.fromkeys(result.get("institution-name") or []))
+        return Author(
+            identifier=f"ORCID:{orcid_id}",
+            provider=cls.name,
+            name=name or orcid_id,
+            aliases=aliases,
+            affiliations=affiliations,
+            urls=(f"https://orcid.org/{orcid_id}",),
+        )
+
+    @classmethod
+    def _record(cls, record: dict[str, Any], orcid_id: str) -> Author:
+        person = record.get("person") or {}
+        name_data = person.get("name") or {}
+        name = cls._name(
+            cls._content(name_data.get("given-names")),
+            cls._content(name_data.get("family-name")),
+            cls._content(name_data.get("credit-name")),
+        )
+        aliases = cls._contents(person.get("other-names"), "other-name")
+        keywords = cls._contents(person.get("keywords"), "keyword")
+        researcher_urls = tuple(
+            value
+            for item in (person.get("researcher-urls") or {}).get("researcher-url", [])
+            if (value := cls._content(item.get("url")))
+        )
+        activities = record.get("activities-summary") or {}
+        affiliations = cls._affiliations(activities)
+        work_groups = (activities.get("works") or {}).get("group", [])
+        works = cls._works(work_groups)
+        return Author(
+            identifier=f"ORCID:{orcid_id}",
+            provider=cls.name,
+            name=name or orcid_id,
+            aliases=aliases,
+            biography=cls._content(person.get("biography")),
+            affiliations=affiliations,
+            keywords=keywords,
+            urls=(f"https://orcid.org/{orcid_id}", *researcher_urls),
+            works_count=len(work_groups),
+            works=works,
+        )
+
+    @staticmethod
+    def _name(given: Any, family: Any, credit: Any) -> str:
+        if credit:
+            return str(credit)
+        return " ".join(str(part) for part in (given, family) if part).strip()
+
+    @staticmethod
+    def _content(value: Any) -> str | None:
+        if isinstance(value, dict):
+            content = value.get("value", value.get("content"))
+            return str(content) if content else None
+        return str(value) if value else None
+
+    @classmethod
+    def _contents(cls, container: Any, key: str) -> tuple[str, ...]:
+        if not isinstance(container, dict):
+            return ()
+        return tuple(value for item in container.get(key, []) if (value := cls._content(item)))
+
+    @classmethod
+    def _works(cls, groups: list[dict[str, Any]]) -> tuple[AuthorWork, ...]:
+        works: list[AuthorWork] = []
+        for group in groups:
+            summaries = group.get("work-summary") or []
+            if not summaries:
+                continue
+            summary = summaries[0]
+            title = cls._content((summary.get("title") or {}).get("title"))
+            if not title:
+                continue
+            external_ids = (summary.get("external-ids") or {}).get("external-id", [])
+            identifiers = {
+                str(item.get("external-id-type")): str(item.get("external-id-value"))
+                for item in external_ids
+                if item.get("external-id-type") and item.get("external-id-value")
+            }
+            url = cls._content(summary.get("url")) or next(
+                (
+                    cls._content(item.get("external-id-url"))
+                    for item in external_ids
+                    if cls._content(item.get("external-id-url"))
+                ),
+                None,
+            )
+            publication_date = summary.get("publication-date") or {}
+            date_parts = [
+                cls._content(publication_date.get(part)) for part in ("year", "month", "day")
+            ]
+            rendered_date = "-".join(part for part in date_parts if part) or None
+            works.append(
+                AuthorWork(
+                    title=title,
+                    work_type=summary.get("type"),
+                    publication_date=rendered_date,
+                    identifiers=identifiers,
+                    url=url,
+                )
+            )
+        return tuple(works)
+
+    @staticmethod
+    def _affiliations(activities: dict[str, Any]) -> tuple[str, ...]:
+        names: list[str] = []
+        for section in activities.values():
+            if not isinstance(section, dict):
+                continue
+            for group in section.get("affiliation-group", []):
+                for summaries in group.get("summaries", []):
+                    for summary in summaries.values():
+                        if not isinstance(summary, dict):
+                            continue
+                        organization = summary.get("organization") or {}
+                        name = organization.get("name")
+                        if name and name not in names:
+                            names.append(str(name))
+        return tuple(names)

aristotle/authors/registry.py

@@ -0,0 +1,50 @@
+"""Discovery and routing for author-profile providers."""
+
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING
+
+from aristotle.authors.orcid import ORCIDProvider
+from aristotle.exceptions import PaperNotFound
+
+if TYPE_CHECKING:
+    import httpx
+
+    from aristotle.authors.base import AuthorProvider
+
+
+class AuthorProviderRegistry:
+    """Catalog built-in and third-party author providers."""
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        builtins: list[AuthorProvider] = [ORCIDProvider(client)]
+        self._providers = {provider.name: provider for provider in builtins}
+        for entry_point in entry_points(group="aristotle.author_providers"):
+            if entry_point.name not in self._providers:
+                provider_class = entry_point.load()
+                self._providers[entry_point.name] = provider_class(client)
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        return tuple(self._providers)
+
+    def get(self, name: str) -> AuthorProvider:
+        try:
+            return self._providers[name.lower()]
+        except KeyError as error:
+            choices = ", ".join(self.names)
+            raise PaperNotFound(
+                f"Unknown author provider {name!r}; choose one of: {choices}"
+            ) from error
+
+    def route(self, identifier: str, preferred: str | None = None) -> AuthorProvider:
+        if preferred:
+            provider = self.get(preferred)
+            if not provider.accepts(identifier):
+                raise PaperNotFound(f"{identifier!r} is not a valid {preferred} identifier")
+            return provider
+        for provider in self._providers.values():
+            if provider.accepts(identifier):
+                return provider
+        raise PaperNotFound(f"Could not recognize author identifier {identifier!r}")