newsscore 0.1.0__py3-none-any.whl

newsscore/__init__.py

@@ -0,0 +1,42 @@
+"""newsscore: news sentiment scoring for stocks with a pluggable scorer.
+
+    from newsscore import NewsScorer
+
+    scorer = NewsScorer()                 # Jev if TYPESAFE_API_KEY is set, else keyword scorer
+    scorer.source_add("yahoo")            # keyless RSS, good for a first try
+    print(scorer.score("AAPL").score)
+
+See ``newsscore.scoring.protocol`` for how to plug in your own scoring function.
+"""
+
+from ._version import __version__
+from .aggregate import Aggregate, AggregateFn, aggregate, make_aggregator
+from .cache import ScoreCache
+from .config import load_env
+from .models import Article, ArticleScore, ScoredArticle, ScoreResult
+from .scorer import NewsScorer
+from .scoring import JevScorer, KeywordScorer, ScoreFn, per_article
+from .sources import SOURCE_TYPES, NewsSource, SourceError, register
+
+__all__ = [
+    "__version__",
+    "NewsScorer",
+    "Article",
+    "ArticleScore",
+    "ScoredArticle",
+    "ScoreResult",
+    "ScoreFn",
+    "per_article",
+    "JevScorer",
+    "KeywordScorer",
+    "NewsSource",
+    "SourceError",
+    "SOURCE_TYPES",
+    "register",
+    "Aggregate",
+    "AggregateFn",
+    "aggregate",
+    "make_aggregator",
+    "ScoreCache",
+    "load_env",
+]

newsscore/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

newsscore/aggregate.py

@@ -0,0 +1,78 @@
+"""Turn many per-article scores into one number.
+
+The default scheme is deliberately simple and fully described here so it can be
+reasoned about, back-tested and replaced:
+
+    weight_i   = confidence_i * relevance_i * 0.5 ** (age_hours_i / half_life_hours)
+    score      = sum(weight_i * score_i) / sum(weight_i)
+    confidence = 1 - exp(-sum(weight_i) / saturation)
+
+Older articles count less (exponential decay), unsure or off-topic articles count
+less (their weights), and confidence grows with the amount of weighted evidence
+but never exceeds 1. With ``saturation=3`` three fully-weighted fresh articles
+give confidence ~0.63; ten give ~0.96.
+
+Plug in your own with ``NewsScorer(aggregate_fn=...)``; it receives the scored
+articles and the reference time and must return an :class:`Aggregate`.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime
+from functools import partial
+from typing import Callable, Sequence
+
+from .models import ScoredArticle
+
+
+@dataclass(frozen=True, slots=True)
+class Aggregate:
+    score: float
+    confidence: float
+    by_source: dict[str, float] = field(default_factory=dict)
+
+
+AggregateFn = Callable[[Sequence[ScoredArticle], datetime], Aggregate]
+
+
+def aggregate(
+    scored: Sequence[ScoredArticle],
+    now: datetime,
+    *,
+    half_life_hours: float = 48.0,
+    saturation: float = 3.0,
+) -> Aggregate:
+    """Confidence- and relevance-weighted mean with exponential time decay."""
+    if not scored:
+        return Aggregate(score=0.0, confidence=0.0)
+
+    total_w = 0.0
+    total_ws = 0.0
+    per_source_w: dict[str, float] = defaultdict(float)
+    per_source_ws: dict[str, float] = defaultdict(float)
+
+    for item in scored:
+        age_hours = max(0.0, (now - item.article.published).total_seconds() / 3600.0)
+        decay = 0.5 ** (age_hours / half_life_hours) if half_life_hours > 0 else 1.0
+        w = item.score.weight * decay
+        if w <= 0.0:
+            continue
+        total_w += w
+        total_ws += w * item.score.score
+        per_source_w[item.article.source] += w
+        per_source_ws[item.article.source] += w * item.score.score
+
+    if total_w == 0.0:
+        return Aggregate(score=0.0, confidence=0.0)
+
+    by_source = {name: per_source_ws[name] / per_source_w[name] for name in per_source_w}
+    confidence = 1.0 - math.exp(-total_w / saturation) if saturation > 0 else 1.0
+    return Aggregate(score=total_ws / total_w, confidence=confidence, by_source=by_source)
+
+
+def make_aggregator(half_life_hours: float = 48.0, saturation: float = 3.0) -> AggregateFn:
+    """Bind parameters so the result matches the :data:`AggregateFn` signature."""
+    return partial(aggregate, half_life_hours=half_life_hours, saturation=saturation)

newsscore/cache.py

@@ -0,0 +1,99 @@
+"""SQLite cache of per-article scores.
+
+Scoring is the expensive step (Jev calls cost money, user models cost time), so
+every :class:`~newsscore.ArticleScore` is stored under
+``(scorer_name, query, article_id)``. Re-running a query only scores articles that
+have not been seen before, and back-tests can replay from the cache for free.
+
+The cache is synchronous on purpose: SQLite calls here take microseconds and a
+threadpool hop would cost more than it saves.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Iterable, Mapping
+
+from platformdirs import user_cache_dir
+
+from .models import ArticleScore
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS scores (
+    scorer     TEXT NOT NULL,
+    query      TEXT NOT NULL,
+    article_id TEXT NOT NULL,
+    payload    TEXT NOT NULL,
+    created    REAL NOT NULL,
+    PRIMARY KEY (scorer, query, article_id)
+)
+"""
+
+
+def default_cache_path() -> Path:
+    override = os.environ.get("NEWSSCORE_CACHE")
+    if override:
+        return Path(override).expanduser()
+    return Path(user_cache_dir("newsscore")) / "scores.sqlite"
+
+
+class ScoreCache:
+    def __init__(self, path: Path | str | None = None) -> None:
+        self.path = Path(path) if path else default_cache_path()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(self.path, check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute(_SCHEMA)
+        self._conn.commit()
+
+    def get_many(self, scorer: str, query: str, ids: Iterable[str]) -> dict[str, ArticleScore]:
+        ids = list(ids)
+        if not ids:
+            return {}
+        found: dict[str, ArticleScore] = {}
+        # SQLite caps bound parameters; chunk to stay well under the limit.
+        for start in range(0, len(ids), 500):
+            chunk = ids[start : start + 500]
+            marks = ",".join("?" * len(chunk))
+            rows = self._conn.execute(
+                f"SELECT article_id, payload FROM scores WHERE scorer=? AND query=? AND article_id IN ({marks})",
+                (scorer, query, *chunk),
+            )
+            for article_id, payload in rows:
+                found[article_id] = ArticleScore.from_dict(json.loads(payload))
+        return found
+
+    def put_many(self, scorer: str, query: str, items: Mapping[str, ArticleScore]) -> None:
+        if not items:
+            return
+        now = time.time()
+        self._conn.executemany(
+            "INSERT OR REPLACE INTO scores (scorer, query, article_id, payload, created) VALUES (?,?,?,?,?)",
+            [
+                (scorer, query, article_id, json.dumps(score.to_dict(), default=str), now)
+                for article_id, score in items.items()
+            ],
+        )
+        self._conn.commit()
+
+    def clear(self, scorer: str | None = None) -> int:
+        cur = (
+            self._conn.execute("DELETE FROM scores WHERE scorer=?", (scorer,))
+            if scorer
+            else self._conn.execute("DELETE FROM scores")
+        )
+        self._conn.commit()
+        return cur.rowcount
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self) -> "ScoreCache":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

newsscore/cli.py

@@ -0,0 +1,312 @@
+"""``newsscore`` command line.
+
+    newsscore source add finnhub --api-key KEY
+    newsscore source add yahoo
+    newsscore source list
+    newsscore score AAPL --days 7
+    newsscore score AAPL -s finnhub -s yahoo --json
+    newsscore fetch AAPL --out news.json
+
+Nothing is written unless you ask for it: ``fetch`` and ``score`` print to stdout,
+and ``--out FILE`` saves the same payload as JSON instead. Article *scores* are
+cached in SQLite so a repeated query only pays for new articles, and saved sources
+live in a per-user JSON file. ``newsscore doctor`` prints every path in use; the
+``NEWSSCORE_CACHE``, ``NEWSSCORE_CONFIG`` and ``NEWSSCORE_ENV`` variables move them.
+
+API keys may be placed in a ``.env`` file in the working directory; it is loaded
+on every invocation without overriding real environment variables.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from ._version import __version__
+from .cache import ScoreCache, default_cache_path
+from .config import SourceSpec, SourceStore, config_path, env_candidates, load_env
+from .scorer import NewsScorer
+from .scoring import SCORERS
+from .sources import SOURCE_TYPES, SourceError, make_source
+
+app = typer.Typer(
+    help="News sentiment scoring for stocks. Mainstream news APIs in, one score out.",
+    invoke_without_command=True,
+    add_completion=False,
+)
+source_app = typer.Typer(help="Manage saved news sources.", no_args_is_help=True)
+app.add_typer(source_app, name="source")
+
+SourcesOpt = Annotated[
+    Optional[list[str]],
+    typer.Option("--source", "-s", help="Saved source name; repeat for several. Omit for all."),
+]
+DaysOpt = Annotated[float, typer.Option("--days", "-d", help="Look-back window in days.")]
+JsonOpt = Annotated[bool, typer.Option("--json", help="Machine-readable output.")]
+OutOpt = Annotated[
+    Optional[Path],
+    typer.Option("--out", metavar="FILE", help="Write the result to FILE as JSON instead of printing it."),
+]
+
+
+@app.callback()
+def _main(
+    ctx: typer.Context,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show warnings from sources.")] = False,
+    version: Annotated[bool, typer.Option("--version", help="Print version and exit.", is_eager=True)] = False,
+) -> None:
+    if version:
+        typer.echo(__version__)
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+    logging.basicConfig(level=logging.INFO if verbose else logging.ERROR, format="%(levelname)s %(message)s")
+    load_env()
+
+
+# ---- source management ------------------------------------------------------------
+
+
+@source_app.command("add")
+def source_add(
+    type_: Annotated[str, typer.Argument(metavar="TYPE", help="Source type; see `newsscore source types`.")],
+    name: Annotated[Optional[str], typer.Option("--name", "-n", help="Name to save under (default: the type).")] = None,
+    api_key: Annotated[Optional[str], typer.Option("--api-key", "-k", help="Provider API key.")] = None,
+    option: Annotated[
+        Optional[list[str]], typer.Option("--option", "-o", metavar="KEY=VALUE", help="Provider option; repeatable.")
+    ] = None,
+    replace: Annotated[bool, typer.Option("--replace", help="Overwrite a source with the same name.")] = False,
+) -> None:
+    """Save a news source to the local config."""
+    if type_ not in SOURCE_TYPES:
+        _fail(f"unknown type {type_!r}. Known: {', '.join(sorted(SOURCE_TYPES))}")
+    options = _parse_options(option or [])
+    spec = SourceSpec(type=type_, name=name or type_, api_key=api_key, options=options)
+    try:  # construct once to surface bad options early; a missing key is only a warning
+        make_source(type_, api_key=api_key, name=spec.name, **options)
+    except SourceError as exc:
+        if "API key required" not in str(exc):
+            _fail(str(exc))
+        typer.secho(f"warning: {exc}. Saved anyway; set the env var before use.", fg="yellow", err=True)
+    try:
+        SourceStore().add(spec, replace=replace)
+    except KeyError as exc:
+        _fail(f"{exc.args[0]}; pass --replace to overwrite")
+    typer.echo(f"saved source {spec.name!r} ({type_}) to {config_path()}")
+
+
+@source_app.command("list")
+def source_list() -> None:
+    """Show saved sources."""
+    specs = SourceStore().load()
+    if not specs:
+        typer.echo("no saved sources. Try: newsscore source add yahoo")
+        return
+    rows = [(s.name, s.type, _mask(s.api_key), json.dumps(s.options) if s.options else "") for s in specs.values()]
+    _table(("NAME", "TYPE", "API KEY", "OPTIONS"), rows)
+
+
+@source_app.command("remove")
+def source_remove(name: Annotated[str, typer.Argument(help="Saved source name.")]) -> None:
+    """Delete a saved source."""
+    try:
+        SourceStore().remove(name)
+    except KeyError as exc:
+        _fail(exc.args[0])
+    typer.echo(f"removed {name!r}")
+
+
+@source_app.command("types")
+def source_types() -> None:
+    """List supported source types."""
+    rows = [
+        (t, "no" if not cls.requires_key else "yes", cls.env_key or "", cls.query_kind)
+        for t, cls in sorted(SOURCE_TYPES.items())
+    ]
+    _table(("TYPE", "NEEDS KEY", "ENV VAR", "QUERY"), rows)
+
+
+# ---- fetching and scoring ---------------------------------------------------------
+
+
+@app.command()
+def fetch(
+    query: Annotated[str, typer.Argument(help="Ticker symbol or keyword.")],
+    source: SourcesOpt = None,
+    days: DaysOpt = 7,
+    as_json: JsonOpt = False,
+    out: OutOpt = None,
+) -> None:
+    """List recent articles without scoring them.
+
+    Articles are printed and then forgotten; pass --out FILE to keep them as JSON.
+    """
+    scorer = NewsScorer.from_config(score_fn="keyword", cache=False)
+    articles = _run(scorer, scorer.afetch(query, days=days, sources=source))
+    payload = [a.to_dict() for a in articles]
+    if out:
+        _write_json(out, payload)
+        typer.echo(f"wrote {len(articles)} article(s) to {out}")
+        return
+    if as_json:
+        typer.echo(json.dumps(payload, indent=2))
+        return
+    if not articles:
+        typer.echo("no articles found")
+        return
+    for a in articles:
+        typer.echo(f"{a.published:%Y-%m-%d %H:%M}  [{a.source}]  {a.title}")
+    typer.echo(f"\n{len(articles)} article(s)")
+
+
+@app.command()
+def score(
+    query: Annotated[str, typer.Argument(help="Ticker symbol or keyword.")],
+    source: SourcesOpt = None,
+    days: DaysOpt = 7,
+    scorer_name: Annotated[
+        Optional[str], typer.Option("--scorer", help=f"One of: {', '.join(sorted(SCORERS))}. Default: jev if configured, else keyword.")
+    ] = None,
+    half_life: Annotated[float, typer.Option("--half-life", help="Decay half-life in hours for aggregation.")] = 48.0,
+    no_cache: Annotated[bool, typer.Option("--no-cache", help="Do not read or write the score cache.")] = False,
+    articles: Annotated[int, typer.Option("--articles", "-a", help="Show the N most recent scored articles.")] = 0,
+    as_json: JsonOpt = False,
+    out: OutOpt = None,
+) -> None:
+    """Fetch, score and aggregate news sentiment for QUERY.
+
+    The result is printed; pass --out FILE to keep the full JSON (every scored
+    article included) instead.
+    """
+    if scorer_name and scorer_name not in SCORERS:
+        _fail(f"unknown scorer {scorer_name!r}. Known: {', '.join(sorted(SCORERS))}")
+    scorer = NewsScorer.from_config(score_fn=scorer_name, cache=not no_cache, half_life_hours=half_life)
+    result = _run(scorer, scorer.ascore(query, days=days, sources=source))
+
+    if out:
+        _write_json(out, result.to_dict())
+        typer.echo(f"wrote {result.n_articles} scored article(s) to {out}")
+        return
+    if as_json:
+        typer.echo(json.dumps(result.to_dict(), indent=2, default=str))
+        return
+
+    typer.echo(f"query       {result.query}")
+    typer.echo(f"window      {result.since:%Y-%m-%d} .. {result.until:%Y-%m-%d}  ({days:g} days)")
+    typer.echo(f"scorer      {scorer.scorer_name or type(scorer.score_fn).__name__}")
+    typer.echo(f"articles    {result.n_articles}")
+    typer.echo(f"score       {result.score:+.3f}   (-1 bearish .. +1 bullish)")
+    typer.echo(f"confidence  {result.confidence:.3f}")
+    if result.by_source:
+        typer.echo("by source   " + "  ".join(f"{k}={v:+.2f}" for k, v in sorted(result.by_source.items())))
+    for message in result.errors:
+        typer.secho(f"warning     {message}", fg="yellow", err=True)
+    if articles:
+        typer.echo("")
+        for item in result.articles[:articles]:
+            a, s = item.article, item.score
+            typer.echo(f"{s.score:+.2f} c={s.confidence:.2f} r={s.relevance:.2f}  {a.published:%m-%d %H:%M} [{a.source}] {a.title}")
+
+
+@app.command("config-path")
+def show_config_path() -> None:
+    """Print where saved sources are stored."""
+    typer.echo(str(config_path()))
+
+
+@app.command("cache-clear")
+def cache_clear(
+    scorer_name: Annotated[Optional[str], typer.Option("--scorer", help="Only clear this scorer's entries.")] = None,
+) -> None:
+    """Delete cached article scores."""
+    with ScoreCache() as cache:
+        n = cache.clear(scorer_name)
+    typer.echo(f"removed {n} cached score(s) from {ScoreCache().path}")
+
+
+@app.command()
+def doctor() -> None:
+    """Check what is configured on this machine."""
+    env_file = next((p for p in env_candidates() if p.is_file()), None)
+    typer.echo(f"env file      {env_file or 'none found (looked in ' + ', '.join(str(p) for p in env_candidates()) + ')'}")
+    typer.echo(f"config file   {config_path()}  ({'exists' if config_path().exists() else 'missing'})")
+    cache = default_cache_path()
+    typer.echo(f"score cache   {cache}  ({'exists' if cache.exists() else 'created on first score'})")
+    typer.echo(f"saved sources {', '.join(SourceStore().load()) or 'none'}")
+    missing = []
+    if importlib.util.find_spec("typesafe_sdk") is None:
+        missing.append("typesafe-sdk not installed (pip install 'newsscore[jev]' or uv sync)")
+    if not os.environ.get("TYPESAFE_API_KEY"):
+        missing.append("TYPESAFE_API_KEY not set")
+    typer.echo(f"jev scorer    {'ready' if not missing else 'unavailable: ' + '; '.join(missing)}")
+
+
+# ---- helpers ---------------------------------------------------------------------------
+
+
+def _run(scorer: NewsScorer, coro):  # type: ignore[no-untyped-def]
+    async def go():  # type: ignore[no-untyped-def]
+        try:
+            return await coro
+        finally:
+            await scorer.aclose()
+
+    return asyncio.run(go())
+
+
+def _write_json(path: Path, payload: object) -> None:
+    """Save `payload` as UTF-8 JSON, creating parent directories as needed."""
+    path = path.expanduser()
+    if path.parent != Path(""):
+        path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        path.write_text(json.dumps(payload, indent=2, default=str), encoding="utf-8")
+    except OSError as exc:
+        _fail(f"could not write {path}: {exc}")
+
+
+def _parse_options(items: list[str]) -> dict[str, object]:
+    options: dict[str, object] = {}
+    for item in items:
+        key, sep, value = item.partition("=")
+        if not sep or not key:
+            _fail(f"bad --option {item!r}; expected KEY=VALUE")
+        lowered = value.lower()
+        options[key] = True if lowered == "true" else False if lowered == "false" else _number_or_str(value)
+    return options
+
+
+def _number_or_str(value: str) -> object:
+    try:
+        return int(value)
+    except ValueError:
+        return value
+
+
+def _mask(key: str | None) -> str:
+    if not key:
+        return "(env)"
+    return key if len(key) <= 6 else f"{key[:3]}...{key[-3:]}"
+
+
+def _table(header: tuple[str, ...], rows: list[tuple[str, ...]]) -> None:
+    widths = [max(len(str(r[i])) for r in (header, *rows)) for i in range(len(header))]
+    for row in (header, *rows):
+        typer.echo("  ".join(str(cell).ljust(w) for cell, w in zip(row, widths)).rstrip())
+
+
+def _fail(message: str) -> None:
+    typer.secho(f"error: {message}", fg="red", err=True)
+    raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

newsscore/config.py

@@ -0,0 +1,151 @@
+"""Per-user store of configured news sources.
+
+Location (first match wins):
+    1. ``$NEWSSCORE_CONFIG``
+    2. ``platformdirs.user_config_dir("newsscore")/sources.json``
+       (``%APPDATA%\\newsscore`` on Windows, ``~/.config/newsscore`` on Linux,
+       ``~/Library/Application Support/newsscore`` on macOS)
+
+Shape::
+
+    {
+      "sources": {
+        "finnhub":  {"type": "finnhub", "api_key": "abc", "options": {}},
+        "yahoo":    {"type": "yahoo",   "api_key": null,  "options": {}}
+      }
+    }
+
+``api_key`` may be null; the source then falls back to its environment variable.
+
+API keys can also live in a ``.env`` file (``KEY=VALUE`` lines, ``#`` comments,
+optional quotes). :func:`load_env` is called by the CLI and by
+``NewsScorer.from_config()``; it never overrides variables already set in the
+environment. Lookup: ``$NEWSSCORE_ENV`` alone if set, else ``./.env``, then ``<config dir>/.env``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+
+def env_candidates() -> list[Path]:
+    """Where :func:`load_env` looks. ``NEWSSCORE_ENV``, when set, is the only candidate."""
+    override = os.environ.get("NEWSSCORE_ENV")
+    if override:
+        return [Path(override).expanduser()]
+    return [Path.cwd() / ".env", Path(user_config_dir("newsscore")) / ".env"]
+
+
+def parse_env(text: str) -> dict[str, str]:
+    """Parse ``KEY=VALUE`` lines. Supports ``export KEY=...``, quotes and ``#`` comments."""
+    values: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):]
+        key, _, value = line.partition("=")
+        key, value = key.strip(), value.strip()
+        if not key:
+            continue
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+            value = value[1:-1]
+        elif value.startswith("#"):
+            value = ""  # blank value followed by a comment
+        else:
+            value = value.split(" #", 1)[0].rstrip()
+        values[key] = value
+    return values
+
+
+def load_env(path: Path | str | None = None, *, override: bool = False) -> Path | None:
+    """Load the first ``.env`` found into ``os.environ``. Returns the path used, or ``None``.
+
+    Empty values are skipped so a template with blank keys is harmless. Existing
+    environment variables win unless ``override=True``.
+    """
+    candidates = [Path(path).expanduser()] if path else env_candidates()
+    for candidate in candidates:
+        if not candidate.is_file():
+            continue
+        for key, value in parse_env(candidate.read_text(encoding="utf-8")).items():
+            if value and (override or key not in os.environ):
+                os.environ[key] = value
+        return candidate
+    return None
+
+
+def config_path() -> Path:
+    override = os.environ.get("NEWSSCORE_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    return Path(user_config_dir("newsscore")) / "sources.json"
+
+
+@dataclass(slots=True)
+class SourceSpec:
+    type: str
+    name: str
+    api_key: str | None = None
+    options: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data.pop("name")
+        return data
+
+
+class SourceStore:
+    """Read and write the JSON file. Every method reloads from disk, so the store
+    is always consistent with what other processes wrote."""
+
+    def __init__(self, path: Path | str | None = None) -> None:
+        self.path = Path(path) if path else config_path()
+
+    def load(self) -> dict[str, SourceSpec]:
+        if not self.path.exists():
+            return {}
+        with self.path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh) or {}
+        specs: dict[str, SourceSpec] = {}
+        for name, item in (data.get("sources") or {}).items():
+            specs[name] = SourceSpec(
+                type=item["type"],
+                name=name,
+                api_key=item.get("api_key"),
+                options=dict(item.get("options") or {}),
+            )
+        return specs
+
+    def save(self, specs: dict[str, SourceSpec]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"sources": {name: spec.to_dict() for name, spec in specs.items()}}
+        tmp = self.path.with_suffix(".tmp")
+        with tmp.open("w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2)
+        os.replace(tmp, self.path)
+        try:  # keys live here; tighten permissions where the OS honours them
+            os.chmod(self.path, 0o600)
+        except OSError:
+            pass
+
+    def add(self, spec: SourceSpec, *, replace: bool = False) -> None:
+        specs = self.load()
+        if spec.name in specs and not replace:
+            raise KeyError(f"source {spec.name!r} already exists (use replace)")
+        specs[spec.name] = spec
+        self.save(specs)
+
+    def remove(self, name: str) -> None:
+        specs = self.load()
+        if name not in specs:
+            raise KeyError(f"no source named {name!r}")
+        del specs[name]
+        self.save(specs)