scientia-core 0.1.1__tar.gz

scientia_core-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scientia Omnibus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scientia_core-0.1.1/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: scientia-core
+Version: 0.1.1
+Summary: Scientia Omnibus -- a knowledge base viewer
+Author-email: MarkLevkovich <levmarkpost@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Scientia-Omnibus/scientia-core
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Other Audience
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: gitpython>=3.1.50
+Requires-Dist: rapidfuzz>=3.14.5
+Requires-Dist: ruff>=0.15.17
+Requires-Dist: textual[syntax]>=8.2.7
+Requires-Dist: typing-extensions>=4.5
+Requires-Dist: xdg<7,>=6
+Dynamic: license-file

scientia_core-0.1.1/README.md

@@ -0,0 +1,52 @@
+# scientia-core
+
+Offline terminal knowledge reader. Download Markdown knowledge packs once, read without internet. Built with [Textual](https://textual.textualize.io/).
+
+Ships under 10 MB. Runs on anything with a terminal — from a $5 Raspberry Pi to a 15-year-old netbook.
+
+---
+
+## Install
+
+```bash
+# via uv (recommended)
+uv tool install scientia-core
+
+# via pip
+pip install scientia-core
+```
+
+Then run:
+
+```bash
+scientia-core
+```
+
+> For keybindings and commands, see **[USAGE.md](USAGE.md)**.
+
+## Features
+
+- **Fully offline** — download once, read anywhere, no network required
+- **Keyboard-driven** — omnibox (`/` or `:`), tab navigation, commands
+- **4 navigation tabs** — Contents, Local Files, Bookmarks, History
+- **Fuzzy search** across all document titles in your knowledge pack
+- **GitHub sync** — pull knowledge base updates with `Ctrl+G`
+- **Dark / light themes** — toggle with `F10`
+
+## Tech
+
+- Python 3.12+, [Textual](https://textual.textualize.io/) TUI framework
+- [rapidfuzz](https://github.com/maxbachmann/RapidFuzz) for fuzzy matching
+- [GitPython](https://github.com/gitpython-developers/GitPython) for sync
+
+## TODO
+
+- [ ] BM25 full-text search across document contents
+- [ ] Auto-update mechanism
+- [ ] Standalone Windows package (`.exe`)
+- [ ] Linux AppImage build
+- [ ] More knowledge pack sources
+
+## License
+
+MIT

scientia_core-0.1.1/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scientia-core"
+version = "0.1.1"
+description = "Scientia Omnibus -- a knowledge base viewer"
+authors = [
+    { name = "MarkLevkovich", email = "levmarkpost@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Other Audience",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows :: Windows 10",
+    "Operating System :: Microsoft :: Windows :: Windows 11",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Documentation"
+]
+
+dependencies = [
+    "gitpython>=3.1.50",
+    "rapidfuzz>=3.14.5",
+    "ruff>=0.15.17",
+    "textual[syntax]>=8.2.7",
+    "typing-extensions>=4.5",
+    "xdg>=6,<7",
+]
+
+[project.urls]
+Homepage = "https://github.com/Scientia-Omnibus/scientia-core"
+
+[project.scripts]
+scientia-core = "src.app.app:run"
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+exclude = [
+    ".git",
+    ".venv",
+    "build",
+    "dist",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

scientia_core-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scientia_core-0.1.1/src/__init__.py

@@ -0,0 +1,4 @@
+__author__ = "Scientia Omnibus"
+__email__ = "levmarkpost@gmail.com"
+__version__ = "0.1.0"
+__licence__ = "MIT"

scientia_core-0.1.1/src/__main__.py

@@ -0,0 +1,4 @@
+from src.app import run
+
+if __name__ == "__main__":
+    run()

scientia_core-0.1.1/src/app/__init__.py

@@ -0,0 +1,3 @@
+from src.app.app import run
+
+__all__ = ["run"]

scientia_core-0.1.1/src/app/app.py

@@ -0,0 +1,21 @@
+from textual.app import App
+
+from src.data import load_config
+from src.screens import Main
+
+
+class ScientiaCore(App[None]):
+    TITLE = "Scientia Omnibus"
+    ENABLE_COMMAND_PALETTE = False
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.dark = not load_config().light_mode
+
+    def on_mount(self) -> None:
+        self.theme = "rose-pine"
+        self.push_screen(Main())
+
+
+def run() -> None:
+    ScientiaCore().run()

scientia_core-0.1.1/src/data/__init__.py

@@ -0,0 +1,16 @@
+"""Provides tools for saving and loading application data."""
+
+from src.data.bookmarks import Bookmark, load_bookmarks, save_bookmarks
+from src.data.config import Config, load_config, save_config
+from src.data.history import load_history, save_history
+
+__all__ = [
+    "Bookmark",
+    "Config",
+    "load_bookmarks",
+    "load_config",
+    "load_history",
+    "save_bookmarks",
+    "save_config",
+    "save_history",
+]

scientia_core-0.1.1/src/data/bookmarks.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from json import JSONEncoder, dumps, loads
+from pathlib import Path
+from typing import Any, NamedTuple
+
+from src.data.data_directory import data_directory
+
+
+class Bookmark(NamedTuple):
+    title: str
+    location: Path
+
+
+def bookmarks_file() -> Path:
+    return data_directory() / "bookmarks.json"
+
+
+class BookmarkEncoder(JSONEncoder):
+    def default(self, o: object) -> Any:
+        return str(o) if isinstance(o, Path) else o
+
+
+def save_bookmarks(bookmarks: list[Bookmark]) -> None:
+    bookmarks_file().write_text(dumps(bookmarks, indent=4, cls=BookmarkEncoder))
+
+
+def load_bookmarks() -> list[Bookmark]:
+    return (
+        [
+            Bookmark(title, Path(location))
+            for (title, location) in loads(bookmarks.read_text())
+        ]
+        if (bookmarks := bookmarks_file()).exists()
+        else []
+    )

scientia_core-0.1.1/src/data/config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from functools import lru_cache
+from json import dumps, loads
+from pathlib import Path
+
+from xdg import xdg_config_home
+
+
+@dataclass
+class Config:
+    light_mode: bool = False
+    """Should we run in light mode?"""
+
+    markdown_extensions: list[str] = field(default_factory=lambda: [".md", ".markdown"])
+    """What Markdown extensions will we look for?"""
+
+    navigation_left: bool = True
+    """Should navigation be docked to the left side of the screen?"""
+
+
+def config_file() -> Path:
+    (config_dir := xdg_config_home() / "scientia-omnibus").mkdir(
+        parents=True, exist_ok=True
+    )
+    return config_dir / "configuration.json"
+
+
+def save_config(config: Config) -> Config:
+    load_config.cache_clear()
+    config_file().write_text(dumps(asdict(config), indent=4))
+    return load_config()
+
+
+@lru_cache(maxsize=None)
+def load_config() -> Config:
+    source_file = config_file()
+    return (
+        Config(**loads(source_file.read_text()))
+        if source_file.exists()
+        else save_config(Config())
+    )

scientia_core-0.1.1/src/data/data_directory.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+from xdg import xdg_data_home
+
+
+def data_directory() -> Path:
+    (target_directory := xdg_data_home() / "scientia-omnibus").mkdir(
+        parents=True, exist_ok=True
+    )
+    return target_directory

scientia_core-0.1.1/src/data/history.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from json import JSONEncoder, dumps, loads
+from pathlib import Path
+from typing import Any
+
+from src.data.data_directory import data_directory
+
+
+def history_file() -> Path:
+    return data_directory() / "history.json"
+
+
+class HistoryEncoder(JSONEncoder):
+    def default(self, o: object) -> Any:
+        return str(o) if isinstance(o, Path) else o
+
+
+def save_history(history: list[Path]) -> None:
+    history_file().write_text(dumps(history, indent=4, cls=HistoryEncoder))
+
+
+def load_history() -> list[Path]:
+    return (
+        [Path(location) for location in loads(history.read_text())]
+        if (history := history_file()).exists()
+        else []
+    )

scientia_core-0.1.1/src/dialogs/__init__.py

@@ -0,0 +1,15 @@
+"""Provides useful dialogs for the application."""
+
+from src.dialogs.error import ErrorDialog
+from src.dialogs.help_dialog import HelpDialog
+from src.dialogs.information import InformationDialog
+from src.dialogs.input_dialog import InputDialog
+from src.dialogs.yes_no_dialog import YesNoDialog
+
+__all__ = [
+    "ErrorDialog",
+    "InformationDialog",
+    "InputDialog",
+    "HelpDialog",
+    "YesNoDialog",
+]

scientia_core-0.1.1/src/dialogs/directory_picker.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual import on
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.screen import ModalScreen
+from textual.widgets import Button, Label, OptionList
+
+from src.data.data_directory import data_directory
+
+
+class DirectoryPicker(ModalScreen[Path]):
+    """A modal dialog for selecting a knowledge directory."""
+
+    DEFAULT_CSS = """
+    DirectoryPicker {
+        align: center middle;
+    }
+
+    DirectoryPicker > Vertical {
+        background: $panel;
+        height: auto;
+        width: auto;
+        border: thick $primary;
+    }
+
+    DirectoryPicker > Vertical > * {
+        width: auto;
+        height: auto;
+    }
+
+    DirectoryPicker Label {
+        margin-left: 2;
+    }
+
+    DirectoryPicker OptionList {
+        width: 40;
+        margin: 1;
+    }
+
+    DirectoryPicker Button {
+        margin-right: 1;
+    }
+
+    DirectoryPicker #buttons {
+        width: 100%;
+        align-horizontal: right;
+        padding-right: 1;
+    }
+    """
+
+    BINDINGS = [
+        Binding("escape", "app.pop_screen", "", show=False),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.paths = [item.name for item in data_directory().iterdir() if item.is_dir()]
+
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            yield Label("Select from existing:")
+            yield OptionList(*self.paths, id="choices")
+            with Horizontal(id="buttons"):
+                yield Button("Cancel", id="cancel")
+                yield Button("OK", id="ok", variant="primary")
+
+    @on(Button.Pressed, "#cancel")
+    def cancel_choice(self) -> None:
+        self.app.pop_screen()
+
+    @on(Button.Pressed, "#ok")
+    def accept_choice(self) -> None:
+        if self.query_one(OptionList).highlighted is not None:
+            self.dismiss(
+                data_directory() / self.paths[self.query_one(OptionList).highlighted]
+            )

scientia_core-0.1.1/src/dialogs/error.py

@@ -0,0 +1,21 @@
+from textual.widgets._button import ButtonVariant
+
+from src.dialogs.text_dialog import TextDialog
+
+
+class ErrorDialog(TextDialog):
+    DEFAULT_CSS = """
+    ErrorDialog > Vertical {
+        background: $error 15%;
+        border: thick $error 50%;
+    }
+
+    ErrorDialog #message {
+        border-top: solid $panel;
+        border-bottom: solid $panel;
+    }
+    """
+
+    @property
+    def button_style(self) -> ButtonVariant:
+        return "error"

scientia_core-0.1.1/src/dialogs/help_dialog.py

@@ -0,0 +1,168 @@
+import webbrowser
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Center, Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Button, Markdown
+from typing_extensions import Final
+
+from src import __version__
+
+HELP: Final[str] = f"""\
+# Scientia Omnibus v{__version__} Help
+
+Scientia Omnibus — a terminal program for viewing your knowledge base.
+
+## Interface
+
+The application consists of three main zones:
+
+- **Omnibox** (top bar) — a command line, like a browser address bar.
+- **Navigation** (sidebar) — four tabs: Contents, Local, Bookmarks, History.
+- **Viewer** (main area) — displays documents.
+
+The sidebar can be hidden/shown (`Ctrl+N`), tabs can be switched,
+or the panel can be moved to the opposite side (`\\`).
+
+## Global Keys
+
+| Key | Action |
+| -- | -- |
+| `/` or `:` | Focus on omnibox (command line) |
+| `Escape` | Return to omnibox / clear omnibox / exit |
+| `Ctrl+G` | Download or update knowledge base repositories |
+| `Ctrl+O` | Change the search directory |
+| `Ctrl+N` | Show/hide navigation sidebar |
+| `Ctrl+B` | Show bookmarks |
+| `Ctrl+L` | Show local files |
+| `Ctrl+T` | Show document table of contents |
+| `Ctrl+Y` | Show history |
+| `Ctrl+Left` | Go back in viewing history |
+| `Ctrl+Right` | Go forward in viewing history |
+| `Ctrl+D` | Add current document to bookmarks |
+| `Ctrl+R` | Reload current document |
+| `Ctrl+Q` | Quit application |
+| `F1` | This help |
+| `F2` | About |
+| `F10` | Toggle dark/light theme |
+
+## Navigation Panel
+
+| Key | Action |
+| -- | -- |
+| `,` / `a` / `h` / `Ctrl+Left` / `Shift+Left` | Previous tab |
+| `.` / `d` / `l` / `Ctrl+Right` / `Shift+Right` | Next tab |
+| `\\` | Move panel left/right |
+
+## Document Viewer
+
+When focus is in the viewer:
+
+| Key | Action |
+| -- | -- |
+| `w` / `k` | Scroll up |
+| `s` / `j` | Scroll down |
+| `Space` | Page down |
+| `b` | Page up |
+
+## Bookmarks
+
+| Key | Action |
+| -- | -- |
+| `Delete` | Delete bookmark |
+| `r` | Rename bookmark |
+
+## History
+
+| Key | Action |
+| -- | -- |
+| `Delete` | Delete history entry |
+| `Backspace` | Clear entire history |
+
+## Search
+
+As you type in the omnibox, fuzzy search automatically scans the knowledge directory
+for matching `.md` files. Results appear in a dropdown list below the omnibox.
+
+- `Down` arrow — move focus to the results list.
+- `Up` arrow (at the top of results) — return focus to the omnibox.
+- `Enter` — open the selected file in the viewer.
+- `Escape` — close the results dropdown.
+
+## Commands
+
+Press `/` or click the omnibox, then type one of the commands:
+
+| Command | Aliases | Description |
+| -- | -- | -- |
+| `about` | `a` | Show application information |
+| `bookmarks` | `b`, `bm` | Show bookmarks list |
+| `contents` | `c`, `toc` | Show document table of contents |
+| `help` | `?` | Show this help |
+| `history` | `h` | Show history |
+| `local` | `l` | Show local files |
+| `quit` | `q` | Quit the program |
+
+## Knowledge Base Sync
+
+`Ctrl+G` opens a dialog to download or update knowledge repositories. Four repositories are available:
+
+- **humanities-sciences**
+- **social-sciences**
+- **natural-sciences**
+- **formal-sciences**
+
+Select a repository and press `OK`. If the repository already exists locally, it will be
+force-synced — any local changes are overwritten with the remote version. If it does not
+exist, it will be cloned from GitHub (`github.com/Scientia-Omnibus`).
+
+After syncing, the file tree navigates to the downloaded repository so you can browse
+its contents immediately.
+"""
+
+
+class HelpDialog(ModalScreen[None]):
+    DEFAULT_CSS = """
+    HelpDialog {
+        align: center middle;
+    }
+
+    HelpDialog > Vertical {
+        border: thick $primary 50%;
+        width: 80%;
+        height: 80%;
+        background: $boost;
+    }
+
+    HelpDialog > Vertical > VerticalScroll {
+        height: 1fr;
+        margin: 1 2;
+    }
+
+    HelpDialog > Vertical > Center {
+        padding: 1;
+        height: auto;
+    }
+    """
+
+    BINDINGS = [
+        Binding("escape,f1", "dismiss(None)", "", show=False),
+    ]
+
+    def compose(self) -> ComposeResult:
+        with Vertical():
+            with VerticalScroll():
+                yield Markdown(HELP)
+            with Center():
+                yield Button("Close", variant="primary")
+
+    def on_mount(self) -> None:
+        self.query_one(Markdown).can_focus_children = False
+        self.query_one("Vertical > VerticalScroll").focus()
+
+    def on_button_pressed(self) -> None:
+        self.dismiss(None)
+
+    def on_markdown_link_clicked(self, event: Markdown.LinkClicked) -> None:
+        webbrowser.open(event.href)

scientia_core-0.1.1/src/dialogs/information.py

@@ -0,0 +1,9 @@
+from src.dialogs.text_dialog import TextDialog
+
+
+class InformationDialog(TextDialog):
+    DEFAULT_CSS = """
+    InformationDialog > Vertical {
+        border: thick $primary 50%;
+    }
+    """