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.
Files changed (74) hide show
  1. {scholarx-2.3.7/scholarx.egg-info → scholarx-2.3.9}/PKG-INFO +26 -17
  2. {scholarx-2.3.7 → scholarx-2.3.9}/README.md +23 -14
  3. {scholarx-2.3.7 → scholarx-2.3.9}/pyproject.toml +3 -3
  4. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/__init__.py +0 -2
  5. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/api_client.py +14 -0
  6. scholarx-2.3.9/scholarx/connector_contracts.py +382 -0
  7. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/kg_ingest.py +3 -3
  8. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/kg_media.py +2 -2
  9. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/mcp_server.py +132 -148
  10. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/__init__.py +1 -1
  11. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/certification.json +3 -3
  12. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/scholarx.ttl +8 -6
  13. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/shapes/connector.shacl.ttl +2 -2
  14. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/paper_storage.py +2 -2
  15. scholarx-2.3.9/scholarx/prompts/biomimicry_innovation_scan.json +39 -0
  16. scholarx-2.3.9/scholarx/prompts/scholarx-librarian.json +56 -0
  17. scholarx-2.3.9/scholarx/prompts/scholarx-operator.json +73 -0
  18. scholarx-2.3.9/scholarx/prompts/scholarx-research-scout.json +51 -0
  19. scholarx-2.3.9/scholarx/prompts/scion_sdk_enhancement_scan.json +41 -0
  20. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/base.py +4 -0
  21. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/semantic_scholar.py +16 -0
  22. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-kg-ingestion/SKILL.md +6 -7
  23. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-kg-ingestion/WORKFLOW.md +5 -6
  24. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-operations/references/catalog.md +1 -1
  25. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-library/SKILL.md +28 -26
  26. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-library/WORKFLOW.md +28 -26
  27. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-search/SKILL.md +22 -10
  28. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-paper-search/WORKFLOW.md +22 -10
  29. {scholarx-2.3.7 → scholarx-2.3.9/scholarx.egg-info}/PKG-INFO +26 -17
  30. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/SOURCES.txt +9 -2
  31. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/requires.txt +2 -2
  32. scholarx-2.3.9/tests/test_citing_papers.py +78 -0
  33. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_kg_ingest.py +1 -1
  34. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_kg_media.py +1 -1
  35. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_mcp_server.py +39 -31
  36. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_operation_tools.py +6 -1
  37. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_paper_storage.py +3 -3
  38. scholarx-2.3.9/tests/test_scion_sdk_0_10_imports.py +47 -0
  39. scholarx-2.3.7/tests/test_action_discovery.py +0 -75
  40. {scholarx-2.3.7 → scholarx-2.3.9}/LICENSE +0 -0
  41. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/__main__.py +0 -0
  42. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/cli.py +0 -0
  43. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/connector_sources.py +0 -0
  44. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/connectors/__init__.py +0 -0
  45. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/deduplication.py +0 -0
  46. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/mcp_config.json +0 -0
  47. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/models.py +0 -0
  48. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/fixtures/records.json +0 -0
  49. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/mappings/source.yaml +0 -0
  50. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/ontology/migrations/manifest.json +0 -0
  51. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/prompts/__init__.py +0 -0
  52. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/__init__.py +0 -0
  53. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/arxiv.py +0 -0
  54. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/biorxiv.py +0 -0
  55. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/osf.py +0 -0
  56. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/pmc.py +0 -0
  57. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/providers/rss.py +0 -0
  58. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/queue.py +0 -0
  59. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/__init__.py +0 -0
  60. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-development/SKILL.md +0 -0
  61. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-operations/SKILL.md +0 -0
  62. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx/skills/scholarx-operations/agents/openai.yaml +0 -0
  63. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/dependency_links.txt +0 -0
  64. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/entry_points.txt +0 -0
  65. {scholarx-2.3.7 → scholarx-2.3.9}/scholarx.egg-info/top_level.txt +0 -0
  66. {scholarx-2.3.7 → scholarx-2.3.9}/setup.cfg +0 -0
  67. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_cli.py +0 -0
  68. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_cli_extended.py +0 -0
  69. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_default_content_surfaces.py +0 -0
  70. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_init_dynamics.py +0 -0
  71. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_models.py +0 -0
  72. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_parallel_download.py +0 -0
  73. {scholarx-2.3.7 → scholarx-2.3.9}/tests/test_providers.py +0 -0
  74. {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.7
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.7.0,>=0.6.3
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.7.0,>=0.6.3; extra == "mcp"
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 use dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.
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
- #### Condensed action-routed tools (default — `MCP_TOOL_MODE=condensed`)
91
+ #### Typed tools
92
92
 
93
93
  | MCP Tool | Toggle Env Var | Description |
94
94
  |----------|----------------|-------------|
95
- | `sx_info` | `DISCOVERYTOOL` | Get metadata about sources and categories. |
96
- | `sx_search` | `SEARCHTOOL` | Search for research papers across all configured sources. |
97
- | `sx_storage` | `STORAGETOOL` | Manage offline PDF storage and background downloads. |
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
- #### Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)
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
- _3 action-routed tool(s) (default) · 11 verbose 1:1 tool(s). Each is enabled unless its `<DOMAIN>TOOL` toggle is set false; `MCP_TOOL_MODE` selects the surface (`condensed` default · `verbose` 1:1 · `both`). Auto-generated — do not edit._
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 `epistemic-graph[full]`. The `[agent-runtime]` extra additionally
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 + `epistemic-graph[full]`) | The operator only run the **MCP server** (smallest install / image) |
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 `epistemic-graph[full]`; no model-orchestration stack | `scholarx-mcp` |
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 (`epistemic-graph`)
511
+ ### Knowledge-graph database (`medulla`)
503
512
 
504
- Scion SDK core dependency (`epistemic-graph[full]`). The `[mcp]` extra keeps
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
- **epistemic-graph as a dedicated database service** and configure the runtime to use it.
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
- [epistemic-graph deployment guide](https://knuckles-team.github.io/epistemic-graph/deployment/).
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 use dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.
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
- #### Condensed action-routed tools (default — `MCP_TOOL_MODE=condensed`)
63
+ #### Typed tools
64
64
 
65
65
  | MCP Tool | Toggle Env Var | Description |
66
66
  |----------|----------------|-------------|
67
- | `sx_info` | `DISCOVERYTOOL` | Get metadata about sources and categories. |
68
- | `sx_search` | `SEARCHTOOL` | Search for research papers across all configured sources. |
69
- | `sx_storage` | `STORAGETOOL` | Manage offline PDF storage and background downloads. |
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
- #### Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)
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
- _3 action-routed tool(s) (default) · 11 verbose 1:1 tool(s). Each is enabled unless its `<DOMAIN>TOOL` toggle is set false; `MCP_TOOL_MODE` selects the surface (`condensed` default · `verbose` 1:1 · `both`). Auto-generated — do not edit._
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 `epistemic-graph[full]`. The `[agent-runtime]` extra additionally
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 + `epistemic-graph[full]`) | The operator only run the **MCP server** (smallest install / image) |
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 `epistemic-graph[full]`; no model-orchestration stack | `scholarx-mcp` |
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 (`epistemic-graph`)
483
+ ### Knowledge-graph database (`medulla`)
475
484
 
476
- Scion SDK core dependency (`epistemic-graph[full]`). The `[mcp]` extra keeps
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
- **epistemic-graph as a dedicated database service** and configure the runtime to use it.
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
- [epistemic-graph deployment guide](https://knuckles-team.github.io/epistemic-graph/deployment/).
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"
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.6.3,<0.7.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.6.3,<0.7.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
+ )