lore-solo 0.1.0__tar.gz

lore_solo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Lore Team
+
+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.

lore_solo-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include build_support.py
+recursive-include web *
+prune web/node_modules
+prune web/.next
+global-exclude *.tsbuildinfo

lore_solo-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: lore-solo
+Version: 0.1.0
+Summary: Governed persona and skill context for a solo developer’s coding agent.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/starrynight-web/LORE
+Project-URL: Repository, https://github.com/starrynight-web/LORE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6
+Requires-Dist: tiktoken>=0.7
+Requires-Dist: fastmcp>=2
+Requires-Dist: django>=5.1
+Requires-Dist: graphifyy==0.9.93
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-jsonschema; extra == "dev"
+Dynamic: license-file
+
+# Lore
+
+[![ci](https://github.com/starrynight-web/LORE/actions/workflows/ci.yml/badge.svg)](https://github.com/starrynight-web/LORE/actions/workflows/ci.yml)
+
+Lore gives one developer’s coding agent a persona, the skills filed under that persona, and a short map of the codebase. The agent calls Lore over MCP and gets one persona back, inside a token budget. Every answer is written down as a decision.
+
+The project folder is the database. Personas and skills are markdown under `.lore/`. The setup site only makes those files easier to create. Closing the site does not stop the agent.
+
+The older architecture documents describe the previous Go design.
+
+## Quick start
+
+The setup site needs Node.js. The agent does not. With [uv](https://docs.astral.sh/uv/) installed, the same commands work on macOS, Linux, and Windows:
+
+```bash
+uvx lore-solo install
+uvx lore-solo setup
+```
+
+`install` puts the `lore-solo` command on this computer, in `~/.lore/bin`. `setup` prints an address and keeps running until you press Ctrl+C. Open that link. Run `uvx lore-solo setup` again whenever you want the website back. Save a provider key, add skills, create a persona, then give the connect prompt to your agent. Personas you write stay drafts until you approve them.
+
+The other commands are the same shape:
+
+```bash
+uvx lore-solo connect
+uvx lore-solo mcp
+```
+
+`connect` registers Lore with the editors already installed. The editor then starts `lore-solo mcp` on its own.
+
+From a clone of the `solo` branch, the same four commands are:
+
+```bash
+git clone -b solo https://github.com/starrynight-web/LORE.git lore-solo
+cd lore-solo
+./scripts/lore-solo install
+./scripts/lore-solo setup
+./scripts/lore-solo connect
+```
+
+On Windows, from that clone:
+
+```powershell
+.\scripts\lore-solo.ps1 install
+.\scripts\lore-solo.ps1 setup
+.\scripts\lore-solo.ps1 connect
+```
+
+The agent calls Lore from any project. A project with its own `.lore` directory uses that. Every other project uses the personas saved from setup.
+
+Connect shows a prompt to paste into an agent. With uv, that prompt is `uvx lore-solo connect` on macOS, Linux, and Windows. From the clone it runs `scripts/lore-solo connect` (or `scripts/lore-solo.ps1 connect` on Windows). Writing `.cursor/mcp.json` inside one project stays available as a backup:
+
+```json
+{
+  "mcpServers": {
+    "lore": {
+      "command": "uvx",
+      "args": ["lore-solo", "mcp"]
+    }
+  }
+}
+```
+
+Restart the editor. It starts Lore on its own. Lore looks for `.lore/` from the working directory upward, then uses the personas saved from setup.
+
+`examples/persona-pack` is a small project with a frontend persona, a backend persona, and a codebase map.
+
+## What the agent receives
+
+`get_context` returns one-line summaries of the stable skills for that persona, then a few nodes from the codebase map when one exists. `get_skill` returns the full steps for one skill. A draft persona asks you to approve it. An unknown persona returns nothing governed.
+
+## Development
+
+```bash
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check lore
+.venv/bin/mypy
+.venv/bin/pytest
+```
+
+`lore/core` reads and writes the files. `lore/mcp.py` is the stdio server the IDE starts. `lore/setup` and `web/` are the setup site. `schemas/lore.result.v1.json` is the answer envelope.
+
+## Documentation
+
+| Document | Contents |
+| --- | --- |
+| [docs/LORE_OVERVIEW.md](docs/LORE_OVERVIEW.md) | Earlier product overview |
+| [docs/LORE_ARCHITECTURE.md](docs/LORE_ARCHITECTURE.md) | Earlier target architecture |
+| [docs/PROJECT_REQUIREMENTS.md](docs/PROJECT_REQUIREMENTS.md) | Earlier requirements |
+| [docs/PROJECT_CHARTER.md](docs/PROJECT_CHARTER.md) | Earlier scope and milestones |
+| [docs/solo/HOW_IT_WORKS.md](docs/solo/HOW_IT_WORKS.md) | How the solo slice runs |
+| [docs/solo/UI.md](docs/solo/UI.md) | Setup site pages and how to change them |
+| [docs/solo/TASKLIST.md](docs/solo/TASKLIST.md) | Build record and the current shape |
+| [docs/solo/HOSTING.md](docs/solo/HOSTING.md) | What a later paid host would sync |
+
+## License
+
+[MIT](LICENSE)

lore_solo-0.1.0/README.md

@@ -0,0 +1,98 @@
+# Lore
+
+[![ci](https://github.com/starrynight-web/LORE/actions/workflows/ci.yml/badge.svg)](https://github.com/starrynight-web/LORE/actions/workflows/ci.yml)
+
+Lore gives one developer’s coding agent a persona, the skills filed under that persona, and a short map of the codebase. The agent calls Lore over MCP and gets one persona back, inside a token budget. Every answer is written down as a decision.
+
+The project folder is the database. Personas and skills are markdown under `.lore/`. The setup site only makes those files easier to create. Closing the site does not stop the agent.
+
+The older architecture documents describe the previous Go design.
+
+## Quick start
+
+The setup site needs Node.js. The agent does not. With [uv](https://docs.astral.sh/uv/) installed, the same commands work on macOS, Linux, and Windows:
+
+```bash
+uvx lore-solo install
+uvx lore-solo setup
+```
+
+`install` puts the `lore-solo` command on this computer, in `~/.lore/bin`. `setup` prints an address and keeps running until you press Ctrl+C. Open that link. Run `uvx lore-solo setup` again whenever you want the website back. Save a provider key, add skills, create a persona, then give the connect prompt to your agent. Personas you write stay drafts until you approve them.
+
+The other commands are the same shape:
+
+```bash
+uvx lore-solo connect
+uvx lore-solo mcp
+```
+
+`connect` registers Lore with the editors already installed. The editor then starts `lore-solo mcp` on its own.
+
+From a clone of the `solo` branch, the same four commands are:
+
+```bash
+git clone -b solo https://github.com/starrynight-web/LORE.git lore-solo
+cd lore-solo
+./scripts/lore-solo install
+./scripts/lore-solo setup
+./scripts/lore-solo connect
+```
+
+On Windows, from that clone:
+
+```powershell
+.\scripts\lore-solo.ps1 install
+.\scripts\lore-solo.ps1 setup
+.\scripts\lore-solo.ps1 connect
+```
+
+The agent calls Lore from any project. A project with its own `.lore` directory uses that. Every other project uses the personas saved from setup.
+
+Connect shows a prompt to paste into an agent. With uv, that prompt is `uvx lore-solo connect` on macOS, Linux, and Windows. From the clone it runs `scripts/lore-solo connect` (or `scripts/lore-solo.ps1 connect` on Windows). Writing `.cursor/mcp.json` inside one project stays available as a backup:
+
+```json
+{
+  "mcpServers": {
+    "lore": {
+      "command": "uvx",
+      "args": ["lore-solo", "mcp"]
+    }
+  }
+}
+```
+
+Restart the editor. It starts Lore on its own. Lore looks for `.lore/` from the working directory upward, then uses the personas saved from setup.
+
+`examples/persona-pack` is a small project with a frontend persona, a backend persona, and a codebase map.
+
+## What the agent receives
+
+`get_context` returns one-line summaries of the stable skills for that persona, then a few nodes from the codebase map when one exists. `get_skill` returns the full steps for one skill. A draft persona asks you to approve it. An unknown persona returns nothing governed.
+
+## Development
+
+```bash
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/ruff check lore
+.venv/bin/mypy
+.venv/bin/pytest
+```
+
+`lore/core` reads and writes the files. `lore/mcp.py` is the stdio server the IDE starts. `lore/setup` and `web/` are the setup site. `schemas/lore.result.v1.json` is the answer envelope.
+
+## Documentation
+
+| Document | Contents |
+| --- | --- |
+| [docs/LORE_OVERVIEW.md](docs/LORE_OVERVIEW.md) | Earlier product overview |
+| [docs/LORE_ARCHITECTURE.md](docs/LORE_ARCHITECTURE.md) | Earlier target architecture |
+| [docs/PROJECT_REQUIREMENTS.md](docs/PROJECT_REQUIREMENTS.md) | Earlier requirements |
+| [docs/PROJECT_CHARTER.md](docs/PROJECT_CHARTER.md) | Earlier scope and milestones |
+| [docs/solo/HOW_IT_WORKS.md](docs/solo/HOW_IT_WORKS.md) | How the solo slice runs |
+| [docs/solo/UI.md](docs/solo/UI.md) | Setup site pages and how to change them |
+| [docs/solo/TASKLIST.md](docs/solo/TASKLIST.md) | Build record and the current shape |
+| [docs/solo/HOSTING.md](docs/solo/HOSTING.md) | What a later paid host would sync |
+
+## License
+
+[MIT](LICENSE)

lore_solo-0.1.0/build_support.py

@@ -0,0 +1,24 @@
+"""Copy the setup site into the wheel. Dependencies and build output stay out."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from setuptools.command.build_py import build_py
+
+
+class BuildPy(build_py):
+    def run(self) -> None:
+        super().run()
+        src = Path(__file__).resolve().parent / "web"
+        if not (src / "package.json").is_file():
+            return
+        dest = Path(self.build_lib) / "lore" / "web_src"
+        if dest.exists():
+            shutil.rmtree(dest)
+        shutil.copytree(
+            src,
+            dest,
+            ignore=shutil.ignore_patterns("node_modules", ".next", "tsconfig.tsbuildinfo"),
+        )

lore_solo-0.1.0/lore/__init__.py

@@ -0,0 +1,3 @@
+"""Lore engine: personas, skills, and a codebase map for one developer."""
+
+__version__ = "0.1.0"

lore_solo-0.1.0/lore/__main__.py

@@ -0,0 +1,43 @@
+"""`lore-solo install`, `setup`, `connect`, and `mcp`."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help"}:
+        print("usage: lore-solo install|setup|connect|mcp", file=sys.stderr)
+        return 0
+    command, rest = args[0], args[1:]
+    if command == "install":
+        from lore.install_cmd import run as run_install
+
+        run_install(rest)
+        return 0
+    if command == "setup":
+        from lore.setup_cmd import run as run_setup
+
+        run_setup(rest)
+        return 0
+    if command == "connect":
+        from lore.connect import register_agents
+
+        result = register_agents()
+        for path in result["written"]:
+            print(path)
+        for skipped in result["skipped"]:
+            print(f"skipped {skipped}", file=sys.stderr)
+        return 0 if result["written"] else 1
+    if command == "mcp":
+        from lore.mcp import run as run_mcp
+
+        run_mcp(rest)
+        return 0
+    print(f"unknown command {command!r}; use install, setup, connect, or mcp", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lore_solo-0.1.0/lore/connect.py

@@ -0,0 +1,232 @@
+"""MCP entry for Lore, and the editor configs the connect command writes.
+
+The command is a local process. The editor starts it with the open project as
+its working directory.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+from pathlib import Path
+
+
+def invocation() -> tuple[str, list[str]]:
+    """The program an editor should start, and the arguments that select MCP."""
+    explicit = os.environ.get("LORE_COMMAND", "").strip()
+    if explicit:
+        return explicit, ["mcp"]
+    installed = _installed_command()
+    if installed is not None:
+        return str(installed), ["mcp"]
+    for name in ("lore-solo", "lore"):
+        found = shutil.which(name)
+        if found:
+            return found, ["mcp"]
+    return "uvx", ["lore-solo", "mcp"]
+
+
+def lore_command() -> str:
+    """The program editors should start."""
+    return invocation()[0]
+
+
+def _installed_command() -> Path | None:
+    bin_dir = Path.home() / ".lore" / "bin"
+    for name in ("lore-solo", "lore"):
+        base = bin_dir / name
+        if os.name == "nt":
+            windows = base.with_suffix(".exe")
+            if windows.is_file():
+                return windows
+        if base.is_file():
+            return base
+    return None
+
+
+def mcp_args() -> list[str]:
+    return invocation()[1]
+
+
+def mcp_entry(
+    kind: str,
+    command: str | None = None,
+    client: str = "",
+    args: list[str] | None = None,
+) -> dict[str, object]:
+    chosen, chosen_args = invocation()
+    if command is not None:
+        chosen = command
+    if args is not None:
+        chosen_args = args
+    elif command is not None:
+        chosen_args = ["mcp"]
+    entry: dict[str, object] = {"command": chosen, "args": chosen_args}
+    if kind == "vscode":
+        entry["type"] = "stdio"
+    name = client.strip()
+    if name:
+        entry["env"] = {"LORE_CLIENT": name}
+    return entry
+
+
+def install_command() -> str:
+    launcher = os.environ.get("LORE_LAUNCHER", "").strip()
+    if launcher:
+        return f"{launcher} connect"
+    return "uvx lore-solo connect"
+
+
+def windows_command(command: str) -> str:
+    if command.startswith("uvx "):
+        return command
+    suffix = " connect"
+    if command.endswith(suffix):
+        script = command[: -len(suffix)]
+        if script.endswith(".ps1"):
+            return command
+        return f"{script}.ps1 connect"
+    return "scripts/lore-solo.ps1 connect"
+
+
+def agent_prompt(command: str | None = None) -> str:
+    chosen = command or install_command()
+    windows = windows_command(chosen)
+    if windows == chosen:
+        steps = f"On macOS, Linux, or Windows, run:\n\n{chosen}\n\n"
+    else:
+        steps = (
+            "On macOS or Linux, run this in the shell:\n\n"
+            f"{chosen}\n\n"
+            "On Windows, run this in PowerShell:\n\n"
+            f"{windows}\n\n"
+        )
+    return (
+        "Register Lore with the editors on this computer. "
+        f"{steps}"
+        "When it finishes, confirm Lore is registered with the editors it found. "
+        "A project that already has a .lore directory keeps using that directory."
+    )
+
+
+def host_system(value: str | None = None) -> str:
+    raw = (value or os.environ.get("LORE_HOST_OS") or platform.system()).lower()
+    if raw.startswith("darwin") or raw == "macos":
+        return "darwin"
+    if raw.startswith("win"):
+        return "windows"
+    return "linux"
+
+
+def _write_json(path: Path, key: str, entry: dict[str, object]) -> None:
+    data: dict[str, object] = {}
+    if path.is_file():
+        raw = path.read_text(encoding="utf-8").strip()
+        if raw:
+            loaded = json.loads(raw)
+            if not isinstance(loaded, dict):
+                raise ValueError(f"{path} is not a JSON object.")
+            data = loaded
+        backup = path.with_name(path.name + ".lore.bak")
+        if not backup.exists():
+            shutil.copyfile(path, backup)
+    servers = data.get(key)
+    if not isinstance(servers, dict):
+        servers = {}
+    servers["lore"] = entry
+    data[key] = servers
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _strip_toml_section(text: str, heading: str) -> str:
+    kept: list[str] = []
+    skipping = False
+    blanks: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("["):
+            skipping = stripped == heading or stripped.startswith(heading + " ")
+        if skipping:
+            continue
+        if stripped == "":
+            blanks.append(line)
+            continue
+        kept.extend(blanks)
+        blanks = []
+        kept.append(line)
+    return "\n".join(kept).rstrip()
+
+
+def _write_codex(path: Path, command: str, client: str = "", args: list[str] | None = None) -> None:
+    existing = path.read_text(encoding="utf-8") if path.is_file() else ""
+    if path.is_file():
+        backup = path.with_name(path.name + ".lore.bak")
+        if not backup.exists():
+            shutil.copyfile(path, backup)
+    kept = _strip_toml_section(existing, "[mcp_servers.lore]")
+    rendered = ", ".join(json.dumps(part) for part in (args if args is not None else mcp_args()))
+    env = ""
+    if client.strip():
+        env = f"env = {{ LORE_CLIENT = {json.dumps(client.strip())} }}\n"
+    block = f"[mcp_servers.lore]\ncommand = {json.dumps(command)}\nargs = [{rendered}]\n{env}"
+    body = f"{kept}\n\n{block}" if kept else block
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body if body.endswith("\n") else body + "\n", encoding="utf-8")
+
+
+def _targets(home: Path, system: str) -> list[tuple[str, Path, str, str]]:
+    """(label, file, container key, editor). An editor is included when its folder exists."""
+    if system == "darwin":
+        desktop = home / "Library" / "Application Support" / "Claude"
+        vscode = home / "Library" / "Application Support" / "Code" / "User"
+    elif system == "windows":
+        desktop = home / "AppData" / "Roaming" / "Claude"
+        vscode = home / "AppData" / "Roaming" / "Code" / "User"
+    else:
+        desktop = home / ".config" / "Claude"
+        vscode = home / ".config" / "Code" / "User"
+    rows: list[tuple[str, Path, str, str]] = []
+    cursor = home / ".cursor"
+    if cursor.is_dir() or (cursor / "mcp.json").exists():
+        rows.append(("Cursor", cursor / "mcp.json", "mcpServers", "cursor"))
+    claude = home / ".claude.json"
+    if claude.exists() or (home / ".claude").is_dir():
+        rows.append(("Claude Code", claude, "mcpServers", "other"))
+    if desktop.is_dir():
+        rows.append(("Claude Desktop", desktop / "claude_desktop_config.json", "mcpServers", "other"))
+    if (home / ".codex").is_dir():
+        rows.append(("Codex", home / ".codex" / "config.toml", "", "codex"))
+    if vscode.is_dir():
+        rows.append(("VS Code", vscode / "mcp.json", "servers", "vscode"))
+    gemini = home / ".gemini" / "config"
+    if gemini.is_dir():
+        rows.append(("Antigravity", gemini / "mcp_config.json", "mcpServers", "other"))
+    return rows
+
+
+def register_agents(
+    home: Path | None = None,
+    system: str | None = None,
+) -> dict[str, list[str]]:
+    """Write Lore into each detected editor. Other servers in those files stay."""
+    if home is None:
+        raw = os.environ.get("LORE_HOST_HOME", "")
+        home = Path(raw) if raw else Path.home()
+    host = host_system(system)
+    command, args = invocation()
+    written: list[str] = []
+    skipped: list[str] = []
+    for label, path, key, editor in _targets(home, host):
+        try:
+            if editor == "codex":
+                _write_codex(path, command, client=label, args=args)
+            else:
+                _write_json(path, key, mcp_entry(editor, command, client=label, args=args))
+        except (OSError, ValueError, json.JSONDecodeError):
+            skipped.append(f"{label}: {path}")
+            continue
+        written.append(str(path))
+    return {"written": written, "skipped": skipped}

lore_solo-0.1.0/lore/core/__init__.py

@@ -0,0 +1 @@
+"""File-backed knowledge. No network and no database."""

lore_solo-0.1.0/lore/core/budget.py

@@ -0,0 +1,40 @@
+"""Count tokens for the 800-token answer cap.
+
+The count is cl100k_base when the tiktoken encoder is installed. That is the
+same encoding the previous Go engine used. If the encoder cannot be loaded,
+the count is one token per three UTF-8 bytes, rounded up. Tests pin both
+behaviors by name.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Protocol
+
+
+class _Encoder(Protocol):
+    def encode(self, text: str) -> list[int]: ...
+
+
+@lru_cache(maxsize=1)
+def _encoder() -> _Encoder | None:
+    try:
+        import tiktoken
+    except ImportError:
+        return None
+    try:
+        return tiktoken.get_encoding("cl100k_base")
+    except (OSError, ValueError, RuntimeError):
+        return None
+
+
+def count_tokens(text: str) -> int:
+    encoder = _encoder()
+    if encoder is not None:
+        return len(encoder.encode(text))
+    return _bytes_fallback(text)
+
+
+def _bytes_fallback(text: str) -> int:
+    """One token per three UTF-8 bytes, rounded up. Used only if tiktoken is missing."""
+    return (len(text.encode("utf-8")) + 2) // 3