Skip to content

third-parties.md

Latest commit

 

History

History
110 lines (85 loc) · 7.64 KB

third-parties.md

File metadata and controls

110 lines (85 loc) · 7.64 KB
Raw

Third-party dependencies

Status: Audit performed 2026-04-19 against the repository HEAD. Describes Python packages the project links against, external HTTP services it talks to, and the runtime infrastructure it assumes. Ends with a list of issues found during this audit.

1. Python packages

1.1 Runtime (declared in pyproject.toml)

Package Min version Where it's used Criticality
fastapi 0.115 src/api/app.py, routes_* — REST layer Required
uvicorn[standard] 0.30 ASGI server (invoked from CLI, not imported) Required for API
httpx 0.27 All HTTP I/O: LLM providers, Serper, Zyte, Kroki, health checks, tests Required
pydantic 2.9 Domain/API DTOs, LLMStepResponse, FinalAnswer, CriticResult Required
pydantic-settings 2.5 config/settings.py::Settings Required
sqlalchemy[asyncio] 2.0 Async ORM for evidence store Required
aiosqlite 0.20 Async SQLite driver (consumed via URL sqlite+aiosqlite://) Required
alembic 1.14 DB migrations (migrations/) Required at deploy
structlog 24.0 src/logging_/logger.py — structured JSON logging Required
pymupdf 1.24 src/tools/pdf_read.py (imported as fitz) Required for pdf_read tool
yake 0.4 src/tools/query_expander.py — keyword-based search expansion Required for query_expander
docker 7.0 src/tools/python_exec.py, src/api/routes_health.py — sandbox control Required for python_exec + /health/services
sse-starlette 2.0 src/api/routes_research.py — SSE stream Required

1.2 Dev / test (declared)

Package Where it's used
pytest Whole tests/ directory
pytest-asyncio tests/conftest.py and async tests
pytest-cov Coverage reports
ruff Linter (CLI-only; not imported)
mypy Type checker (CLI-only; not imported)

2. External services (HTTP)

Every outbound integration is listed here. Anything talking to the internet or to a local daemon counts.

Service When it's used Base URL setting Secret setting Endpoint(s) called
Ollama RC_LLM_PROVIDER=ollama (default) RC_LLM_BASE_URL RC_LLM_API_TOKEN (optional) POST /api/generate, GET /api/tags
OpenAI RC_LLM_PROVIDER=openai + diagram_gen tool RC_OPENAI_BASE_URL RC_OPENAI_API_KEY (required) POST /v1/chat/completions, GET /v1/models
llama.cpp server RC_LLM_PROVIDER=llama_cpp RC_LLAMA_CPP_BASE_URL RC_LLAMA_CPP_API_KEY (optional) POST /v1/chat/completions, GET /v1/models
Serper web_search tool RC_SERPER_BASE_URL RC_SERPER_API_KEY (required) POST /search
Zyte web_fetch, pdf_read tools RC_ZYTE_BASE_URL RC_ZYTE_API_KEY (required) POST /v1/extract
Kroki diagram_gen tool (Mermaid rendering) RC_KROKI_BASE_URL — POST /mermaid/svg (and similar)

Provider selection is mutually exclusive — only one of Ollama / OpenAI / llama.cpp is active per process, chosen by RC_LLM_PROVIDER. Note that the diagram_gen tool always uses OpenAI regardless of the main LLM provider (it needs RC_OPENAI_API_KEY independently).

Credential hygiene: all secret settings default to "" in config/settings.py. Providers that need a key raise LLMConfigError at construction. Tools skip / fail clearly when the key is empty. Never commit real credentials; put them in .env only.

3. Runtime infrastructure

Component Purpose How it's consumed
Docker daemon Sandbox for python_exec tool docker SDK (from_env()), docker run <RC_SANDBOX_IMAGE>
Sandbox image RC_SANDBOX_IMAGE (default researchcore-sandbox:latest) Built from Dockerfile.sandbox. Runs untrusted code with CPU/RAM/timeout limits.
SQLite database Evidence store (data/researchcore.db) Via SQLAlchemy async + aiosqlite. Path configured by RC_DATABASE_URL.
artifacts/{run_id}/ Per-run scratchpad files Filesystem; used by notes_read / notes_write tools.
Ollama service When provider=ollama — assumes a local native install or an authenticated remote proxy.
Kroki service Local docker-compose service (kroki_base_url=http://localhost:8000).

Python runtime target: 3.11+ (enforced by requires-python in pyproject.toml). CI and dev currently report 3.14 as well; anything 3.11+ is supported.

4. Issues history (resolved 2026-04-19)

# Issue Resolution
D1 yake imported in src/tools/query_expander.py but not declared. Added yake>=0.4 to pyproject.toml.
D2 PyMuPDF (fitz) used by src/tools/pdf_read.py but not declared. Added pymupdf>=1.24 to pyproject.toml.
D3 trafilatura>=1.12 declared but not imported anywhere. Dropped from pyproject.toml.
D4 freezegun dev-dep declared but not used. Dropped from pyproject.toml.

Open items (informational)

# Topic Note
D5 docker Python SDK pulls many transitive deps just for sandbox + /health/services. Kept as-is (required for python_exec). Consider guarding /health/services with try/except ImportError if the API ever needs to run on a box without Docker.
D6 diagram_gen always needs OpenAI regardless of RC_LLM_PROVIDER. Documented in §2. Either require RC_OPENAI_API_KEY even on Ollama stacks, or add a deterministic Mermaid-code fallback.

5. Summary

  • 13 declared runtime deps, all used.
  • 5 declared dev deps, all used.
  • 6 external HTTP services; credentials default to empty strings and fail-fast at config time.
  • 2 runtime infra components required for full functionality (Docker daemon, SQLite on disk). The rest of the stack degrades gracefully.