locusfiles 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,14 @@
1
+ .venv/
2
+ venv/
3
+ __pycache__/
4
+ *.pyc
5
+ *.egg-info/
6
+ dist/
7
+ build/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .env
11
+ .locus/
12
+ .DS_Store
13
+ # Repo-internal ignores live in nested .gitignore files: hatchling
14
+ # ships this root file in the public sdist (packaging review F8).
@@ -0,0 +1,91 @@
1
+ Metadata-Version: 2.5
2
+ Name: locusfiles
3
+ Version: 0.1.0
4
+ Summary: Local-first personal AI brain: index your own folders and search them from local MCP clients such as Claude Desktop, Claude Code and Cursor.
5
+ License-Expression: FSL-1.1-ALv2
6
+ License-File: src/locus/LICENSE
7
+ License-File: src/locus/NOTICE
8
+ License-File: src/locus/THIRD_PARTY_LICENSES.md
9
+ Requires-Python: >=3.11
10
+ Requires-Dist: chromadb<1.6,>=1.5
11
+ Requires-Dist: mcp<2.3,>=2.2
12
+ Requires-Dist: pydantic>=2.5
13
+ Requires-Dist: pypdfium2>=4.30
14
+ Requires-Dist: python-docx>=1.1
15
+ Requires-Dist: python-dotenv>=1.0
16
+ Requires-Dist: watchdog>=4.0
17
+ Provides-Extra: dev
18
+ Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
19
+ Requires-Dist: pytest>=8.0; extra == 'dev'
20
+ Requires-Dist: ruff>=0.6; extra == 'dev'
21
+ Provides-Extra: lancedb
22
+ Requires-Dist: lancedb>=0.15; extra == 'lancedb'
23
+ Provides-Extra: local
24
+ Requires-Dist: sentence-transformers>=3.0; extra == 'local'
25
+ Provides-Extra: openai
26
+ Requires-Dist: openai>=1.30; extra == 'openai'
27
+ Provides-Extra: relay
28
+ Requires-Dist: cryptography>=42; extra == 'relay'
29
+ Requires-Dist: httpx>=0.27; extra == 'relay'
30
+ Requires-Dist: realtime<2.32,>=2.31; extra == 'relay'
31
+ Provides-Extra: voyage
32
+ Requires-Dist: voyageai>=0.3; extra == 'voyage'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # Locus
36
+
37
+ Your files, your machine, the MCP clients you already use.
38
+
39
+ Locus indexes folders you choose on your own computer and gives MCP clients that can start a local
40
+ server (tested: Claude Desktop, Claude Code and Cursor) a semantic search tool over them. Every
41
+ result carries the file path, so the assistant can cite its sources.
42
+
43
+ The package is `locusfiles`; the command it installs is `locus`.
44
+
45
+ ## Install
46
+
47
+ You need Python 3.11 or newer. Install with [pipx](https://pipx.pypa.io) or
48
+ [uv](https://docs.astral.sh/uv/), which put `locus` in its own environment. These commands work
49
+ once `locusfiles` is published on PyPI (first upload planned for 2026-10-01):
50
+
51
+ ```bash
52
+ # On-device embeddings, no account (downloads PyTorch, about 1-2 GB):
53
+ pipx install "locusfiles[local]"
54
+ # or
55
+ uv tool install --python 3.12 "locusfiles[local]"
56
+
57
+ # A Locus plan (managed embeddings, remote connection), no PyTorch:
58
+ pipx install "locusfiles[relay]"
59
+ ```
60
+
61
+ Other extras: `voyage` or `openai` to embed with your own provider key.
62
+
63
+ macOS and Linux are tested. Windows is not yet verified.
64
+
65
+ ## First search
66
+
67
+ ```bash
68
+ export LOCUS_EMBEDDER=local # or managed (with LOCUS_API_KEY), voyage, openai
69
+ locus doctor # checks Python, packages, settings and the embedder
70
+ locus index ~/Documents/notes --prune # parse, chunk, embed and index a folder
71
+ locus query "what did I decide about pricing" -k 5
72
+ ```
73
+
74
+ Then connect your AI assistant: it runs `locus serve` (MCP over stdio). Setup steps for each
75
+ client are on the Locus website's Connect page (`/docs/connect`).
76
+
77
+ ## What leaves your computer
78
+
79
+ - Local: Indexing and embeddings run on your computer. When your AI assistant searches, the
80
+ matching excerpts go to that assistant, as they would if you pasted them in.
81
+ - Your own key: Chunk text goes straight from your computer to the embedding provider you chose,
82
+ under your own account.
83
+ - Managed: On managed plans, chunk text passes through Locus's relay to Voyage AI to be embedded.
84
+ We don't store it; we keep only usage counts.
85
+ - Remote: When you reach your computer from another device or a web AI app, your question and
86
+ the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your
87
+ computer. They are encrypted in transit and we don't store them.
88
+ - In every mode: Your raw files are never uploaded to Locus.
89
+
90
+ Indexes live in `~/.locus` (set `LOCUS_DATA_DIR` to move them). Settings are environment
91
+ variables, or a `.env` file in the directory you run `locus` from or one of its parents.
@@ -0,0 +1,57 @@
1
+ # Locus
2
+
3
+ Your files, your machine, the MCP clients you already use.
4
+
5
+ Locus indexes folders you choose on your own computer and gives MCP clients that can start a local
6
+ server (tested: Claude Desktop, Claude Code and Cursor) a semantic search tool over them. Every
7
+ result carries the file path, so the assistant can cite its sources.
8
+
9
+ The package is `locusfiles`; the command it installs is `locus`.
10
+
11
+ ## Install
12
+
13
+ You need Python 3.11 or newer. Install with [pipx](https://pipx.pypa.io) or
14
+ [uv](https://docs.astral.sh/uv/), which put `locus` in its own environment. These commands work
15
+ once `locusfiles` is published on PyPI (first upload planned for 2026-10-01):
16
+
17
+ ```bash
18
+ # On-device embeddings, no account (downloads PyTorch, about 1-2 GB):
19
+ pipx install "locusfiles[local]"
20
+ # or
21
+ uv tool install --python 3.12 "locusfiles[local]"
22
+
23
+ # A Locus plan (managed embeddings, remote connection), no PyTorch:
24
+ pipx install "locusfiles[relay]"
25
+ ```
26
+
27
+ Other extras: `voyage` or `openai` to embed with your own provider key.
28
+
29
+ macOS and Linux are tested. Windows is not yet verified.
30
+
31
+ ## First search
32
+
33
+ ```bash
34
+ export LOCUS_EMBEDDER=local # or managed (with LOCUS_API_KEY), voyage, openai
35
+ locus doctor # checks Python, packages, settings and the embedder
36
+ locus index ~/Documents/notes --prune # parse, chunk, embed and index a folder
37
+ locus query "what did I decide about pricing" -k 5
38
+ ```
39
+
40
+ Then connect your AI assistant: it runs `locus serve` (MCP over stdio). Setup steps for each
41
+ client are on the Locus website's Connect page (`/docs/connect`).
42
+
43
+ ## What leaves your computer
44
+
45
+ - Local: Indexing and embeddings run on your computer. When your AI assistant searches, the
46
+ matching excerpts go to that assistant, as they would if you pasted them in.
47
+ - Your own key: Chunk text goes straight from your computer to the embedding provider you chose,
48
+ under your own account.
49
+ - Managed: On managed plans, chunk text passes through Locus's relay to Voyage AI to be embedded.
50
+ We don't store it; we keep only usage counts.
51
+ - Remote: When you reach your computer from another device or a web AI app, your question and
52
+ the matching excerpts travel through Locus's relay (Vercel and Supabase) to and from your
53
+ computer. They are encrypted in transit and we don't store them.
54
+ - In every mode: Your raw files are never uploaded to Locus.
55
+
56
+ Indexes live in `~/.locus` (set `LOCUS_DATA_DIR` to move them). Settings are environment
57
+ variables, or a `.env` file in the directory you run `locus` from or one of its parents.
@@ -0,0 +1,68 @@
1
+ [project]
2
+ # The distribution name is the ONE place the PyPI name lives (scripts/dist_name.py).
3
+ # E1 (Ch.8.10): `locusfiles` (W26, IP-008); `locus` is taken on PyPI. Import name and CLI stay `locus`.
4
+ name = "locusfiles"
5
+ dynamic = ["version"] # from src/locus/__init__.py (__version__), see [tool.hatch.version]
6
+ description = "Local-first personal AI brain: index your own folders and search them from local MCP clients such as Claude Desktop, Claude Code and Cursor."
7
+ readme = "docs/package/README.md" # public PyPI page; the repo README is internal (F8)
8
+ requires-python = ">=3.11"
9
+ # A6 ratified 2026-09-26 (licensor Yonathan Levy). PEP 639 SPDX expression; the licence covers the
10
+ # engine only, so its text lives next to the engine and ships in the wheel's dist-info/licenses/.
11
+ # LEG-014: NOTICE and the third-party licence inventory (scripts/licence_inventory.py writes it) ship
12
+ # the same way; scripts/check_dist_contents.py fails a build whose sdist or wheel lacks any of them.
13
+ license = "FSL-1.1-ALv2"
14
+ license-files = ["src/locus/LICENSE", "src/locus/NOTICE", "src/locus/THIRD_PARTY_LICENSES.md"]
15
+ dependencies = [
16
+ "mcp>=2.2,<2.3",
17
+ "chromadb>=1.5,<1.6",
18
+ "pydantic>=2.5",
19
+ "python-dotenv>=1.0",
20
+ "watchdog>=4.0",
21
+ "pypdfium2>=4.30",
22
+ "python-docx>=1.1",
23
+ ]
24
+
25
+ [project.optional-dependencies]
26
+ voyage = ["voyageai>=0.3"]
27
+ openai = ["openai>=1.30"]
28
+ local = ["sentence-transformers>=3.0"]
29
+ lancedb = ["lancedb>=0.15"]
30
+ relay = ["realtime>=2.31,<2.32", "httpx>=0.27", "cryptography>=42"] # cryptography: SEC-021 request verification
31
+ # hatchling: the build backend below, so tests/test_connector_check.py builds the checkout's wheel
32
+ # offline (--no-build-isolation) instead of downloading it in every CI run.
33
+ dev = ["pytest>=8.0", "ruff>=0.6", "hatchling>=1.27,<2"]
34
+
35
+ [project.scripts]
36
+ locus = "locus.cli:main"
37
+
38
+ [build-system]
39
+ requires = ["hatchling>=1.27,<2"] # pinned: Metadata-Version 2.4+ (F8)
40
+ build-backend = "hatchling.build"
41
+
42
+ [tool.hatch.version]
43
+ # One version source: the engine reports __version__ (X-Locus-Version, locus_diagnose_connection).
44
+ path = "src/locus/__init__.py"
45
+
46
+ [tool.hatch.build.targets.wheel]
47
+ packages = ["src/locus"]
48
+
49
+ # IP-008: the sdist is an allowlist. Hatchling's default sdist is "everything git tracks", which
50
+ # for this private repo means the master plan, docs/, locus-web/, supabase/ and .claude/ would be
51
+ # published with the package. scripts/check_dist_contents.py fails the package workflow if
52
+ # anything outside this list (plus the PKG-INFO and .gitignore hatchling adds) gets in.
53
+ [tool.hatch.build.targets.sdist]
54
+ only-include = ["src/locus", "pyproject.toml", "docs/package/README.md"]
55
+
56
+ [tool.pytest.ini_options]
57
+ testpaths = ["tests"]
58
+ pythonpath = ["src"]
59
+ markers = [
60
+ "e2e: installs the engine into a temporary environment and drives it end to end (runs in CI; about 15 s)",
61
+ ]
62
+
63
+ [tool.ruff]
64
+ line-length = 120
65
+ target-version = "py311"
66
+
67
+ [tool.ruff.lint]
68
+ select = ["E", "F", "I", "UP", "B"]
@@ -0,0 +1,105 @@
1
+ # Functional Source License, Version 1.1, ALv2 Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-ALv2
6
+
7
+ ## Notice
8
+
9
+ Copyright 2026 Yonathan Levy
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or
34
+ service that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software
39
+ that exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee
52
+ using the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to
59
+ the infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
+ PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
+ EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the Apache License, Version 2.0 that is effective on the second anniversary of
91
+ the date we make the Software available. On or after that date, you may use the
92
+ Software under the Apache License, Version 2.0, in which case the following
93
+ will apply:
94
+
95
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
96
+ this file except in compliance with the License.
97
+
98
+ You may obtain a copy of the License at
99
+
100
+ http://www.apache.org/licenses/LICENSE-2.0
101
+
102
+ Unless required by applicable law or agreed to in writing, software distributed
103
+ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
104
+ CONDITIONS OF ANY KIND, either express or implied. See the License for the
105
+ specific language governing permissions and limitations under the License.
@@ -0,0 +1,18 @@
1
+ Locus engine (the `locusfiles` package)
2
+ Copyright 2026 Yonathan Levy
3
+
4
+ Licensed under the Functional Source License, Version 1.1, ALv2 Future License
5
+ (FSL-1.1-ALv2). The full terms are in the LICENSE file shipped with this package.
6
+
7
+ Third-party software
8
+ --------------------
9
+ This package contains no third-party source code. It depends on third-party
10
+ packages (mcp, chromadb, pydantic, python-dotenv, watchdog, pypdfium2,
11
+ python-docx, and optional extras) that pip, pipx or uv installs separately from
12
+ their own upstream releases. Each keeps its own licence and notices, which ship
13
+ with that package. THIRD_PARTY_LICENSES.md lists every direct dependency, its
14
+ declared licence and where it comes from.
15
+
16
+ With LOCUS_EMBEDDER=local, the engine downloads the BAAI/bge-small-en-v1.5
17
+ embedding model (MIT licence) from Hugging Face on first use. The model is not
18
+ included in this package.
@@ -0,0 +1,34 @@
1
+ # Third-party licences: Locus engine (`locusfiles`)
2
+
3
+ Direct runtime dependencies of this package, generated from each installed package's metadata on 2026-09-26.
4
+ None of them is bundled in this package: pip, pipx or uv installs each one from its own upstream
5
+ release, which carries its own licence text and any NOTICE file. Test and lint tools are not listed
6
+ because they are never installed for users. The Locus engine itself is licensed under
7
+ FSL-1.1-ALv2 (see LICENSE and NOTICE).
8
+
9
+ | Package | Needed for | Version range | Licence (as declared) | Checked version | Ships its own NOTICE | Upstream |
10
+ |---|---|---|---|---|---|---|
11
+ | mcp | core | `>=2.2,<2.3` | MIT | 2.2.0 | no | https://github.com/modelcontextprotocol/python-sdk |
12
+ | chromadb | core | `>=1.5,<1.6` | Apache-2.0 | 1.5.9 | no | https://github.com/chroma-core/chroma |
13
+ | pydantic | core | `>=2.5` | MIT | 2.13.5 | no | https://github.com/pydantic/pydantic |
14
+ | python-dotenv | core | `>=1.0` | BSD-3-Clause | 1.2.3 | no | https://github.com/theskumar/python-dotenv |
15
+ | watchdog | core | `>=4.0` | Apache-2.0 | 6.0.0 | no | https://github.com/gorakhargosh/watchdog/ |
16
+ | pypdfium2 | core | `>=4.30` | BSD-3-Clause, Apache-2.0, dependency licenses | 5.13.0 | no | https://github.com/pypdfium2-team/pypdfium2 |
17
+ | python-docx | core | `>=1.1` | MIT | 1.2.0 | no | https://github.com/python-openxml/python-docx |
18
+ | voyageai | extra `voyage` | `>=0.3` | MIT | 0.5.0 | no | https://pypi.org/project/voyageai/ |
19
+ | openai | extra `openai` | `>=1.30` | Apache-2.0 | 3.19.2 | no | https://github.com/openai/openai-python |
20
+ | sentence-transformers | extra `local` | `>=3.0` | Apache-2.0 | 6.1.0 | yes | https://github.com/huggingface/sentence-transformers/ |
21
+ | lancedb | extra `lancedb` | `>=0.15` | Apache-2.0 | 0.39.0 | no | https://github.com/lancedb/lancedb |
22
+ | realtime | extra `relay` | `>=2.31,<2.32` | MIT | 2.31.0 | no | https://github.com/supabase/supabase-py |
23
+ | httpx | extra `relay` | `>=0.27` | BSD-3-Clause | 0.28.1 | no | https://github.com/encode/httpx |
24
+ | cryptography | extra `relay` | `>=42` | Apache-2.0 OR BSD-3-Clause | 50.0.1 | no | https://github.com/pyca/cryptography/ |
25
+
26
+ Notes:
27
+
28
+ - pypdfium2: Its wheel bundles a PDFium binary; the licences of PDFium and the libraries built into it (abseil, FreeType, ICU, libjpeg-turbo, libpng, libtiff, OpenJPEG, zlib and others) ship in that wheel's licenses/ directory.
29
+
30
+ ## Models downloaded at run time (not bundled)
31
+
32
+ | Model | Licence | Source | When |
33
+ |---|---|---|---|
34
+ | BAAI/bge-small-en-v1.5 | MIT | https://huggingface.co/BAAI/bge-small-en-v1.5 | Downloaded from Hugging Face on first use when LOCUS_EMBEDDER=local (the `local` extra). |
@@ -0,0 +1,3 @@
1
+ """Locus — local-first personal AI brain exposed over MCP."""
2
+
3
+ __version__ = "0.1.0"