inscien 0.2.0__tar.gz

inscien-0.2.0/.gitignore

@@ -0,0 +1,312 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (config lives in the in-app Settings page; no .env is shipped)
+.env*
+*.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+# ...but ours is a hand-written, committed build input the release CI depends on.
+!backend/inscien.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+.venv.local
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation (not used here). NOTE: `site/` is our Astro marketing+docs SOURCE and
+# must be tracked, so this rule is disabled. Astro's build output (site/dist) is ignored by
+# site/.gitignore instead.
+# /site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+
+
+# Database files
+*.sqlite3
+
+# Temporary files
+*.tmp
+
+# Celery (scaffolding only — not run in InScien)
+celerybeat-schedule*
+celerybeat.pid
+
+# InScien-specific
+*.sqlite
+*.sqlite3
+inscien.db
+
+# Durable user data (DB, indexes, narration audio) — host-owned, never tracked.
+# Use `data/*` (not `data/`) so the negation below can re-include the keep file:
+# Git can't re-include a path once its parent directory itself is excluded.
+data/*
+!data/.gitkeep
+
+# throwaway TTS benchmark harness + pre-Kokoro GPU-TTS leftovers
+tts-bench/
+tts/
+
+# empty AI-assistant scratch dirs
+.agents/
+.codex/
+
+# Editor + AI-assistant local files (kept locally, not shipped in the public repo).
+# CLAUDE.md IS tracked: it's project-wide architecture/onboarding docs, useful to any
+# contributor or assistant. AGENTS.md stays local (it encodes this host's workflow rules).
+.vscode/
+AGENTS.md
+
+# Local Zotero test snapshot (never commit — full library metadata + PDFs)
+zotero-sample/
+zotero.sqlite
+zotero.sqlite*
+zotero-storage/
+
+# Generated pdf.js worker (copied from pdfjs-dist on predev/prebuild)
+frontend/public/pdf.worker.min.mjs
+
+# Next.js static export (build artifact — regenerated on every build)
+frontend/out/
+
+# Vendored UI + wheel artifacts for the pip/uvx build (regenerated by `make web` / `make wheel`)
+backend/webui/
+backend/dist/
+
+# Build scratch / stray files
+.build-tmp/
+/docker

inscien-0.2.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: inscien
+Version: 0.2.0
+Summary: A local, private companion over your own Zotero library - citation Map + audio Narrate, served in your browser.
+License: MIT
+Requires-Python: <3.13,>=3.12
+Requires-Dist: annotated-doc==0.0.4
+Requires-Dist: annotated-types==0.7.0
+Requires-Dist: anyio==4.13.0
+Requires-Dist: audioop-lts; python_version >= '3.13'
+Requires-Dist: certifi==2026.2.25
+Requires-Dist: cffi==2.0.0
+Requires-Dist: charset-normalizer==3.4.7
+Requires-Dist: click==8.3.2
+Requires-Dist: cryptography==46.0.7
+Requires-Dist: distro==1.9.0
+Requires-Dist: fastapi==0.135.3
+Requires-Dist: filelock==3.29.0
+Requires-Dist: flatbuffers==25.12.19
+Requires-Dist: fsspec==2026.4.0
+Requires-Dist: greenlet==3.4.0
+Requires-Dist: grpcio==1.80.0
+Requires-Dist: h11==0.16.0
+Requires-Dist: h2==4.3.0
+Requires-Dist: hf-xet==1.5.0
+Requires-Dist: hpack==4.1.0
+Requires-Dist: httpcore==1.0.9
+Requires-Dist: httpx==0.28.1
+Requires-Dist: huggingface-hub==1.15.0
+Requires-Dist: hyperframe==6.1.0
+Requires-Dist: idna==3.11
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: jiter==0.14.0
+Requires-Dist: kokoro-onnx>=0.5
+Requires-Dist: mmh3==5.2.1
+Requires-Dist: numpy==2.4.4
+Requires-Dist: onnxruntime==1.26.0
+Requires-Dist: openai==2.37.0
+Requires-Dist: packaging==26.1
+Requires-Dist: pillow==12.2.0
+Requires-Dist: platformdirs>=4
+Requires-Dist: portalocker==3.2.0
+Requires-Dist: protobuf==7.34.1
+Requires-Dist: py-rust-stemmers==0.1.5
+Requires-Dist: pycparser==3.0
+Requires-Dist: pydantic-core==2.46.0
+Requires-Dist: pydantic==2.13.0
+Requires-Dist: pydub>=0.25
+Requires-Dist: pymupdf<2.0,>=1.24
+Requires-Dist: python-dateutil==2.9.0.post0
+Requires-Dist: python-dotenv==1.2.2
+Requires-Dist: python-multipart==0.0.27
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: requests==2.33.1
+Requires-Dist: six==1.17.0
+Requires-Dist: sniffio==1.3.1
+Requires-Dist: sqlalchemy==2.0.49
+Requires-Dist: starlette==1.0.0
+Requires-Dist: tokenizers==0.23.1
+Requires-Dist: tqdm==4.67.3
+Requires-Dist: typing-extensions==4.15.0
+Requires-Dist: typing-inspection==0.4.2
+Requires-Dist: tzdata==2026.1
+Requires-Dist: urllib3==2.6.3
+Requires-Dist: uvicorn==0.44.0

inscien-0.2.0/core/db.py

@@ -0,0 +1,95 @@
+"""
+Database connection and session management.
+
+InScien is single-user and local-first, so the store is a file-based SQLite
+database (no server to run). `DATABASE_URL` overrides the location/backend -
+the compose file sets it to `sqlite:////workspace/data/inscien.db`.
+"""
+
+import logging
+import os
+from sqlalchemy import create_engine, inspect, text
+from sqlalchemy.orm import sessionmaker, scoped_session, declarative_base
+
+from core.paths import data_path
+
+logger = logging.getLogger(__name__)
+
+Base = declarative_base()
+
+
+def _norm(s: str | None) -> str:
+    return "" if s is None else s.strip()
+
+
+def _get_database_url() -> str:
+    # Explicit URL wins; otherwise default to the local-first SQLite store.
+    explicit = _norm(os.getenv("DATABASE_URL"))
+    if explicit:
+        return explicit
+    path = _norm(os.getenv("SQLITE_PATH")) or data_path("inscien.db")
+    return f"sqlite:///{path}"
+
+
+DATABASE_URL = _get_database_url()
+
+if DATABASE_URL.startswith("sqlite"):
+    # SQLite is accessed across FastAPI's threadpool / the streaming generator's
+    # own session, so disable the same-thread check. No pool recycling needed.
+    engine = create_engine(
+        DATABASE_URL,
+        connect_args={"check_same_thread": False},
+        future=True,
+    )
+else:
+    engine = create_engine(
+        DATABASE_URL,
+        pool_pre_ping=True,
+        pool_recycle=3600,
+        future=True,
+    )
+
+SessionLocal = scoped_session(
+    sessionmaker(bind=engine, autocommit=False, autoflush=False)
+)
+
+
+def get_db():
+    """FastAPI dependency - yields a DB session."""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def ensure_app_settings_columns() -> None:
+    """Additively reconcile `app_settings` columns on a pre-existing DB.
+
+    There is no migration framework - `Base.metadata.create_all` builds missing *tables* but
+    never adds missing *columns* to a table that already exists. So a returning user's
+    `app_settings` won't gain `llm_provider` on its own. Add it with an idempotent, guarded
+    `ALTER TABLE ... ADD COLUMN` (SQLite backfills existing rows from the literal DEFAULT). A
+    brand-new DB already has the column via the model, so this is a no-op there; a legacy DB
+    that already carries the column is also a clean no-op.
+    """
+    inspector = inspect(engine)
+    if "app_settings" not in inspector.get_table_names():
+        return  # fresh DB - create_all builds it with the column already present
+
+    existing = {c["name"] for c in inspector.get_columns("app_settings")}
+    additive = {
+        "llm_provider": "ALTER TABLE app_settings ADD COLUMN llm_provider VARCHAR(20) NOT NULL DEFAULT 'local'",
+        "openai_api_key": "ALTER TABLE app_settings ADD COLUMN openai_api_key VARCHAR(200)",
+        "zotero_data_dir": "ALTER TABLE app_settings ADD COLUMN zotero_data_dir VARCHAR(500)",
+    }
+    for column, ddl in additive.items():
+        if column in existing:
+            continue
+        try:
+            with engine.begin() as conn:
+                conn.execute(text(ddl))
+            logger.info("app_settings: added missing column %s", column)
+        except Exception:
+            # A concurrent boot or a legacy duplicate column must never crash startup.
+            logger.warning("app_settings: could not add column %s (may already exist)", column, exc_info=True)

inscien-0.2.0/core/paths.py

@@ -0,0 +1,25 @@
+"""Durable data-dir resolution - one base dir for everything InScien persists.
+
+SQLite, the OpenAlex cache, job records, narration audio, the Zotero snapshot, and the Kokoro
+weights all live under one base directory. For host dev that's the repo-root `data/` folder
+(default below); in the **desktop app** the Tauri shell sets `INSCIEN_DATA_DIR` to the OS per-user
+app-data dir, so a single env var redirects them all. Each individual path still honours its own
+explicit override (e.g. `INSCIEN_VECTORS_PATH`) for back-compat.
+"""
+
+import os
+from pathlib import Path
+
+# Default base = the repo-root `data/` dir (this file is backend/core/paths.py, so parents[2] is
+# the repo root, regardless of cwd). The desktop build overrides this via INSCIEN_DATA_DIR.
+_DEFAULT_DATA_DIR = str(Path(__file__).resolve().parents[2] / "data")
+
+
+def data_dir() -> str:
+    """The base directory for all durable state (`INSCIEN_DATA_DIR`, else the ./data mount)."""
+    return (os.getenv("INSCIEN_DATA_DIR") or "").strip() or _DEFAULT_DATA_DIR
+
+
+def data_path(*parts: str) -> str:
+    """A path under the data dir, e.g. `data_path("pdf-index.json")` -> `<data_dir>/pdf-index.json`."""
+    return str(Path(data_dir(), *parts))

inscien-0.2.0/launcher.py

@@ -0,0 +1,58 @@
+"""pip / uvx entry point - run InScien as a local web app in the user's own browser.
+
+This is the non-desktop launch path: instead of the Tauri window (whose bundled WebKit is fragile
+on new GPUs), the backend serves BOTH the API and the static UI on one loopback port, and we open
+the system browser at it. Same one-process shape as the frozen desktop build (see run_server.py),
+minus the native window.
+
+Installed as the `inscien` console script (see pyproject.toml). Everything is self-contained:
+Kokoro bundles espeak via espeakng-loader, imageio-ffmpeg bundles ffmpeg - no system packages.
+"""
+
+import os
+import socket
+import threading
+import webbrowser
+from pathlib import Path
+
+
+def _pick_port(preferred: int = 8000) -> int:
+    """Use the preferred port if free, else let the OS hand out any open one."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        try:
+            s.bind(("127.0.0.1", preferred))
+            return preferred
+        except OSError:
+            s.bind(("127.0.0.1", 0))
+            return s.getsockname()[1]
+
+
+def main() -> None:
+    here = Path(__file__).resolve().parent
+
+    # Production mode: relative API base (no CORS), and serve the vendored static UI.
+    os.environ.setdefault("ENV_NAME", "production")
+    os.environ.setdefault("FRONTEND_DIST", str(here / "webui"))
+
+    # Durable state goes in the OS per-user app-data dir, not the install location.
+    if not (os.getenv("INSCIEN_DATA_DIR") or "").strip():
+        from platformdirs import user_data_dir
+
+        os.environ["INSCIEN_DATA_DIR"] = user_data_dir("inscien")
+    os.makedirs(os.environ["INSCIEN_DATA_DIR"], exist_ok=True)
+
+    port = int((os.getenv("PORT") or "").strip() or _pick_port())
+    url = f"http://127.0.0.1:{port}"
+
+    import uvicorn
+
+    from main import app  # main.py builds the app on import (routers + static mount)
+
+    # Open the browser shortly after uvicorn starts serving.
+    threading.Timer(1.2, lambda: webbrowser.open(url)).start()
+    print(f"InScien running at {url}  (press Ctrl+C to stop)")
+    uvicorn.run(app, host="127.0.0.1", port=port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

inscien-0.2.0/main.py

@@ -0,0 +1,139 @@
+import sys
+
+from dotenv import load_dotenv
+
+# In a frozen desktop build all config comes from the parent (Tauri) environment - don't pick up a
+# stray `.env` from the working directory.
+if not getattr(sys, "frozen", False):
+    load_dotenv()
+
+import logging
+
+# Ensure app logs (tracebacks from services) reach the console. basicConfig is a no-op
+# if the root logger already has handlers, so it won't fight uvicorn/gunicorn config.
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+)
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from core.db import engine, Base, ensure_app_settings_columns
+from routers.settings import router as settings_router
+from routers.papers import router as papers_router
+from routers.graph import router as graph_router
+from routers.narrate import router as narrate_router
+from routers.zotero import router as zotero_router
+import os
+
+ENV_NAME = os.getenv("ENV_NAME", "development")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    Base.metadata.create_all(bind=engine)
+    # No migration framework: additively add columns that create_all can't add to an
+    # already-existing table (e.g. llm_provider on a returning user's app_settings).
+    ensure_app_settings_columns()
+    # In-process jobs don't survive a restart - fail any that were mid-run.
+    from services.narration.jobs import recover_stale as recover_narration
+    from services.narration.model import recover_stale as recover_narrate_model
+    from services.refs.fetch_jobs import recover_stale as recover_graph_fetch
+    recover_narration()
+    recover_narrate_model()
+    recover_graph_fetch()
+    yield
+
+
+if ENV_NAME == "production":
+    app = FastAPI(
+        title="InScien Backend API",
+        version="0.1.6",
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+        lifespan=lifespan,
+    )
+else:
+    app = FastAPI(
+        title="InScien Backend API",
+        version="0.1.6",
+        lifespan=lifespan,
+    )
+
+# Dev runs the Next dev server and the API on separate localhost origins, so CORS is needed.
+# Default to localhost (zero-config host dev); `CORS_ORIGINS` overrides. Prod/desktop serve the
+# UI same-origin, so the list is never consulted there - and localhost-only is safe to ship.
+_DEV_ORIGINS = ["http://localhost:3000", "http://127.0.0.1:3000"]
+_configured = [o.strip() for o in (os.getenv("CORS_ORIGINS") or "").split(",") if o.strip()]
+ALLOWED_ORIGINS = _configured or _DEV_ORIGINS
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(settings_router)
+app.include_router(papers_router)
+app.include_router(graph_router)
+app.include_router(narrate_router)
+app.include_router(zotero_router)
+
+
+@app.get("/health")
+async def health():
+    # Liveness only - fast and dependency-free, so the compose healthcheck reflects "the API
+    # process is serving" and never flaps on a host Ollama being down. See /health/ready.
+    return {"status": "ok"}
+
+
+@app.get("/health/ready")
+def health_ready():
+    """Readiness/diagnostics: probe each dependency without ever failing the request. Ollama
+    is informational (it lives on the host and may legitimately be down); readiness needs only
+    the API's own store (SQLite)."""
+    from sqlalchemy import text
+    from core.db import SessionLocal
+    from services.llm.client import list_ollama_models_status
+
+    db_ok = False
+    try:
+        session = SessionLocal()
+        try:
+            session.execute(text("SELECT 1"))
+            db_ok = True
+        finally:
+            session.close()
+    except Exception:
+        logging.getLogger("health").exception("readiness: DB probe failed")
+
+    try:
+        ollama_ok = bool(list_ollama_models_status().get("reachable"))
+    except Exception:
+        ollama_ok = False
+
+    return {"db": db_ok, "ollama": ollama_ok, "ready": db_ok}
+
+
+# Serve the built frontend (Next static export) when present. The production image bakes the
+# export into FRONTEND_DIST and serves it here, so the UI and API share one origin - no CORS,
+# no separate Next server. Mounted LAST so the /api routers and /health above take precedence;
+# html=True resolves /map -> /map/index.html. In development FRONTEND_DIST is unset (the Next
+# dev server serves the UI on its own port), so this is a no-op.
+FRONTEND_DIST = os.getenv("FRONTEND_DIST")
+if FRONTEND_DIST and os.path.isdir(FRONTEND_DIST):
+    import mimetypes
+    from fastapi.staticfiles import StaticFiles
+
+    # The pdf.js worker is an ES module (.mjs); browsers refuse to load a module worker
+    # unless it's served with a JavaScript MIME type, and Python's mimetypes doesn't always
+    # register .mjs. Set it before mounting so StaticFiles guesses the right type.
+    mimetypes.add_type("text/javascript", ".mjs")
+
+    app.mount("/", StaticFiles(directory=FRONTEND_DIST, html=True), name="frontend")