scholarx 2.3.7__tar.gz → 2.3.9__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {scholarx-2.3.7/scholarx.egg-info → scholarx-2.3.9}/PKG-INFO +26 -17
- {scholarx-2.3.7 → scholarx-2.3.9}/README.md +23 -14
- {scholarx-2.3.7 → scholarx-2.3.9}/pyproject.toml +3 -3
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/__init__.py +0 -2
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/api_client.py +14 -0
- scholarx-2.3.9/scholarx/connector_contracts.py +382 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/kg_ingest.py +3 -3
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/kg_media.py +2 -2
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/mcp_server.py +132 -148
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/__init__.py +1 -1
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/certification.json +3 -3
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/scholarx.ttl +8 -6
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/shapes/connector.shacl.ttl +2 -2
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/paper_storage.py +2 -2
- scholarx-2.3.9/scholarx/prompts/biomimicry_innovation_scan.json +39 -0
- scholarx-2.3.9/scholarx/prompts/scholarx-librarian.json +56 -0
- scholarx-2.3.9/scholarx/prompts/scholarx-operator.json +73 -0
- scholarx-2.3.9/scholarx/prompts/scholarx-research-scout.json +51 -0
- scholarx-2.3.9/scholarx/prompts/scion_sdk_enhancement_scan.json +41 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/base.py +4 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/semantic_scholar.py +16 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-kg-ingestion/SKILL.md +6 -7
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-kg-ingestion/WORKFLOW.md +5 -6
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-operations/references/catalog.md +1 -1
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-library/SKILL.md +28 -26
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-library/WORKFLOW.md +28 -26
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-search/SKILL.md +22 -10
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-search/WORKFLOW.md +22 -10
- {scholarx-2.3.7 → scholarx-2.3.9/scholarx.egg-info}/PKG-INFO +26 -17
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/SOURCES.txt +9 -2
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/requires.txt +2 -2
- scholarx-2.3.9/tests/test_citing_papers.py +78 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_kg_ingest.py +1 -1
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_kg_media.py +1 -1
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_mcp_server.py +39 -31
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_operation_tools.py +6 -1
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_paper_storage.py +3 -3
- scholarx-2.3.9/tests/test_scion_sdk_0_10_imports.py +47 -0
- scholarx-2.3.7/tests/test_action_discovery.py +0 -75
- {scholarx-2.3.7 → scholarx-2.3.9}/LICENSE +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/__main__.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/cli.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/connector_sources.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/connectors/__init__.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/deduplication.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/mcp_config.json +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/models.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/fixtures/records.json +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/mappings/source.yaml +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/migrations/manifest.json +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/prompts/__init__.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/__init__.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/arxiv.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/biorxiv.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/osf.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/pmc.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/rss.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/queue.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/__init__.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-development/SKILL.md +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-operations/SKILL.md +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-operations/agents/openai.yaml +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/dependency_links.txt +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/entry_points.txt +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/top_level.txt +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/setup.cfg +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_cli.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_cli_extended.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_default_content_surfaces.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_init_dynamics.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_models.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_parallel_download.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_providers.py +0 -0
- {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_queue.py +0 -0
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: scholarx
|
|
3
|
-
Version: 2.3.
|
|
3
|
+
Version: 2.3.9
|
|
4
4
|
Summary: Universal Research Paper API — single entry point for arXiv, PMC, bioRxiv, medRxiv, PsyArXiv, OSF, and Semantic Scholar
|
|
5
5
|
Author-email: Repository Maintainers <maintainers@knuckles.team>
|
|
6
6
|
License: MIT
|
|
7
7
|
Requires-Python: <3.15,>=3.12
|
|
8
8
|
Description-Content-Type: text/markdown
|
|
9
9
|
License-File: LICENSE
|
|
10
|
-
Requires-Dist: scion-sdk[mcp]<0.
|
|
10
|
+
Requires-Dist: scion-sdk[mcp]<0.12,>=0.11.0
|
|
11
11
|
Requires-Dist: httpx>=0.28.1
|
|
12
12
|
Requires-Dist: python-dotenv>=1.2.4
|
|
13
13
|
Requires-Dist: Levenshtein>=0.27.5
|
|
@@ -15,7 +15,7 @@ Requires-Dist: pypdf>=6.21.0
|
|
|
15
15
|
Requires-Dist: rich>=15.0.0
|
|
16
16
|
Requires-Dist: defusedxml>=0.7.1
|
|
17
17
|
Provides-Extra: mcp
|
|
18
|
-
Requires-Dist: scion-sdk[mcp]<0.
|
|
18
|
+
Requires-Dist: scion-sdk[mcp]<0.12,>=0.11.0; extra == "mcp"
|
|
19
19
|
Provides-Extra: all
|
|
20
20
|
Requires-Dist: scholarx[mcp]; extra == "all"
|
|
21
21
|
Provides-Extra: test
|
|
@@ -80,7 +80,7 @@ Detailed instructions on how to use the underlying API wrappers, extended schema
|
|
|
80
80
|
|
|
81
81
|
## MCP
|
|
82
82
|
|
|
83
|
-
This server
|
|
83
|
+
This server serves one typed tool per operation: search, discovery, storage and download tools, plus one tool per ScholarX client method.
|
|
84
84
|
|
|
85
85
|
### Available MCP Tools
|
|
86
86
|
|
|
@@ -88,18 +88,27 @@ The table below is auto-generated from the MCP server — do not edit by hand.
|
|
|
88
88
|
|
|
89
89
|
<!-- MCP-TOOLS-TABLE:START -->
|
|
90
90
|
|
|
91
|
-
####
|
|
91
|
+
#### Typed tools
|
|
92
92
|
|
|
93
93
|
| MCP Tool | Toggle Env Var | Description |
|
|
94
94
|
|----------|----------------|-------------|
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
95
|
+
| `sx_search_search` | `SEARCHTOOL` | Search for research papers across all configured sources. |
|
|
96
|
+
| `sx_search_get` | `SEARCHTOOL` | Retrieve one paper by source and id. |
|
|
97
|
+
| `sx_search_author` | `SEARCHTOOL` | Search papers by author name. |
|
|
98
|
+
| `sx_search_recent` | `SEARCHTOOL` | Papers published in recent days. |
|
|
99
|
+
| `sx_info_sources` | `DISCOVERYTOOL` | Status of every configured source. |
|
|
100
|
+
| `sx_info_categories` | `DISCOVERYTOOL` | Categories each source offers. |
|
|
101
|
+
| `sx_storage_stored` | `STORAGETOOL` | Locally stored papers and statistics. |
|
|
102
|
+
| `sx_storage_status` | `STORAGETOOL` | Status of one queued download. |
|
|
103
|
+
| `sx_storage_queue` | `STORAGETOOL` | Every queued download. |
|
|
104
|
+
| `sx_storage_download` | `STORAGETOOL` | Download one paper. |
|
|
105
|
+
| `sx_storage_download_url` | `STORAGETOOL` | Download arXiv PDFs by id or URL. |
|
|
106
|
+
| `sx_storage_bulk_download` | `STORAGETOOL` | Queue many papers for download. |
|
|
98
107
|
| `sx_enabled_sources` | `OPERATIONTOOL` | List the paper sources enabled on this server (read-only). |
|
|
99
108
|
| `sx_download_papers` | `OPERATIONTOOL` | Download many papers in parallel. |
|
|
100
109
|
| `sx_download_urls` | `OPERATIONTOOL` | Download arXiv PDFs directly by id or URL in parallel. |
|
|
101
110
|
|
|
102
|
-
####
|
|
111
|
+
#### Per-client-method tools
|
|
103
112
|
|
|
104
113
|
<details>
|
|
105
114
|
<summary>11 per-operation tools — one per public API method (click to expand)</summary>
|
|
@@ -120,7 +129,7 @@ The table below is auto-generated from the MCP server — do not edit by hand.
|
|
|
120
129
|
|
|
121
130
|
</details>
|
|
122
131
|
|
|
123
|
-
|
|
132
|
+
_15 typed tool(s) · 12 client-method tool(s) · 1 ingestion tool. Auto-generated - do not edit._
|
|
124
133
|
<!-- MCP-TOOLS-TABLE:END -->
|
|
125
134
|
|
|
126
135
|
Detailed tool schemas, parameter shapes, and validation constraints are preserved in [docs/usage.md](docs/usage.md).
|
|
@@ -152,7 +161,7 @@ When query strings or parameters are supplied, an LLM-free **Knowledge Graph res
|
|
|
152
161
|
|
|
153
162
|
> **Install the connector-focused `[mcp]` extra.** Examples use `scholarx[mcp]` to add
|
|
154
163
|
> FastMCP / FastAPI through `scion-sdk`; the required Scion SDK core
|
|
155
|
-
> still carries `
|
|
164
|
+
> still carries `medulla[full]`. The `[agent-runtime]` extra additionally
|
|
156
165
|
> enables model orchestration.
|
|
157
166
|
|
|
158
167
|
#### stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)
|
|
@@ -472,7 +481,7 @@ Pick the extra that matches what the operator want to run:
|
|
|
472
481
|
|
|
473
482
|
| Extra | Installs | Use when |
|
|
474
483
|
|-------|----------|----------|
|
|
475
|
-
| `scholarx[mcp]` | Connector-focused MCP server (`scion-sdk` — FastMCP/FastAPI + `
|
|
484
|
+
| `scholarx[mcp]` | Connector-focused MCP server (`scion-sdk` — FastMCP/FastAPI + `medulla[full]`) | The operator only run the **MCP server** (smallest install / image) |
|
|
476
485
|
| `scholarx[all]` | Everything (`mcp` + `agent`) | Development / both surfaces |
|
|
477
486
|
|
|
478
487
|
```bash
|
|
@@ -491,7 +500,7 @@ One multi-stage `docker/Dockerfile` builds the MCP-only image (`--target mcp`):
|
|
|
491
500
|
|
|
492
501
|
| Image tag | Build target | Contents | Entrypoint |
|
|
493
502
|
|-----------|--------------|----------|------------|
|
|
494
|
-
| `example/scholarx:mcp` | `--target mcp` | `scholarx[mcp]` — **connector-focused**, includes `
|
|
503
|
+
| `example/scholarx:mcp` | `--target mcp` | `scholarx[mcp]` — **connector-focused**, includes `medulla[full]`; no model-orchestration stack | `scholarx-mcp` |
|
|
495
504
|
|
|
496
505
|
```bash
|
|
497
506
|
docker build --target mcp -t example/scholarx:mcp docker/ # connector-focused MCP server
|
|
@@ -499,14 +508,14 @@ docker build --target mcp -t example/scholarx:mcp docker/ # connector-foc
|
|
|
499
508
|
|
|
500
509
|
agent (`immutable agent digest`) with a co-located `:mcp` sidecar.
|
|
501
510
|
|
|
502
|
-
### Knowledge-graph database (`
|
|
511
|
+
### Knowledge-graph database (`medulla`)
|
|
503
512
|
|
|
504
|
-
Scion SDK core dependency (`
|
|
513
|
+
Scion SDK core dependency (`medulla[full]`). The `[mcp]` extra keeps
|
|
505
514
|
deployments can use the bundled engine. For production or shared state, run
|
|
506
|
-
**
|
|
515
|
+
**medulla as a dedicated database service** and configure the runtime to use it.
|
|
507
516
|
Deployment recipes (single-node + Raft HA), connection configuration, and architecture
|
|
508
517
|
diagrams are documented in the
|
|
509
|
-
[
|
|
518
|
+
[medulla deployment guide](https://knuckles-team.github.io/medulla/deployment/).
|
|
510
519
|
|
|
511
520
|
---
|
|
512
521
|
|
|
@@ -52,7 +52,7 @@ Detailed instructions on how to use the underlying API wrappers, extended schema
|
|
|
52
52
|
|
|
53
53
|
## MCP
|
|
54
54
|
|
|
55
|
-
This server
|
|
55
|
+
This server serves one typed tool per operation: search, discovery, storage and download tools, plus one tool per ScholarX client method.
|
|
56
56
|
|
|
57
57
|
### Available MCP Tools
|
|
58
58
|
|
|
@@ -60,18 +60,27 @@ The table below is auto-generated from the MCP server — do not edit by hand.
|
|
|
60
60
|
|
|
61
61
|
<!-- MCP-TOOLS-TABLE:START -->
|
|
62
62
|
|
|
63
|
-
####
|
|
63
|
+
#### Typed tools
|
|
64
64
|
|
|
65
65
|
| MCP Tool | Toggle Env Var | Description |
|
|
66
66
|
|----------|----------------|-------------|
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
67
|
+
| `sx_search_search` | `SEARCHTOOL` | Search for research papers across all configured sources. |
|
|
68
|
+
| `sx_search_get` | `SEARCHTOOL` | Retrieve one paper by source and id. |
|
|
69
|
+
| `sx_search_author` | `SEARCHTOOL` | Search papers by author name. |
|
|
70
|
+
| `sx_search_recent` | `SEARCHTOOL` | Papers published in recent days. |
|
|
71
|
+
| `sx_info_sources` | `DISCOVERYTOOL` | Status of every configured source. |
|
|
72
|
+
| `sx_info_categories` | `DISCOVERYTOOL` | Categories each source offers. |
|
|
73
|
+
| `sx_storage_stored` | `STORAGETOOL` | Locally stored papers and statistics. |
|
|
74
|
+
| `sx_storage_status` | `STORAGETOOL` | Status of one queued download. |
|
|
75
|
+
| `sx_storage_queue` | `STORAGETOOL` | Every queued download. |
|
|
76
|
+
| `sx_storage_download` | `STORAGETOOL` | Download one paper. |
|
|
77
|
+
| `sx_storage_download_url` | `STORAGETOOL` | Download arXiv PDFs by id or URL. |
|
|
78
|
+
| `sx_storage_bulk_download` | `STORAGETOOL` | Queue many papers for download. |
|
|
70
79
|
| `sx_enabled_sources` | `OPERATIONTOOL` | List the paper sources enabled on this server (read-only). |
|
|
71
80
|
| `sx_download_papers` | `OPERATIONTOOL` | Download many papers in parallel. |
|
|
72
81
|
| `sx_download_urls` | `OPERATIONTOOL` | Download arXiv PDFs directly by id or URL in parallel. |
|
|
73
82
|
|
|
74
|
-
####
|
|
83
|
+
#### Per-client-method tools
|
|
75
84
|
|
|
76
85
|
<details>
|
|
77
86
|
<summary>11 per-operation tools — one per public API method (click to expand)</summary>
|
|
@@ -92,7 +101,7 @@ The table below is auto-generated from the MCP server — do not edit by hand.
|
|
|
92
101
|
|
|
93
102
|
</details>
|
|
94
103
|
|
|
95
|
-
|
|
104
|
+
_15 typed tool(s) · 12 client-method tool(s) · 1 ingestion tool. Auto-generated - do not edit._
|
|
96
105
|
<!-- MCP-TOOLS-TABLE:END -->
|
|
97
106
|
|
|
98
107
|
Detailed tool schemas, parameter shapes, and validation constraints are preserved in [docs/usage.md](docs/usage.md).
|
|
@@ -124,7 +133,7 @@ When query strings or parameters are supplied, an LLM-free **Knowledge Graph res
|
|
|
124
133
|
|
|
125
134
|
> **Install the connector-focused `[mcp]` extra.** Examples use `scholarx[mcp]` to add
|
|
126
135
|
> FastMCP / FastAPI through `scion-sdk`; the required Scion SDK core
|
|
127
|
-
> still carries `
|
|
136
|
+
> still carries `medulla[full]`. The `[agent-runtime]` extra additionally
|
|
128
137
|
> enables model orchestration.
|
|
129
138
|
|
|
130
139
|
#### stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)
|
|
@@ -444,7 +453,7 @@ Pick the extra that matches what the operator want to run:
|
|
|
444
453
|
|
|
445
454
|
| Extra | Installs | Use when |
|
|
446
455
|
|-------|----------|----------|
|
|
447
|
-
| `scholarx[mcp]` | Connector-focused MCP server (`scion-sdk` — FastMCP/FastAPI + `
|
|
456
|
+
| `scholarx[mcp]` | Connector-focused MCP server (`scion-sdk` — FastMCP/FastAPI + `medulla[full]`) | The operator only run the **MCP server** (smallest install / image) |
|
|
448
457
|
| `scholarx[all]` | Everything (`mcp` + `agent`) | Development / both surfaces |
|
|
449
458
|
|
|
450
459
|
```bash
|
|
@@ -463,7 +472,7 @@ One multi-stage `docker/Dockerfile` builds the MCP-only image (`--target mcp`):
|
|
|
463
472
|
|
|
464
473
|
| Image tag | Build target | Contents | Entrypoint |
|
|
465
474
|
|-----------|--------------|----------|------------|
|
|
466
|
-
| `example/scholarx:mcp` | `--target mcp` | `scholarx[mcp]` — **connector-focused**, includes `
|
|
475
|
+
| `example/scholarx:mcp` | `--target mcp` | `scholarx[mcp]` — **connector-focused**, includes `medulla[full]`; no model-orchestration stack | `scholarx-mcp` |
|
|
467
476
|
|
|
468
477
|
```bash
|
|
469
478
|
docker build --target mcp -t example/scholarx:mcp docker/ # connector-focused MCP server
|
|
@@ -471,14 +480,14 @@ docker build --target mcp -t example/scholarx:mcp docker/ # connector-foc
|
|
|
471
480
|
|
|
472
481
|
agent (`immutable agent digest`) with a co-located `:mcp` sidecar.
|
|
473
482
|
|
|
474
|
-
### Knowledge-graph database (`
|
|
483
|
+
### Knowledge-graph database (`medulla`)
|
|
475
484
|
|
|
476
|
-
Scion SDK core dependency (`
|
|
485
|
+
Scion SDK core dependency (`medulla[full]`). The `[mcp]` extra keeps
|
|
477
486
|
deployments can use the bundled engine. For production or shared state, run
|
|
478
|
-
**
|
|
487
|
+
**medulla as a dedicated database service** and configure the runtime to use it.
|
|
479
488
|
Deployment recipes (single-node + Raft HA), connection configuration, and architecture
|
|
480
489
|
diagrams are documented in the
|
|
481
|
-
[
|
|
490
|
+
[medulla deployment guide](https://knuckles-team.github.io/medulla/deployment/).
|
|
482
491
|
|
|
483
492
|
---
|
|
484
493
|
|
|
@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "scholarx"
|
|
7
|
-
version = "2.3.
|
|
7
|
+
version = "2.3.9"
|
|
8
8
|
description = "Universal Research Paper API — single entry point for arXiv, PMC, bioRxiv, medRxiv, PsyArXiv, OSF, and Semantic Scholar"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = { text = "MIT" }
|
|
11
11
|
requires-python = ">=3.12, <3.15"
|
|
12
12
|
authors = [{ name = "Repository Maintainers", email = "maintainers@knuckles.team" }]
|
|
13
13
|
dependencies = [
|
|
14
|
-
"scion-sdk[mcp]>=0.
|
|
14
|
+
"scion-sdk[mcp]>=0.11.0,<0.12",
|
|
15
15
|
"httpx>=0.28.1",
|
|
16
16
|
"python-dotenv>=1.2.4",
|
|
17
17
|
"Levenshtein>=0.27.5",
|
|
@@ -21,7 +21,7 @@ dependencies = [
|
|
|
21
21
|
]
|
|
22
22
|
|
|
23
23
|
[project.optional-dependencies]
|
|
24
|
-
mcp = ["scion-sdk[mcp]>=0.
|
|
24
|
+
mcp = ["scion-sdk[mcp]>=0.11.0,<0.12"]
|
|
25
25
|
all = ["scholarx[mcp]"]
|
|
26
26
|
test = [
|
|
27
27
|
"pytest-xdist>=3.8.0","pytest>=9.1.1", "pytest-asyncio>=1.4.0", "pytest-cov>=7.1.0", "respx>=0.23.1"]
|
|
@@ -93,7 +93,6 @@ def _declare_connector():
|
|
|
93
93
|
register_discovery_tools,
|
|
94
94
|
register_kg_tools,
|
|
95
95
|
register_operation_tools,
|
|
96
|
-
register_prompt_surface,
|
|
97
96
|
register_search_tools,
|
|
98
97
|
register_storage_tools,
|
|
99
98
|
)
|
|
@@ -114,7 +113,6 @@ def _declare_connector():
|
|
|
114
113
|
("operation", "OPERATIONTOOL", register_operation_tools),
|
|
115
114
|
("kg", "KGTOOL", register_kg_tools),
|
|
116
115
|
),
|
|
117
|
-
extra_registrations=(register_prompt_surface,),
|
|
118
116
|
)
|
|
119
117
|
|
|
120
118
|
|
|
@@ -258,6 +258,20 @@ class ScholarXClient:
|
|
|
258
258
|
return None
|
|
259
259
|
return await provider.get_paper(paper_id)
|
|
260
260
|
|
|
261
|
+
async def get_citing_papers(self, source: PaperSource, paper_id: str, limit: int = 20) -> list[Paper]:
|
|
262
|
+
"""Papers that cite ``paper_id`` according to ``source``.
|
|
263
|
+
|
|
264
|
+
Raises:
|
|
265
|
+
ValueError: the source is not configured or has no citation graph.
|
|
266
|
+
"""
|
|
267
|
+
provider = self._providers.get(source)
|
|
268
|
+
if not provider:
|
|
269
|
+
raise ValueError(f"Source not configured: {source.value}")
|
|
270
|
+
try:
|
|
271
|
+
return await provider.get_citations(paper_id, limit)
|
|
272
|
+
except NotImplementedError as exc:
|
|
273
|
+
raise ValueError(str(exc)) from exc
|
|
274
|
+
|
|
261
275
|
async def get_recent_papers(
|
|
262
276
|
self,
|
|
263
277
|
categories: list[str] | None = None,
|
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
"""Surface contracts: tool use, links, data locations and business roles."""
|
|
2
|
+
|
|
3
|
+
from scion_sdk.surface_contracts import (
|
|
4
|
+
BusinessRole,
|
|
5
|
+
DataLocation,
|
|
6
|
+
Refusal,
|
|
7
|
+
SurfaceLink,
|
|
8
|
+
ToolStep,
|
|
9
|
+
ToolUseContract,
|
|
10
|
+
)
|
|
11
|
+
|
|
12
|
+
CONTRACTS = (
|
|
13
|
+
ToolUseContract(
|
|
14
|
+
"search-papers",
|
|
15
|
+
(
|
|
16
|
+
ToolStep(
|
|
17
|
+
"sx_enabled_sources",
|
|
18
|
+
result=("sources",),
|
|
19
|
+
),
|
|
20
|
+
ToolStep(
|
|
21
|
+
"sx_search_search",
|
|
22
|
+
params=("query", "sources", "categories", "max_results", "sort_by", "title", "paper_id"),
|
|
23
|
+
result=("papers", "total_count", "sources_queried", "deduplicated_count"),
|
|
24
|
+
refusals=(Refusal("SOURCE_UNAVAILABLE", "the paper source is disabled or does not answer"),),
|
|
25
|
+
),
|
|
26
|
+
ToolStep(
|
|
27
|
+
"scholarx_search",
|
|
28
|
+
params=("query",),
|
|
29
|
+
result=("papers", "total_count"),
|
|
30
|
+
refusals=(Refusal("SOURCE_UNAVAILABLE", "the paper source is disabled or does not answer"),),
|
|
31
|
+
),
|
|
32
|
+
),
|
|
33
|
+
),
|
|
34
|
+
ToolUseContract(
|
|
35
|
+
"read-a-paper",
|
|
36
|
+
(
|
|
37
|
+
ToolStep(
|
|
38
|
+
"sx_search_get",
|
|
39
|
+
params=("sources", "paper_id"),
|
|
40
|
+
result=("id", "title", "authors", "abstract", "pdf_url"),
|
|
41
|
+
refusals=(
|
|
42
|
+
Refusal("PAPER_NOT_FOUND", "no paper has the id in that source"),
|
|
43
|
+
Refusal("INVALID_SOURCE", "the source is not one of the enabled paper sources"),
|
|
44
|
+
),
|
|
45
|
+
),
|
|
46
|
+
ToolStep(
|
|
47
|
+
"scholarx_get_paper",
|
|
48
|
+
params=("source", "paper_id"),
|
|
49
|
+
result=("id", "title", "authors", "abstract"),
|
|
50
|
+
refusals=(
|
|
51
|
+
Refusal("PAPER_NOT_FOUND", "no paper has the id in that source"),
|
|
52
|
+
Refusal("INVALID_SOURCE", "the source is not one of the enabled paper sources"),
|
|
53
|
+
),
|
|
54
|
+
),
|
|
55
|
+
),
|
|
56
|
+
),
|
|
57
|
+
ToolUseContract(
|
|
58
|
+
"find-citing-papers",
|
|
59
|
+
(
|
|
60
|
+
ToolStep(
|
|
61
|
+
"sx_search_citations",
|
|
62
|
+
params=("paper_id", "sources", "max_results"),
|
|
63
|
+
result=("papers", "total_count"),
|
|
64
|
+
refusals=(
|
|
65
|
+
Refusal("PAPER_ID_REQUIRED", "no paper id was supplied"),
|
|
66
|
+
Refusal("CITATIONS_UNSUPPORTED", "the source has no citation graph"),
|
|
67
|
+
),
|
|
68
|
+
),
|
|
69
|
+
ToolStep(
|
|
70
|
+
"scholarx_get_citing_papers",
|
|
71
|
+
params=("source", "paper_id", "limit"),
|
|
72
|
+
result=("id", "title", "authors"),
|
|
73
|
+
refusals=(Refusal("INVALID_SOURCE", "the source is not configured or has no citation graph"),),
|
|
74
|
+
),
|
|
75
|
+
),
|
|
76
|
+
),
|
|
77
|
+
ToolUseContract(
|
|
78
|
+
"find-papers-by-author",
|
|
79
|
+
(
|
|
80
|
+
ToolStep(
|
|
81
|
+
"sx_search_author",
|
|
82
|
+
params=("author", "max_results"),
|
|
83
|
+
result=("papers", "total_count"),
|
|
84
|
+
refusals=(Refusal("AUTHOR_REQUIRED", "no author name was supplied"),),
|
|
85
|
+
),
|
|
86
|
+
),
|
|
87
|
+
),
|
|
88
|
+
ToolUseContract(
|
|
89
|
+
"track-recent-papers",
|
|
90
|
+
(
|
|
91
|
+
ToolStep(
|
|
92
|
+
"sx_search_recent",
|
|
93
|
+
params=("categories", "days", "sources"),
|
|
94
|
+
result=("papers", "total_count", "sources_queried"),
|
|
95
|
+
refusals=(Refusal("SOURCE_UNAVAILABLE", "the paper source is disabled or does not answer"),),
|
|
96
|
+
),
|
|
97
|
+
ToolStep(
|
|
98
|
+
"scholarx_get_recent_papers",
|
|
99
|
+
params=("categories", "days", "sources"),
|
|
100
|
+
result=("papers", "total_count"),
|
|
101
|
+
refusals=(Refusal("SOURCE_UNAVAILABLE", "the paper source is disabled or does not answer"),),
|
|
102
|
+
),
|
|
103
|
+
),
|
|
104
|
+
),
|
|
105
|
+
ToolUseContract(
|
|
106
|
+
"explore-sources-and-categories",
|
|
107
|
+
(
|
|
108
|
+
ToolStep(
|
|
109
|
+
"sx_info_sources",
|
|
110
|
+
result=("sources",),
|
|
111
|
+
),
|
|
112
|
+
ToolStep(
|
|
113
|
+
"sx_info_categories",
|
|
114
|
+
params=("source",),
|
|
115
|
+
result=("categories",),
|
|
116
|
+
refusals=(Refusal("INVALID_SOURCE", "the source is not one of the enabled paper sources"),),
|
|
117
|
+
),
|
|
118
|
+
ToolStep(
|
|
119
|
+
"scholarx_get_source_status",
|
|
120
|
+
result=("source", "enabled", "status"),
|
|
121
|
+
),
|
|
122
|
+
ToolStep(
|
|
123
|
+
"scholarx_list_categories",
|
|
124
|
+
params=("source",),
|
|
125
|
+
result=("categories",),
|
|
126
|
+
refusals=(Refusal("INVALID_SOURCE", "the source is not one of the enabled paper sources"),),
|
|
127
|
+
),
|
|
128
|
+
ToolStep(
|
|
129
|
+
"scholarx_enabled_sources",
|
|
130
|
+
result=("sources",),
|
|
131
|
+
),
|
|
132
|
+
),
|
|
133
|
+
),
|
|
134
|
+
ToolUseContract(
|
|
135
|
+
"download-papers",
|
|
136
|
+
(
|
|
137
|
+
ToolStep(
|
|
138
|
+
"sx_storage_download",
|
|
139
|
+
params=("source", "paper_ids"),
|
|
140
|
+
result=("status", "local_path", "paper_id"),
|
|
141
|
+
refusals=(
|
|
142
|
+
Refusal("PAPER_NOT_FOUND", "no paper has the id in that source"),
|
|
143
|
+
Refusal("INVALID_SOURCE", "the source is not one of the enabled paper sources"),
|
|
144
|
+
Refusal("LIMIT_EXCEEDED", "the id list or input exceeds the documented bound"),
|
|
145
|
+
),
|
|
146
|
+
),
|
|
147
|
+
ToolStep(
|
|
148
|
+
"sx_storage_download_url",
|
|
149
|
+
params=("paper_ids",),
|
|
150
|
+
result=("results",),
|
|
151
|
+
refusals=(
|
|
152
|
+
Refusal("LIMIT_EXCEEDED", "the id list or input exceeds the documented bound"),
|
|
153
|
+
Refusal("INVALID_ARXIV_ID", "the identifier is not an arXiv id or URL"),
|
|
154
|
+
),
|
|
155
|
+
),
|
|
156
|
+
ToolStep(
|
|
157
|
+
"sx_download_papers",
|
|
158
|
+
params=("source", "paper_ids", "concurrency"),
|
|
159
|
+
result=("results",),
|
|
160
|
+
refusals=(
|
|
161
|
+
Refusal("INVALID_SOURCE", "the source is not one of the enabled paper sources"),
|
|
162
|
+
Refusal("LIMIT_EXCEEDED", "the id list or input exceeds the documented bound"),
|
|
163
|
+
),
|
|
164
|
+
),
|
|
165
|
+
ToolStep(
|
|
166
|
+
"sx_download_urls",
|
|
167
|
+
params=("paper_ids", "concurrency"),
|
|
168
|
+
result=("results",),
|
|
169
|
+
refusals=(Refusal("LIMIT_EXCEEDED", "the id list or input exceeds the documented bound"),),
|
|
170
|
+
),
|
|
171
|
+
ToolStep(
|
|
172
|
+
"scholarx_download_paper",
|
|
173
|
+
params=("paper",),
|
|
174
|
+
result=("local_path",),
|
|
175
|
+
refusals=(Refusal("SOURCE_UNAVAILABLE", "the paper source is disabled or does not answer"),),
|
|
176
|
+
),
|
|
177
|
+
ToolStep(
|
|
178
|
+
"scholarx_download_papers",
|
|
179
|
+
params=("papers", "concurrency"),
|
|
180
|
+
result=("results",),
|
|
181
|
+
refusals=(Refusal("SOURCE_UNAVAILABLE", "the paper source is disabled or does not answer"),),
|
|
182
|
+
),
|
|
183
|
+
ToolStep(
|
|
184
|
+
"scholarx_download_urls",
|
|
185
|
+
params=("raw_ids", "concurrency"),
|
|
186
|
+
result=("results",),
|
|
187
|
+
refusals=(Refusal("LIMIT_EXCEEDED", "the id list or input exceeds the documented bound"),),
|
|
188
|
+
),
|
|
189
|
+
),
|
|
190
|
+
),
|
|
191
|
+
ToolUseContract(
|
|
192
|
+
"queue-background-downloads",
|
|
193
|
+
(
|
|
194
|
+
ToolStep(
|
|
195
|
+
"sx_storage_bulk_download",
|
|
196
|
+
params=("source", "paper_ids"),
|
|
197
|
+
result=("results", "job_id"),
|
|
198
|
+
refusals=(
|
|
199
|
+
Refusal("INVALID_SOURCE", "the source is not one of the enabled paper sources"),
|
|
200
|
+
Refusal("LIMIT_EXCEEDED", "the id list or input exceeds the documented bound"),
|
|
201
|
+
),
|
|
202
|
+
),
|
|
203
|
+
ToolStep(
|
|
204
|
+
"scholarx_queue_download",
|
|
205
|
+
params=("paper",),
|
|
206
|
+
result=("job_id",),
|
|
207
|
+
),
|
|
208
|
+
ToolStep(
|
|
209
|
+
"sx_storage_status",
|
|
210
|
+
params=("job_id",),
|
|
211
|
+
result=("status",),
|
|
212
|
+
refusals=(Refusal("JOB_NOT_FOUND", "no queued job has the id"),),
|
|
213
|
+
),
|
|
214
|
+
ToolStep(
|
|
215
|
+
"scholarx_get_download_status",
|
|
216
|
+
params=("job_id",),
|
|
217
|
+
result=("status",),
|
|
218
|
+
refusals=(Refusal("JOB_NOT_FOUND", "no queued job has the id"),),
|
|
219
|
+
),
|
|
220
|
+
ToolStep(
|
|
221
|
+
"sx_storage_queue",
|
|
222
|
+
result=("downloads",),
|
|
223
|
+
),
|
|
224
|
+
ToolStep(
|
|
225
|
+
"scholarx_get_queue_status",
|
|
226
|
+
result=("downloads",),
|
|
227
|
+
),
|
|
228
|
+
),
|
|
229
|
+
),
|
|
230
|
+
ToolUseContract(
|
|
231
|
+
"review-stored-papers",
|
|
232
|
+
(
|
|
233
|
+
ToolStep(
|
|
234
|
+
"sx_storage_stored",
|
|
235
|
+
result=("papers", "stats"),
|
|
236
|
+
),
|
|
237
|
+
),
|
|
238
|
+
),
|
|
239
|
+
ToolUseContract(
|
|
240
|
+
"ingest-papers-to-graph",
|
|
241
|
+
(
|
|
242
|
+
ToolStep(
|
|
243
|
+
"scholarx_ingest_papers",
|
|
244
|
+
params=("query", "sources", "categories", "max_results"),
|
|
245
|
+
result=("fetched", "ingested"),
|
|
246
|
+
refusals=(Refusal("NO_ENGINE", "no knowledge-graph engine is reachable, ingested is null"),),
|
|
247
|
+
),
|
|
248
|
+
),
|
|
249
|
+
),
|
|
250
|
+
)
|
|
251
|
+
|
|
252
|
+
LINKS = (
|
|
253
|
+
SurfaceLink(
|
|
254
|
+
"search-papers",
|
|
255
|
+
tools=("sx_enabled_sources", "sx_search_search", "scholarx_search"),
|
|
256
|
+
prompts=(
|
|
257
|
+
"scholarx-operator",
|
|
258
|
+
"scholarx-research-scout",
|
|
259
|
+
"scion_sdk_enhancement_scan",
|
|
260
|
+
"biomimicry_innovation_scan",
|
|
261
|
+
),
|
|
262
|
+
skills=("scholarx-paper-search",),
|
|
263
|
+
),
|
|
264
|
+
SurfaceLink(
|
|
265
|
+
"read-a-paper",
|
|
266
|
+
tools=("sx_search_get", "scholarx_get_paper"),
|
|
267
|
+
prompts=("scholarx-operator", "scholarx-research-scout"),
|
|
268
|
+
skills=("scholarx-paper-search",),
|
|
269
|
+
),
|
|
270
|
+
SurfaceLink(
|
|
271
|
+
"find-citing-papers",
|
|
272
|
+
tools=("sx_search_citations", "scholarx_get_citing_papers"),
|
|
273
|
+
prompts=("scholarx-operator", "scholarx-research-scout"),
|
|
274
|
+
skills=("scholarx-paper-search",),
|
|
275
|
+
),
|
|
276
|
+
SurfaceLink(
|
|
277
|
+
"find-papers-by-author",
|
|
278
|
+
tools=("sx_search_author",),
|
|
279
|
+
prompts=("scholarx-operator", "scholarx-research-scout"),
|
|
280
|
+
skills=("scholarx-paper-search",),
|
|
281
|
+
),
|
|
282
|
+
SurfaceLink(
|
|
283
|
+
"track-recent-papers",
|
|
284
|
+
tools=("sx_search_recent", "scholarx_get_recent_papers"),
|
|
285
|
+
prompts=("scholarx-operator", "scholarx-research-scout", "scion_sdk_enhancement_scan"),
|
|
286
|
+
skills=("scholarx-paper-search",),
|
|
287
|
+
),
|
|
288
|
+
SurfaceLink(
|
|
289
|
+
"explore-sources-and-categories",
|
|
290
|
+
tools=(
|
|
291
|
+
"sx_info_sources",
|
|
292
|
+
"sx_info_categories",
|
|
293
|
+
"scholarx_get_source_status",
|
|
294
|
+
"scholarx_list_categories",
|
|
295
|
+
"scholarx_enabled_sources",
|
|
296
|
+
),
|
|
297
|
+
prompts=("scholarx-operator", "scholarx-research-scout"),
|
|
298
|
+
skills=("scholarx-paper-search",),
|
|
299
|
+
),
|
|
300
|
+
SurfaceLink(
|
|
301
|
+
"download-papers",
|
|
302
|
+
tools=(
|
|
303
|
+
"sx_storage_download",
|
|
304
|
+
"sx_storage_download_url",
|
|
305
|
+
"sx_download_papers",
|
|
306
|
+
"sx_download_urls",
|
|
307
|
+
"scholarx_download_paper",
|
|
308
|
+
"scholarx_download_papers",
|
|
309
|
+
"scholarx_download_urls",
|
|
310
|
+
),
|
|
311
|
+
prompts=("scholarx-operator", "scholarx-librarian"),
|
|
312
|
+
skills=("scholarx-paper-library",),
|
|
313
|
+
),
|
|
314
|
+
SurfaceLink(
|
|
315
|
+
"queue-background-downloads",
|
|
316
|
+
tools=(
|
|
317
|
+
"sx_storage_bulk_download",
|
|
318
|
+
"scholarx_queue_download",
|
|
319
|
+
"sx_storage_status",
|
|
320
|
+
"scholarx_get_download_status",
|
|
321
|
+
"sx_storage_queue",
|
|
322
|
+
"scholarx_get_queue_status",
|
|
323
|
+
),
|
|
324
|
+
prompts=("scholarx-operator", "scholarx-librarian"),
|
|
325
|
+
skills=("scholarx-paper-library",),
|
|
326
|
+
),
|
|
327
|
+
SurfaceLink(
|
|
328
|
+
"review-stored-papers",
|
|
329
|
+
tools=("sx_storage_stored",),
|
|
330
|
+
prompts=("scholarx-operator", "scholarx-librarian"),
|
|
331
|
+
skills=("scholarx-paper-library",),
|
|
332
|
+
),
|
|
333
|
+
SurfaceLink(
|
|
334
|
+
"ingest-papers-to-graph",
|
|
335
|
+
tools=("scholarx_ingest_papers",),
|
|
336
|
+
prompts=("scholarx-operator", "scholarx-librarian"),
|
|
337
|
+
skills=("scholarx-kg-ingestion",),
|
|
338
|
+
),
|
|
339
|
+
SurfaceLink(
|
|
340
|
+
"scholarx-operations",
|
|
341
|
+
tools=("sx_search_search", "sx_storage_download", "scholarx_search"),
|
|
342
|
+
skills=("scholarx-operations",),
|
|
343
|
+
),
|
|
344
|
+
)
|
|
345
|
+
|
|
346
|
+
LOCATIONS = (
|
|
347
|
+
DataLocation(
|
|
348
|
+
"scholarx-paper-sources",
|
|
349
|
+
("Paper", "PaperSource", "ResearchCategory"),
|
|
350
|
+
"SCHOLARX_SOURCES",
|
|
351
|
+
"sx_search_search",
|
|
352
|
+
route_param="sources",
|
|
353
|
+
federation_key="paper_id",
|
|
354
|
+
),
|
|
355
|
+
DataLocation(
|
|
356
|
+
"scholarx-paper-store",
|
|
357
|
+
("Paper",),
|
|
358
|
+
"SCHOLARX_OUTPUT_DIR",
|
|
359
|
+
"sx_storage_stored",
|
|
360
|
+
federation_key="paper_id",
|
|
361
|
+
),
|
|
362
|
+
)
|
|
363
|
+
|
|
364
|
+
ROLES = (
|
|
365
|
+
BusinessRole(
|
|
366
|
+
"research-scout",
|
|
367
|
+
tasks=(
|
|
368
|
+
"search-papers",
|
|
369
|
+
"read-a-paper",
|
|
370
|
+
"find-papers-by-author",
|
|
371
|
+
"find-citing-papers",
|
|
372
|
+
"track-recent-papers",
|
|
373
|
+
"explore-sources-and-categories",
|
|
374
|
+
),
|
|
375
|
+
),
|
|
376
|
+
BusinessRole("enhancement-analyst", tasks=("search-papers", "track-recent-papers")),
|
|
377
|
+
BusinessRole("biomimicry-analyst", tasks=("search-papers",)),
|
|
378
|
+
BusinessRole(
|
|
379
|
+
"librarian",
|
|
380
|
+
tasks=("download-papers", "queue-background-downloads", "review-stored-papers", "ingest-papers-to-graph"),
|
|
381
|
+
),
|
|
382
|
+
)
|