seren-loci 0.1.0__tar.gz

seren_loci-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: seren-loci
+Version: 0.1.0
+Summary: Keyed facts/logic memory for Seren. The left brain - addressable, deterministic, one live value per key.
+Author: Chad Roesler
+License: GPL-3.0-or-later
+Keywords: llm,memory,facts,logic,sqlite,sqlite-vec,seren
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: vector
+Requires-Dist: sqlite-vec>=0.1.6; extra == "vector"
+Requires-Dist: sentence-transformers>=3.0; extra == "vector"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: corp
+Requires-Dist: truststore>=0.9; extra == "corp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx2>=2.3; extra == "dev"
+
+# SerenLoci
+
+**The left brain.** A keyed facts-and-logic store for the Seren constellation —
+addressable, deterministic, exactly one live value per key.
+
+Where [SerenMemory](https://github.com/ChadRoesler/SerenMemory) (the right
+brain) holds fuzzy, episodic memory — *"we ground on the embedder migration for
+a week, it was a slog"* — Loci holds **facts**:
+
+```
+{ project, key, value, why }
+```
+
+`camelCase is life`. `braces on a new line in posh`. `GGML_CUDA_NO_VMM=ON must
+be set at compile time` — *because the env var isn't honored at runtime on
+Jetson*. A locus has an **address**. You go *to* it and get *the* thing — you
+don't grope around for something that rhymes.
+
+---
+
+## Why it's shaped like this
+
+**One live value per key, enforced by the database.** Set a new value for a key
+and the old one is *superseded* — kept as history, pointed at by the new row,
+**never blended**. A vibed-together fact is worse than no fact, so the rule is
+strict, and it's not enforced by hope: a `PARTIAL UNIQUE INDEX` makes sqlite
+physically refuse a second live row per `(project, key)`.
+
+**Two tiers.** A reserved project of `*` is the *fundamentals* tier —
+cross-project truths. A concrete project name (`seren-memory`) is the
+per-project tier — the targeted override. Same split as nano/xavier/dgx
+prebuilts: the platform-wide truth and the per-board variant.
+
+**The `why` is the point.** A logic store without rationale is just a
+dictionary. The value tells you *what*; the why is what stops you re-learning it
+the painful way — and it's searchable, so "that CUDA thing" finds a fact whose
+*reason* mentions CUDA even when the key doesn't.
+
+---
+
+## The floor is free
+
+Three access rungs, cheapest first:
+
+1. **Exact** — `get_fact(project, key)` returns the live value, deterministically.
+   No embedding, no ranking. You know the address, you get the thing.
+2. **Lexical** — FTS5 full-text over `(key, value, why)` of the live rows. The
+   "I sort of remember the words" path.
+3. **Vector** *(additive)* — a [sqlite-vec](https://github.com/asg017/sqlite-vec)
+   index for the "this smells like that CUDA thing" associative jump. Built
+   **only** when you name an embedder.
+
+Rungs 1 and 2 need nothing but sqlite (stdlib) and the web stack — **no torch,
+no GPU, the 4GB-laptop floor**. The vector finder is the ceiling, opted into by
+install, never required. *Where does it sit? How much does it need?* — the floor
+needs almost nothing.
+
+---
+
+## Install
+
+```bash
+pip install seren-loci                 # the floor: exact + FTS5 lexical
+pip install seren-loci[vector]         # + the sqlite-vec associative finder (pulls torch)
+pip install seren-loci[mcp]            # + the MCP surface (model reaches facts directly)
+pip install seren-loci[corp]           # + OS-trust-store TLS for corp-proxied boxes
+```
+
+Extras stack: `pip install seren-loci[vector,mcp]`.
+
+## Run
+
+```bash
+seren-loci                             # or: python -m seren_loci
+seren-loci --config ./seren-loci.yaml
+```
+
+Listens on **7422** by default (neighbor convention: memory 7420, margin 7421,
+loci 7422).
+
+```bash
+# set a fundamental truth
+curl -X POST localhost:7422/fact -H 'content-type: application/json' \
+  -d '{"key":"posh.brace_style","value":"curly brackets on a new line","why":"readability"}'
+
+# get it back, deterministically
+curl 'localhost:7422/fact?key=posh.brace_style'
+
+# discovery search (exact-key first, then the finder)
+curl -X POST localhost:7422/search -H 'content-type: application/json' \
+  -d '{"query":"cuda runtime"}'
+```
+
+---
+
+## API
+
+| Method | Path             | What                                                   |
+|--------|------------------|--------------------------------------------------------|
+| POST   | `/fact`          | Set/replace a fact (strict supersede). Names the superseded id, or null. |
+| GET    | `/fact`          | The live value for `?project=&key=` (project defaults to `*`). 404 if none. |
+| GET    | `/fact/history`  | Every value a key has held, newest first.              |
+| DELETE | `/fact`          | Retire (soft-supersede) the live value for a key.      |
+| GET    | `/facts`         | List facts in scope (`?project=&include_superseded=`). |
+| GET    | `/counts`        | `{live, history, projects}`.                           |
+| POST   | `/search`        | Exact + finder discovery, ranked.                      |
+| GET    | `/` `/health`    | Service info / liveness.                               |
+
+Every search hit carries a normalized **0–1 score** (`exact`→1.0,
+`vector`→`1/(1+distance)`, `lexical`→bm25 mapped above 0). That's the common
+currency a future **SerenCorpusCallosum** uses to merge left-brain and
+right-brain results on one axis instead of comparing cosines to key-hits.
+
+---
+
+## Config
+
+`seren-loci.yaml` (all optional — defaults are a working zero-config dev setup).
+Env vars (`SEREN_LOCI_*`) override the file.
+
+```yaml
+server:
+  host: 0.0.0.0
+  port: 7422
+  bearer_token: ""        # empty = no auth (trusted LAN)
+storage:
+  db_path: ~/.seren-loci/loci.db
+  embedding_model:        # null = floor (no torch). name one to light the vector finder.
+  embedding_device: cpu
+tls:
+  trust_system_store: false   # true (+ [corp]) for TLS-intercepting corp proxies
+```
+
+---
+
+## Where it sits in the constellation
+
+- **SerenMemory** — the right brain. Fuzzy, consolidated, episodic. General-purpose AI memory protocol.
+- **SerenLoci** — *this*. The left brain. Keyed facts, deterministic, strict-supersede.
+- **SerenMargin** — opinionated private notes, opt-in by deploy.
+- **SerenCorpusCallosum** *(planned)* — fans a query across both hemispheres and merges on the shared score currency.
+
+Build for the floor, not the ceiling. The Nano is the floor, not the cap. GPL-3.0-or-later. Rip it and win. 🌭🔧

seren_loci-0.1.0/README.md

@@ -0,0 +1,143 @@
+# SerenLoci
+
+**The left brain.** A keyed facts-and-logic store for the Seren constellation —
+addressable, deterministic, exactly one live value per key.
+
+Where [SerenMemory](https://github.com/ChadRoesler/SerenMemory) (the right
+brain) holds fuzzy, episodic memory — *"we ground on the embedder migration for
+a week, it was a slog"* — Loci holds **facts**:
+
+```
+{ project, key, value, why }
+```
+
+`camelCase is life`. `braces on a new line in posh`. `GGML_CUDA_NO_VMM=ON must
+be set at compile time` — *because the env var isn't honored at runtime on
+Jetson*. A locus has an **address**. You go *to* it and get *the* thing — you
+don't grope around for something that rhymes.
+
+---
+
+## Why it's shaped like this
+
+**One live value per key, enforced by the database.** Set a new value for a key
+and the old one is *superseded* — kept as history, pointed at by the new row,
+**never blended**. A vibed-together fact is worse than no fact, so the rule is
+strict, and it's not enforced by hope: a `PARTIAL UNIQUE INDEX` makes sqlite
+physically refuse a second live row per `(project, key)`.
+
+**Two tiers.** A reserved project of `*` is the *fundamentals* tier —
+cross-project truths. A concrete project name (`seren-memory`) is the
+per-project tier — the targeted override. Same split as nano/xavier/dgx
+prebuilts: the platform-wide truth and the per-board variant.
+
+**The `why` is the point.** A logic store without rationale is just a
+dictionary. The value tells you *what*; the why is what stops you re-learning it
+the painful way — and it's searchable, so "that CUDA thing" finds a fact whose
+*reason* mentions CUDA even when the key doesn't.
+
+---
+
+## The floor is free
+
+Three access rungs, cheapest first:
+
+1. **Exact** — `get_fact(project, key)` returns the live value, deterministically.
+   No embedding, no ranking. You know the address, you get the thing.
+2. **Lexical** — FTS5 full-text over `(key, value, why)` of the live rows. The
+   "I sort of remember the words" path.
+3. **Vector** *(additive)* — a [sqlite-vec](https://github.com/asg017/sqlite-vec)
+   index for the "this smells like that CUDA thing" associative jump. Built
+   **only** when you name an embedder.
+
+Rungs 1 and 2 need nothing but sqlite (stdlib) and the web stack — **no torch,
+no GPU, the 4GB-laptop floor**. The vector finder is the ceiling, opted into by
+install, never required. *Where does it sit? How much does it need?* — the floor
+needs almost nothing.
+
+---
+
+## Install
+
+```bash
+pip install seren-loci                 # the floor: exact + FTS5 lexical
+pip install seren-loci[vector]         # + the sqlite-vec associative finder (pulls torch)
+pip install seren-loci[mcp]            # + the MCP surface (model reaches facts directly)
+pip install seren-loci[corp]           # + OS-trust-store TLS for corp-proxied boxes
+```
+
+Extras stack: `pip install seren-loci[vector,mcp]`.
+
+## Run
+
+```bash
+seren-loci                             # or: python -m seren_loci
+seren-loci --config ./seren-loci.yaml
+```
+
+Listens on **7422** by default (neighbor convention: memory 7420, margin 7421,
+loci 7422).
+
+```bash
+# set a fundamental truth
+curl -X POST localhost:7422/fact -H 'content-type: application/json' \
+  -d '{"key":"posh.brace_style","value":"curly brackets on a new line","why":"readability"}'
+
+# get it back, deterministically
+curl 'localhost:7422/fact?key=posh.brace_style'
+
+# discovery search (exact-key first, then the finder)
+curl -X POST localhost:7422/search -H 'content-type: application/json' \
+  -d '{"query":"cuda runtime"}'
+```
+
+---
+
+## API
+
+| Method | Path             | What                                                   |
+|--------|------------------|--------------------------------------------------------|
+| POST   | `/fact`          | Set/replace a fact (strict supersede). Names the superseded id, or null. |
+| GET    | `/fact`          | The live value for `?project=&key=` (project defaults to `*`). 404 if none. |
+| GET    | `/fact/history`  | Every value a key has held, newest first.              |
+| DELETE | `/fact`          | Retire (soft-supersede) the live value for a key.      |
+| GET    | `/facts`         | List facts in scope (`?project=&include_superseded=`). |
+| GET    | `/counts`        | `{live, history, projects}`.                           |
+| POST   | `/search`        | Exact + finder discovery, ranked.                      |
+| GET    | `/` `/health`    | Service info / liveness.                               |
+
+Every search hit carries a normalized **0–1 score** (`exact`→1.0,
+`vector`→`1/(1+distance)`, `lexical`→bm25 mapped above 0). That's the common
+currency a future **SerenCorpusCallosum** uses to merge left-brain and
+right-brain results on one axis instead of comparing cosines to key-hits.
+
+---
+
+## Config
+
+`seren-loci.yaml` (all optional — defaults are a working zero-config dev setup).
+Env vars (`SEREN_LOCI_*`) override the file.
+
+```yaml
+server:
+  host: 0.0.0.0
+  port: 7422
+  bearer_token: ""        # empty = no auth (trusted LAN)
+storage:
+  db_path: ~/.seren-loci/loci.db
+  embedding_model:        # null = floor (no torch). name one to light the vector finder.
+  embedding_device: cpu
+tls:
+  trust_system_store: false   # true (+ [corp]) for TLS-intercepting corp proxies
+```
+
+---
+
+## Where it sits in the constellation
+
+- **SerenMemory** — the right brain. Fuzzy, consolidated, episodic. General-purpose AI memory protocol.
+- **SerenLoci** — *this*. The left brain. Keyed facts, deterministic, strict-supersede.
+- **SerenMargin** — opinionated private notes, opt-in by deploy.
+- **SerenCorpusCallosum** *(planned)* — fans a query across both hemispheres and merges on the shared score currency.
+
+Build for the floor, not the ceiling. The Nano is the floor, not the cap. GPL-3.0-or-later. Rip it and win. 🌭🔧

seren_loci-0.1.0/SerenLoci.pyproj

@@ -0,0 +1,82 @@
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <SchemaVersion>2.0</SchemaVersion>
+    <ProjectGuid>e5ad2b2f-4465-4a6d-b491-02c5819d2234</ProjectGuid>
+    <ProjectHome>.</ProjectHome>
+    <StartupFile>
+    </StartupFile>
+    <SearchPath>
+    </SearchPath>
+    <WorkingDirectory>.</WorkingDirectory>
+    <OutputPath>.</OutputPath>
+    <Name>SerenLoci</Name>
+    <RootNamespace>SerenLoci</RootNamespace>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <DebugSymbols>true</DebugSymbols>
+    <EnableUnmanagedDebugging>false</EnableUnmanagedDebugging>
+  </PropertyGroup>
+  <ItemGroup>
+    <Folder Include="seren_loci\" />
+    <Folder Include="seren_loci\mcp\" />
+    <Folder Include="seren_loci\models\" />
+    <Folder Include="seren_loci\routes\" />
+    <Folder Include="seren_loci\tests\" />
+    <Folder Include="seren_loci\tests\__pycache__\" />
+    <Folder Include="seren_loci\viewer\" />
+    <Folder Include="tests\" />
+    <Folder Include="tests\__pycache__\" />
+  </ItemGroup>
+  <ItemGroup>
+    <Compile Include="seren_loci\app.py" />
+    <Compile Include="seren_loci\config.py" />
+    <Compile Include="seren_loci\mcp\server.py" />
+    <Compile Include="seren_loci\mcp\tools.py" />
+    <Compile Include="seren_loci\mcp\__init__.py" />
+    <Compile Include="seren_loci\models\schemas.py" />
+    <Compile Include="seren_loci\models\__init__.py" />
+    <Compile Include="seren_loci\routes\fact.py" />
+    <Compile Include="seren_loci\routes\facts.py" />
+    <Compile Include="seren_loci\routes\search.py" />
+    <Compile Include="seren_loci\routes\__init__.py" />
+    <Compile Include="seren_loci\store.py" />
+    <Compile Include="seren_loci\tests\conftest.py" />
+    <Compile Include="seren_loci\tests\test_embedder_reconcile.py" />
+    <Compile Include="seren_loci\tests\test_mcp_mount.py" />
+    <Compile Include="seren_loci\tests\test_mcp_tools.py" />
+    <Compile Include="seren_loci\tests\test_routes.py" />
+    <Compile Include="seren_loci\tests\test_store.py" />
+    <Compile Include="seren_loci\tests\test_vector_sql.py" />
+    <Compile Include="seren_loci\__init__.py" />
+    <Compile Include="seren_loci\__main__.py" />
+    <Compile Include="tests\conftest.py" />
+    <Compile Include="tests\test_embedder_reconcile.py" />
+    <Compile Include="tests\test_mcp_mount.py" />
+    <Compile Include="tests\test_mcp_tools.py" />
+    <Compile Include="tests\test_routes.py" />
+    <Compile Include="tests\test_store.py" />
+    <Compile Include="tests\test_vector_sql.py" />
+  </ItemGroup>
+  <ItemGroup>
+    <Content Include="pyproject.toml" />
+    <Content Include="seren-loci.service.sample" />
+    <Content Include="seren-loci.yaml.sample" />
+    <Content Include="seren_loci\tests\__pycache__\conftest.cpython-311-pytest-9.0.3.pyc" />
+    <Content Include="seren_loci\viewer\loci.html" />
+    <Content Include="tests\__pycache__\conftest.cpython-311-pytest-9.0.3.pyc" />
+  </ItemGroup>
+  <Import Project="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v$(VisualStudioVersion)\Python Tools\Microsoft.PythonTools.targets" />
+  <!-- Uncomment the CoreCompile target to enable the Build command in
+       Visual Studio and specify your pre- and post-build commands in
+       the BeforeBuild and AfterBuild targets below. -->
+  <!--<Target Name="CoreCompile" />-->
+  <Target Name="BeforeBuild">
+  </Target>
+  <Target Name="AfterBuild">
+  </Target>
+</Project>

seren_loci-0.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seren-loci"
+dynamic = ["version"]
+description = "Keyed facts/logic memory for Seren. The left brain - addressable, deterministic, one live value per key."
+readme = "README.md"
+# Upper bound mirrors SerenMemory, but the REASON differs: Loci's floor (exact
+# + FTS5) is pure sqlite + the web stack and would run fine anywhere. The cap
+# exists for the OPTIONAL [vector] extra - sentence-transformers pulls torch,
+# and torch's 3.13 wheel gap is the wall. Capping here keeps `pip install
+# seren-loci[vector]` resolving cleanly instead of exploding on a torch build.
+# LIFT THE <3.13 the day torch ships 3.13 wheels (bump the CI matrix to match
+# in the same commit).
+requires-python = ">=3.10,<3.13"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "Chad Roesler" }]
+keywords = ["llm", "memory", "facts", "logic", "sqlite", "sqlite-vec", "seren"]
+
+# THE FLOOR IS DEP-LIGHT ON PURPOSE. Exact-key + FTS5 lexical search need
+# nothing but sqlite (stdlib) and the web stack. The associative vector finder
+# - sqlite-vec + sentence-transformers - is the [vector] extra below, so the
+# Nano / 4GB-laptop floor never pulls torch unless an operator opts into the
+# "this smells like that CUDA thing" jump. Structural opt-in: capability by
+# install choice, not a runtime flag.
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "pydantic>=2.9.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+vector = [
+    # The associative finder. sqlite-vec is the index (MIT/Apache, pure C,
+    # ~60KB, arm64 wheels exist - drops onto Jetson without the build saga);
+    # it's brute-force KNN, which is CORRECT for a facts table this size, not a
+    # compromise. sentence-transformers turns fact text into the vectors it
+    # searches. Pinned >=0.1.6 (sqlite-vec is on the 0.1.x line; a >=1.0 pin
+    # would never resolve). Opt-in: `pip install seren-loci[vector]`.
+    "sqlite-vec>=0.1.6",
+    "sentence-transformers>=3.0",
+]
+mcp = [
+    # The Python MCP SDK from Anthropic (FastMCP merged in). Lets a connected
+    # Rhys set_fact/get_fact/search the left brain directly. Same loose pin as
+    # SerenMemory - the SDK moves fast and our server tolerates transport drift.
+    "mcp>=1.0",
+]
+corp = [
+    # Corporate / intercepting-proxy support. Routes Python TLS through the OS
+    # trust store so a corp root CA (Zscaler/Netskope/etc.) is honored without
+    # hand-exporting .pem files. Opt-in: `pip install seren-loci[corp]` +
+    # tls.trust_system_store: true (the --corp installer flag sets both).
+    "truststore>=0.9",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    # silences the starlette->httpx deprecation warning under fastapi.testclient
+    # and future-proofs the test stack against the hard cutover (same as memory).
+    "httpx2>=2.3",
+]
+
+[project.scripts]
+seren-loci = "seren_loci.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["seren_loci*"]
+
+# Ship the viewer HTML inside the wheel when it lands. Same gotcha as
+# SerenMemory: pip strips non-.py files, so GET /viewer would 404 on an
+# installed copy without this. Harmless before the viewer exists (the glob just
+# matches nothing).
+[tool.setuptools.package-data]
+seren_loci = ["viewer/*.html"]
+
+[tool.setuptools_scm]
+# .git is one level above pyproject.toml (repo root, not the SerenLoci subdir)
+root = ".."
+version_scheme = "release-branch-semver"
+# Tag-derived version written into the package (shipped in the wheel, read by
+# __init__ / importlib.metadata). _version.py is gitignored - build artifact.
+version_file = "seren_loci/_version.py"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

seren_loci-0.1.0/seren-loci.service.sample

@@ -0,0 +1,47 @@
+# SerenLoci systemd unit (sample)
+#
+# Install:
+#   1. Edit __TARGET_USER__ and the paths below
+#   2. sudo cp seren-loci.service /etc/systemd/system/
+#   3. sudo systemctl daemon-reload
+#   4. sudo systemctl enable --now seren-loci
+#
+# Logs:  journalctl -u seren-loci -f
+#
+# Tip: you usually don't hand-roll this - the setup scripts generate it for you.
+#   bash seren-loci-setup.sh --service     (Linux, via the generic core)
+# This sample is for understanding what they produce, or rolling your own.
+
+[Unit]
+Description=SerenLoci - keyed facts / the left brain
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=__TARGET_USER__
+WorkingDirectory=/home/__TARGET_USER__/seren-loci
+
+# Use the venv's python. Adjust the venv path to wherever you installed.
+ExecStart=/home/__TARGET_USER__/seren-venvs/loci/bin/python -m seren_loci --config /home/__TARGET_USER__/seren-loci/seren-loci.yaml
+
+# Force UTF-8 stdio regardless of locale, so an emoji or smart-quote in a
+# fact's why-text can never crash the logger. The installer sets this too.
+Environment=PYTHONUTF8=1
+
+# Config can also come from env - uncomment + set as needed:
+# Environment=SEREN_LOCI_PORT=7422
+# Environment=SEREN_LOCI_BEARER_TOKEN=
+# Environment=SEREN_LOCI_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
+
+Restart=on-failure
+RestartSec=5
+
+# The floor (sqlite + FTS5) barely touches memory. Only the OPTIONAL [vector]
+# embedder wants headroom - sentence-transformers plus a small model is a few
+# hundred MB. 1G is comfortable for all-MiniLM-L6-v2; bump it if you point
+# embedding_model at something larger.
+MemoryMax=1G
+
+[Install]
+WantedBy=multi-user.target

seren_loci-0.1.0/seren-loci.yaml.sample

@@ -0,0 +1,61 @@
+# ═══════════════════════════════════════════════════════════════════════
+#  seren-loci.yaml - config for SerenLoci (the left brain)
+# ═══════════════════════════════════════════════════════════════════════
+#
+#  Copy to seren-loci.yaml, edit, and run:
+#     python -m seren_loci --config seren-loci.yaml
+#
+#  Or just run with no config at all - the defaults below are baked in, so
+#  `python -m seren_loci` works zero-config for a local dev spin.
+#
+#  Env vars override file values (handy for Docker/systemd):
+#     SEREN_LOCI_PORT, SEREN_LOCI_HOST, SEREN_LOCI_BEARER_TOKEN,
+#     SEREN_LOCI_DB_PATH, SEREN_LOCI_EMBEDDING_MODEL,
+#     SEREN_LOCI_TRUST_SYSTEM_STORE
+#
+#  What this is: keyed, deterministic facts - exactly one live value per
+#  (project, key), old values kept as history, never blended. Where
+#  SerenMemory is fuzzy episodic recall (the right brain), Loci is the
+#  addressable logic store (the left). Notably ABSENT vs memory: no
+#  consolidator, no tiers, no embedder safe-mode. The finder is a rebuildable
+#  index over the fact text, so there's nothing to migrate and nothing to gate.
+#
+# ═══════════════════════════════════════════════════════════════════════
+
+server:
+  host: 0.0.0.0
+  port: 7422            # neighbor convention: memory 7420, margin 7421, loci 7422
+  # Leave empty for no auth (trusted LAN / dev). Set a token to require
+  #   Authorization: Bearer <token>
+  # on every endpoint except /, /health, and /viewer.
+  bearer_token: ""
+
+storage:
+  # The WHOLE left brain is one sqlite file. ~ is expanded; the parent dir is
+  # created on first run. Back THIS up - it survives package upgrades untouched.
+  db_path: ~/.seren-loci/loci.db
+
+  # OPTIONAL associative finder (the "this smells like that CUDA thing" jump).
+  #   null / unset -> embedding-free FLOOR: exact-key + FTS5 lexical only.
+  #                   Zero vector deps, no torch. Runs on a 4GB laptop / Nano.
+  #   a model name -> builds a sqlite-vec index over the facts so search can
+  #                   make the semantic jump. Exact-key hits ALWAYS still lead
+  #                   at score 1.0; the finder only fills in below them.
+  #
+  # Requires the vector extra:  pip install seren-loci[vector]
+  # (or run the installer with --vector / -Vector, which sets this for you).
+  # all-MiniLM-L6-v2 is ~80MB, CPU-friendly, downloaded on first use.
+  embedding_model: null
+  # embedding_model: sentence-transformers/all-MiniLM-L6-v2
+  embedding_device: cpu   # "cpu", or "cuda" if you've got the VRAM to spare
+
+# -- Corporate / intercepting-proxy support (opt-in) ------------------------
+# If you're on a corporate network that does TLS interception (Zscaler,
+# Netskope, etc.), the proxy's root CA is in your OS trust store but not in
+# Python's bundled certs, so the embedder's model download fails with
+# CERTIFICATE_VERIFY_FAILED. Turn this on to route TLS through the OS store.
+#
+# Requires the corp extra:  pip install seren-loci[corp]
+# Or run the installer with --corp / -Corp (sets this and installs the extra).
+# tls:
+#   trust_system_store: true

seren_loci-0.1.0/seren_loci/__init__.py

@@ -0,0 +1,17 @@
+"""
+SerenLoci - the left brain. A keyed facts/logic store for the Seren
+constellation: addressable, deterministic, one live value per key.
+
+The deterministic spine (exact + FTS5 lexical) runs embedding-free on the
+floor. An optional sqlite-vec finder adds the associative jump when an
+embedder is configured. Pairs with SerenLoci (the right brain) under a
+future SerenCorpusCallosum.
+"""
+from __future__ import annotations
+
+try:
+    from ._version import version as __version__
+except Exception:  # noqa: BLE001 - source checkout without a build
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]