Systole

Systole is a local-first research workflow app:

• Daily digest: fetches arXiv papers, scores relevance, and stores per-day feeds.
• Summary generation: creates daily markdown summaries on demand.
• Knowledge archive: ingests screenshots/links/text into structured paper | software | article | dataset items.

The app is split into a Vue frontend and a FastAPI backend, with JSON/JSONL file storage under data/.

Repository Layout

frontend/                  Vue 3 + TypeScript + Vite
backend/                   FastAPI app + ingest pipeline
  systole/api.py           HTTP API routes
  systole/tasks.py         daily fetch task orchestration
  systole/archive/         ingest/extraction/archive modules
  config.toml.example      backend config template
scripts/run_dev.sh         one-command local dev (backend + frontend)
data/                      runtime files (git-ignored)

Requirements

• Python >= 3.12
• Node.js >= 18
• uv (recommended Python package manager)
• opencode CLI (required for archive ingestion)

Quick Start

1. Clone and enter the repo.

git clone <repo-url> Systole
cd Systole

2. Create backend config.

cp backend/config.toml.example backend/config.toml

Edit backend/config.toml and fill at least:

• [llm.<provider>] credentials (base_url, api_key, model_name)
• [llm_select] provider names for summary, relevance, and vision
• [opencode] binary path and timeout

3. Start everything.

scripts/run_dev.sh

Default dev URLs:

• Frontend: http://127.0.0.1:15173
• Backend: http://127.0.0.1:18080

Optional backend auto-reload:

SYSTOLE_BACKEND_RELOAD=1 scripts/run_dev.sh

Manual Development

Backend:

cd backend
uv venv .venv --python 3.12
uv sync
cp config.toml.example config.toml
uv run python -m systole

Frontend:

cd frontend
npm install
VITE_API_BASE_URL=http://127.0.0.1:18080 npm run dev

Configuration

Systole uses two config layers:

1. Backend runtime config (backend/config.toml)
2. User settings (data/settings.json, managed via /settings API/UI)

backend/config.toml

Loaded by backend/systole/config.py (default path: config.toml in current working directory).

You can override config path:

SYSTOLE_CONFIG=/absolute/path/to/config.toml uv run python -m systole

Key sections:

• [llm.<name>]: provider definitions (OpenAI-compatible /chat/completions)
• [llm_select]: which provider name to use for summary/relevance/vision
• [opencode]: OpenCode executable and timeout
• [ingest]: optional max_concurrency for ingest worker semaphore
• [system]: app-level metadata

OpenCode Requirement

Archive ingestion endpoints call opencode as a subprocess. If opencode is missing or misconfigured, ingestion fails while daily fetch APIs still work.

Main Workflows

Daily Digest

• Trigger fetch for "today" (Beijing time): POST /tasks/daily
• Fetch writes paper records into data/YYYY-MM-DD/*.jsonl
• Relevance is scored during the task (LLM with heuristic fallback on request failures)
• Summary is generated separately (manual trigger)

Daily Summary

• Trigger: POST /daily/{date}/summary/generate
• Check task: GET /daily/{date}/summary/task
• Read summary: GET /daily/{date}/summary

Archive Ingestion

Input sources supported by /archive/ingest/upload:

• Text (plain text, URLs, snippets)
• Image upload (.png, .jpg, .jpeg, .webp)
• Combined image + text context

Processing is async: upload endpoints return quickly with item_id, then status is polled via inbox endpoints.

API Reference

Core

• GET /health
• GET /dates
• GET /settings
• POST /settings
• POST /tasks/daily
• GET /tasks
• GET /tasks/{task_id}
• POST /tasks/{task_id}/cancel (currently returns 410, cancel disabled)
• GET /daily/{date}
• DELETE /daily/{date}/items/{source}/{source_id}
• GET /daily/{date}/summary
• GET /daily/{date}/summary/task
• POST /daily/{date}/summary/generate

Archive Items

• GET /archive/items
• GET /archive/items/{item_id}
• PUT /archive/items/{item_id}
• DELETE /archive/items/{item_id}

Ingest + Inbox

• POST /archive/ingest/upload
• POST /archive/ingest/from-daily
• POST /archive/ingest/batch
• GET /archive/ingest/status
• GET /archive/inbox
• GET /archive/inbox/{item_id}
• GET /archive/inbox/{item_id}/preview (image items only)
• POST /archive/inbox/{item_id}/retry

Batch Ingest

• POST /archive/ingest/batch-upload (browser folder upload flow)
• POST /archive/ingest/batch-folder (server-local folder path)
• GET /archive/ingest/batches
• GET /archive/ingest/batch/{batch_id}
• POST /archive/ingest/batch/{batch_id}/retry-failed

Data Storage

Runtime data is file-based:

data/
  settings.json
  tasks/
    *.json                 # background task states
  YYYY-MM-DD/
    *.jsonl                 # daily source files (arXiv etc.)
    summary.json
  archive/
    items.jsonl             # current archive item store
    papers.jsonl            # legacy fallback read path
    inbox.jsonl
    inbox/
      uploads/              # uploaded files
    batch_jobs/
      *.json                # per-batch status

Troubleshooting

OpenCode not found:

which opencode
opencode --version

If needed, set explicit binary path in backend/config.toml:

[opencode]
bin = "/absolute/path/to/opencode"
timeout = 1800

Backend config not loading:

• Ensure backend/config.toml exists.
• If running from repo root with manual backend commands, set SYSTOLE_CONFIG=backend/config.toml.

Frontend cannot reach backend:

• Set VITE_API_BASE_URL and restart npm run dev.
• Confirm backend is running on 127.0.0.1:18080.

Quality Checks

Frontend:

cd frontend
npm run type-check
npm run build

Backend test files live under backend/tests/ and currently require installing pytest manually.