second-brain-core 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.
Files changed (59) hide show
  1. second_brain_core-0.1.0/.editorconfig +18 -0
  2. second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/bug.yml +32 -0
  3. second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/epic.yml +24 -0
  4. second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/feature.yml +27 -0
  5. second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/spike.yml +25 -0
  6. second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/task.yml +22 -0
  7. second_brain_core-0.1.0/.github/dependabot.yml +16 -0
  8. second_brain_core-0.1.0/.github/labeler.yml +27 -0
  9. second_brain_core-0.1.0/.github/project.yml +41 -0
  10. second_brain_core-0.1.0/.github/workflows/checks.yml +135 -0
  11. second_brain_core-0.1.0/.github/workflows/ci.yml +18 -0
  12. second_brain_core-0.1.0/.github/workflows/labeler.yml +27 -0
  13. second_brain_core-0.1.0/.github/workflows/release.yml +58 -0
  14. second_brain_core-0.1.0/.gitignore +27 -0
  15. second_brain_core-0.1.0/.pre-commit-config.yaml +23 -0
  16. second_brain_core-0.1.0/.python-version +1 -0
  17. second_brain_core-0.1.0/CHANGELOG.md +71 -0
  18. second_brain_core-0.1.0/CONTRIBUTING.md +65 -0
  19. second_brain_core-0.1.0/LICENSE +661 -0
  20. second_brain_core-0.1.0/PKG-INFO +106 -0
  21. second_brain_core-0.1.0/README.md +70 -0
  22. second_brain_core-0.1.0/SECURITY.md +51 -0
  23. second_brain_core-0.1.0/docs/releasing.md +46 -0
  24. second_brain_core-0.1.0/pyproject.toml +100 -0
  25. second_brain_core-0.1.0/scripts/github-release.sh +58 -0
  26. second_brain_core-0.1.0/scripts/smoke.py +103 -0
  27. second_brain_core-0.1.0/src/second_brain_core/__init__.py +32 -0
  28. second_brain_core-0.1.0/src/second_brain_core/annotations.py +15 -0
  29. second_brain_core-0.1.0/src/second_brain_core/audit.py +275 -0
  30. second_brain_core-0.1.0/src/second_brain_core/auth.py +235 -0
  31. second_brain_core-0.1.0/src/second_brain_core/env.py +171 -0
  32. second_brain_core-0.1.0/src/second_brain_core/errors.py +37 -0
  33. second_brain_core-0.1.0/src/second_brain_core/failure.py +87 -0
  34. second_brain_core-0.1.0/src/second_brain_core/health.py +48 -0
  35. second_brain_core-0.1.0/src/second_brain_core/py.typed +0 -0
  36. second_brain_core-0.1.0/src/second_brain_core/recent.py +69 -0
  37. second_brain_core-0.1.0/src/second_brain_core/remote.py +252 -0
  38. second_brain_core-0.1.0/src/second_brain_core/semantic/__init__.py +7 -0
  39. second_brain_core-0.1.0/src/second_brain_core/semantic/chunking.py +48 -0
  40. second_brain_core-0.1.0/src/second_brain_core/semantic/embedders.py +68 -0
  41. second_brain_core-0.1.0/src/second_brain_core/semantic/engine.py +218 -0
  42. second_brain_core-0.1.0/src/second_brain_core/semantic/stores.py +539 -0
  43. second_brain_core-0.1.0/src/second_brain_core/semantic/sync.py +17 -0
  44. second_brain_core-0.1.0/src/second_brain_core/semantic/testing.py +183 -0
  45. second_brain_core-0.1.0/src/second_brain_core/semantic/types.py +130 -0
  46. second_brain_core-0.1.0/src/second_brain_core/server.py +44 -0
  47. second_brain_core-0.1.0/src/second_brain_core/testing.py +57 -0
  48. second_brain_core-0.1.0/tests/fakeserver/__init__.py +14 -0
  49. second_brain_core-0.1.0/tests/fakeserver/app.py +104 -0
  50. second_brain_core-0.1.0/tests/test_audit.py +427 -0
  51. second_brain_core-0.1.0/tests/test_auth.py +353 -0
  52. second_brain_core-0.1.0/tests/test_env.py +196 -0
  53. second_brain_core-0.1.0/tests/test_remote.py +376 -0
  54. second_brain_core-0.1.0/tests/test_semantic_chunking.py +50 -0
  55. second_brain_core-0.1.0/tests/test_semantic_engine.py +246 -0
  56. second_brain_core-0.1.0/tests/test_semantic_stores.py +444 -0
  57. second_brain_core-0.1.0/tests/test_semantic_sync.py +41 -0
  58. second_brain_core-0.1.0/tests/test_server.py +122 -0
  59. second_brain_core-0.1.0/uv.lock +5501 -0
@@ -0,0 +1,18 @@
1
+ root = true
2
+
3
+ [*]
4
+ charset = utf-8
5
+ end_of_line = lf
6
+ insert_final_newline = true
7
+ trim_trailing_whitespace = true
8
+ indent_style = space
9
+ indent_size = 4
10
+
11
+ [*.{yml,yaml,json,toml}]
12
+ indent_size = 2
13
+
14
+ [*.md]
15
+ trim_trailing_whitespace = false
16
+
17
+ [Makefile]
18
+ indent_style = tab
@@ -0,0 +1,32 @@
1
+ name: Bug
2
+ description: An unexpected problem or incorrect behavior
3
+ labels: ["needs-triage"]
4
+ body:
5
+ - type: textarea
6
+ id: description
7
+ attributes:
8
+ label: What happened
9
+ validations:
10
+ required: true
11
+ - type: textarea
12
+ id: expected
13
+ attributes:
14
+ label: What was expected
15
+ validations:
16
+ required: true
17
+ - type: textarea
18
+ id: repro
19
+ attributes:
20
+ label: Steps to reproduce
21
+ validations:
22
+ required: true
23
+ - type: input
24
+ id: version
25
+ attributes:
26
+ label: Package version
27
+ placeholder: "e.g. 0.1.0"
28
+ - type: textarea
29
+ id: env
30
+ attributes:
31
+ label: Environment
32
+ placeholder: "OS, Python version, which server and its version"
@@ -0,0 +1,24 @@
1
+ name: Epic
2
+ description: A large, multi-issue initiative
3
+ labels: ["epic", "needs-triage"]
4
+ body:
5
+ - type: textarea
6
+ id: goal
7
+ attributes:
8
+ label: Goal
9
+ description: What does this epic accomplish when all sub-issues are closed?
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: sub-issues
14
+ attributes:
15
+ label: Sub-issues
16
+ description: List the issues that make up this epic (fill in after filing them).
17
+ placeholder: "- [ ] #1\n- [ ] #2"
18
+ - type: textarea
19
+ id: acceptance
20
+ attributes:
21
+ label: Acceptance criteria
22
+ description: How do we know this epic is done?
23
+ validations:
24
+ required: true
@@ -0,0 +1,27 @@
1
+ name: Feature
2
+ description: A request, idea, or new functionality
3
+ labels: ["needs-triage"]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: Problem / motivation
9
+ description: What problem does this solve, or what need does it address?
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: proposal
14
+ attributes:
15
+ label: Proposed solution
16
+ validations:
17
+ required: true
18
+ - type: textarea
19
+ id: alternatives
20
+ attributes:
21
+ label: Alternatives considered
22
+ - type: textarea
23
+ id: acceptance
24
+ attributes:
25
+ label: Acceptance criteria
26
+ validations:
27
+ required: true
@@ -0,0 +1,25 @@
1
+ name: Spike
2
+ description: A time-boxed investigation that informs follow-on work
3
+ labels: ["needs-triage"]
4
+ body:
5
+ - type: textarea
6
+ id: question
7
+ attributes:
8
+ label: Question to answer
9
+ description: What do we need to know by the end of this spike?
10
+ validations:
11
+ required: true
12
+ - type: input
13
+ id: timebox
14
+ attributes:
15
+ label: Timebox
16
+ placeholder: "e.g. 2 hours, 1 day"
17
+ validations:
18
+ required: true
19
+ - type: textarea
20
+ id: output
21
+ attributes:
22
+ label: Expected output
23
+ description: What artifact or decision does this spike produce?
24
+ validations:
25
+ required: true
@@ -0,0 +1,22 @@
1
+ name: Task
2
+ description: A specific, well-scoped piece of work (including docs and chores)
3
+ labels: ["needs-triage"]
4
+ body:
5
+ - type: textarea
6
+ id: description
7
+ attributes:
8
+ label: What needs to be done
9
+ validations:
10
+ required: true
11
+ - type: textarea
12
+ id: acceptance
13
+ attributes:
14
+ label: Done when
15
+ description: Clear, verifiable definition of done.
16
+ validations:
17
+ required: true
18
+ - type: textarea
19
+ id: notes
20
+ attributes:
21
+ label: Implementation notes
22
+ description: Relevant context, links, or constraints.
@@ -0,0 +1,16 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: "uv"
4
+ directory: "/"
5
+ schedule:
6
+ interval: "weekly"
7
+ labels:
8
+ - "dependencies"
9
+
10
+ - package-ecosystem: "github-actions"
11
+ directory: "/"
12
+ schedule:
13
+ interval: "weekly"
14
+ labels:
15
+ - "dependencies"
16
+ - "github_actions"
@@ -0,0 +1,27 @@
1
+ component:mcp:
2
+ - changed-files:
3
+ - any-glob-to-any-file:
4
+ - src/second_brain_core/*.py
5
+
6
+ component:search:
7
+ - changed-files:
8
+ - any-glob-to-any-file:
9
+ - src/second_brain_core/semantic/**
10
+
11
+ component:docs:
12
+ - changed-files:
13
+ - any-glob-to-any-file:
14
+ - docs/**
15
+ - changed-files:
16
+ - any-glob-to-any-file:
17
+ - "*.md"
18
+ all-globs-to-all-files:
19
+ - "!CONTRIBUTING.md"
20
+
21
+ component:ci:
22
+ - changed-files:
23
+ - any-glob-to-any-file:
24
+ - .github/workflows/**
25
+ - .github/project.yml
26
+ - .github/labeler.yml
27
+ - pyproject.toml
@@ -0,0 +1,41 @@
1
+ # Declarative PM spec for second-brain-core.
2
+ # Applied manually via `gh` CLI or GitHub UI; no automated sync script at this stage.
3
+
4
+ labels:
5
+ # component labels
6
+ - name: "component:mcp"
7
+ color: "0075ca"
8
+ description: "Sign-in, audit log, HTTP serving and the other serving pieces"
9
+ - name: "component:search"
10
+ color: "0075ca"
11
+ description: "The search engine: embeddings, vector and word index"
12
+ - name: "component:docs"
13
+ color: "0075ca"
14
+ description: "Documentation"
15
+ - name: "component:ci"
16
+ color: "0075ca"
17
+ description: "CI/CD and build"
18
+
19
+ # meta labels
20
+ - name: "epic"
21
+ color: "6f42c1"
22
+ description: "Multi-issue initiative"
23
+ - name: "backlog"
24
+ color: "d4c5f9"
25
+ description: "Unscheduled work"
26
+ - name: "needs-triage"
27
+ color: "e11d48"
28
+ description: "Not yet triaged"
29
+ - name: "blocked"
30
+ color: "b60205"
31
+ description: "Blocked by another issue or external dependency"
32
+ - name: "good first issue"
33
+ color: "7057ff"
34
+ description: "Good for newcomers"
35
+ - name: "help wanted"
36
+ color: "008672"
37
+ description: "Extra attention is needed"
38
+
39
+ milestones:
40
+ - title: "v0.1 — First cut"
41
+ description: "The serving pieces both servers share, the client name in the audit line, and the search engine"
@@ -0,0 +1,135 @@
1
+ name: Checks
2
+
3
+ # Reusable quality-gate workflow: lint, type-check, test matrix, and package
4
+ # build/validation. Called by both ci.yml (push/PR) and release.yml (before
5
+ # publish) so nothing ships that has not passed the same gates.
6
+
7
+ on:
8
+ workflow_call:
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ jobs:
14
+ lint:
15
+ name: Lint
16
+ runs-on: ubuntu-latest
17
+ steps:
18
+ - uses: actions/checkout@v7
19
+ - uses: astral-sh/setup-uv@v7
20
+ with:
21
+ enable-cache: true
22
+ - name: Cache pre-commit environments
23
+ uses: actions/cache@v6
24
+ with:
25
+ path: ~/.cache/pre-commit
26
+ key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
27
+ - name: Run pre-commit (ruff lint + format)
28
+ run: uvx pre-commit run --all-files --show-diff-on-failure
29
+
30
+ typecheck:
31
+ name: Type check
32
+ runs-on: ubuntu-latest
33
+ steps:
34
+ - uses: actions/checkout@v7
35
+ - uses: astral-sh/setup-uv@v7
36
+ with:
37
+ enable-cache: true
38
+ - name: Install dependencies
39
+ run: uv sync --locked
40
+ - name: Run mypy
41
+ run: uv run mypy
42
+
43
+ test:
44
+ name: Test (Python ${{ matrix.python-version }})
45
+ runs-on: ubuntu-latest
46
+ strategy:
47
+ matrix:
48
+ python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
49
+ steps:
50
+ - uses: actions/checkout@v7
51
+ - uses: astral-sh/setup-uv@v7
52
+ with:
53
+ enable-cache: true
54
+ python-version: ${{ matrix.python-version }}
55
+ - name: Install dependencies
56
+ run: uv sync --locked
57
+ - name: Run tests (with 90% coverage gate)
58
+ run: uv run pytest --cov-fail-under=90 --tb=short
59
+
60
+ # The Chroma store needs chromadb, which is too heavy for every job and has no
61
+ # build for Python 3.15 yet: its tests run here, with the sqlite-vec ones.
62
+ test-chroma:
63
+ name: Test (Chroma store, Python 3.13)
64
+ runs-on: ubuntu-latest
65
+ steps:
66
+ - uses: actions/checkout@v7
67
+ - uses: astral-sh/setup-uv@v7
68
+ with:
69
+ enable-cache: true
70
+ python-version: "3.13"
71
+ - name: Install dependencies
72
+ run: uv sync --locked
73
+ - name: Run the store tests with chromadb installed
74
+ run: uv run --with "chromadb>=0.5" pytest tests/test_semantic_stores.py --no-cov --tb=short
75
+
76
+ # The servers built on this library run on macOS in production and are
77
+ # installed on Windows too, so both get the test suite and then the smoke test
78
+ # of the wheel the build job made (see `build`). One job per system does both,
79
+ # because macOS runners are scarce: a second macOS job waits in the queue a
80
+ # second time. A separate job from the Linux matrix keeps that matrix's check
81
+ # names unchanged.
82
+ test-os:
83
+ name: Test (${{ matrix.name }}, Python 3.13)
84
+ needs: build
85
+ runs-on: ${{ matrix.os }}
86
+ strategy:
87
+ fail-fast: false
88
+ matrix:
89
+ include:
90
+ - { os: macos-latest, name: macOS }
91
+ - { os: windows-latest, name: Windows }
92
+ steps:
93
+ - uses: actions/checkout@v7
94
+ - uses: astral-sh/setup-uv@v7
95
+ with:
96
+ enable-cache: true
97
+ python-version: "3.13"
98
+ - name: Install dependencies
99
+ run: uv sync --locked
100
+ - name: Run tests (with 90% coverage gate)
101
+ run: uv run pytest --cov-fail-under=90 --tb=short
102
+ - name: Download the built wheel
103
+ uses: actions/download-artifact@v8
104
+ with:
105
+ name: dist
106
+ path: dist
107
+ - name: Smoke-test the built wheel (a fresh install, then a server built on it)
108
+ shell: bash
109
+ run: uv run scripts/smoke.py --from ./dist/*.whl
110
+
111
+ # Builds the package, installs the wheel in a fresh environment the way a
112
+ # server's install does, and builds a small server on it (scripts/smoke.py).
113
+ # Dependencies resolve fresh from PyPI, as they do for a server. The same wheel
114
+ # gets the same smoke test on macOS and Windows in `test-os`.
115
+ build:
116
+ name: Build and validate package
117
+ runs-on: ubuntu-latest
118
+ steps:
119
+ - uses: actions/checkout@v7
120
+ - uses: astral-sh/setup-uv@v7
121
+ with:
122
+ enable-cache: true
123
+ python-version: "3.13"
124
+ - name: Build sdist and wheel
125
+ run: uv build
126
+ - name: Validate metadata
127
+ run: uvx twine check dist/*
128
+ - name: Smoke-test the built wheel (a fresh install, then a server built on it)
129
+ run: uv run scripts/smoke.py --from ./dist/*.whl
130
+ - name: Upload distributions
131
+ uses: actions/upload-artifact@v7
132
+ with:
133
+ name: dist
134
+ path: dist/
135
+ retention-days: 1
@@ -0,0 +1,18 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ concurrency:
10
+ group: ci-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ checks:
18
+ uses: ./.github/workflows/checks.yml
@@ -0,0 +1,27 @@
1
+ name: Labeler
2
+
3
+ # Applies component:* labels to PRs from the path rules in .github/labeler.yml.
4
+ # Runs on pull_request_target so it has a write-scoped token even for fork PRs;
5
+ # labeler only reads the changed-file list via the API and never checks out or
6
+ # runs PR code, so this is safe. See docs/project-management.md.
7
+
8
+ on:
9
+ pull_request_target:
10
+ types: [opened, synchronize, reopened]
11
+
12
+ concurrency:
13
+ group: labeler-${{ github.event.pull_request.number }}
14
+ cancel-in-progress: true
15
+
16
+ permissions:
17
+ contents: read
18
+ pull-requests: write
19
+
20
+ jobs:
21
+ label:
22
+ name: Apply component labels
23
+ runs-on: ubuntu-latest
24
+ steps:
25
+ - uses: actions/labeler@v7
26
+ with:
27
+ sync-labels: false # add-only; never strip maintainer-applied labels
@@ -0,0 +1,58 @@
1
+ name: Release (PyPI)
2
+
3
+ # Runs the full check suite (lint, type-check, test matrix, build) on the tagged
4
+ # commit, then publishes the *tested* artifact to PyPI via an OIDC trusted
5
+ # publisher (no stored token), then creates the GitHub Release for the tag. The
6
+ # trusted publisher is registered on https://pypi.org for the
7
+ # `second-brain-tools/second-brain-core` repo, environment `pypi`. A red check
8
+ # blocks the publish. See docs/releasing.md.
9
+
10
+ on:
11
+ push:
12
+ tags: ["v*"]
13
+ workflow_dispatch:
14
+
15
+ jobs:
16
+ checks:
17
+ uses: ./.github/workflows/checks.yml
18
+
19
+ publish:
20
+ name: Publish to PyPI
21
+ needs: checks
22
+ runs-on: ubuntu-latest
23
+ environment: pypi
24
+ permissions:
25
+ id-token: write # required for OIDC trusted publishing
26
+ steps:
27
+ - name: Download built distributions
28
+ uses: actions/download-artifact@v8
29
+ with:
30
+ name: dist
31
+ path: dist
32
+ - name: Publish to PyPI
33
+ uses: pypa/gh-action-pypi-publish@release/v1
34
+ with:
35
+ skip-existing: true
36
+
37
+ # The GitHub Release for the tag, after PyPI so it never announces a version
38
+ # that failed to publish. Notes come from the version's CHANGELOG.md section and
39
+ # the tested sdist + wheel are attached. Re-running updates it in place.
40
+ github-release:
41
+ name: GitHub Release
42
+ needs: publish
43
+ if: startsWith(github.ref, 'refs/tags/v')
44
+ runs-on: ubuntu-latest
45
+ permissions:
46
+ contents: write # create the release and upload its assets
47
+ steps:
48
+ - uses: actions/checkout@v7
49
+ - name: Download built distributions
50
+ uses: actions/download-artifact@v8
51
+ with:
52
+ name: dist
53
+ path: dist
54
+ - name: Create or update the release
55
+ env:
56
+ GH_TOKEN: ${{ github.token }}
57
+ TAG: ${{ github.ref_name }}
58
+ run: scripts/github-release.sh "$TAG" dist/*
@@ -0,0 +1,27 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .venv/
8
+ .env
9
+
10
+ # Ruff / mypy / pytest cache
11
+ .ruff_cache/
12
+ .mypy_cache/
13
+ .pytest_cache/
14
+ .coverage
15
+ htmlcov/
16
+
17
+ # Search indexes written by tests or by hand
18
+ index.db
19
+ *.sqlite
20
+
21
+ # macOS
22
+ .DS_Store
23
+
24
+ # Editor
25
+ .idea/
26
+ .vscode/
27
+ *.swp
@@ -0,0 +1,23 @@
1
+ # Run `uv run pre-commit install` once to enable these on every commit.
2
+ # This config is the authoritative lint gate: CI runs `pre-commit run --all-files`
3
+ # (see .github/workflows/checks.yml), so the ruff version pinned here is the one
4
+ # that gates the project.
5
+ repos:
6
+ - repo: https://github.com/astral-sh/ruff-pre-commit
7
+ rev: v0.17.5
8
+ hooks:
9
+ - id: ruff-check
10
+ args: [--fix]
11
+ - id: ruff-format
12
+ - repo: https://github.com/pre-commit/pre-commit-hooks
13
+ rev: v6.0.0
14
+ hooks:
15
+ - id: end-of-file-fixer
16
+ - id: trailing-whitespace
17
+ args: [--markdown-linebreak-ext=md]
18
+ - id: check-yaml
19
+ - id: check-toml
20
+ - repo: https://github.com/rhysd/actionlint
21
+ rev: v1.7.12
22
+ hooks:
23
+ - id: actionlint
@@ -0,0 +1 @@
1
+ 3.11
@@ -0,0 +1,71 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format is based on
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Until 1.0, a minor version
6
+ may change the interfaces.
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.1.0] — First cut
11
+
12
+ The serving pieces the Second Brain servers shared as copies, written once: sign-in,
13
+ the audit log (now naming the client), HTTP serving and its guardrails, the settings
14
+ files, the error a client sees, and the security checks each server runs on itself.
15
+ With the `semantic` extra, the search engine, by meaning and by words.
16
+
17
+ ### Added
18
+
19
+ - **The shared serving pieces of the Second Brain servers**, moved here from
20
+ second-brain-joplin and second-brain-imap, which carried copies of them
21
+ (second-brain-joplin #91):
22
+ - `Server`, the description every piece takes, so nothing here names a product;
23
+ - `env`: a named env file *or* a checkout's `.env`, never both, and readers that
24
+ never raise: a bad value reads as `None`, for the server to record and refuse;
25
+ - `auth`: GitHub sign-in with an allow-list of numeric ids;
26
+ - `audit`: the audit line, naming a server's own failures by class; the per-caller
27
+ rate limit; the logging set-up;
28
+ - `remote` and `health`: HTTP options and guardrails, the transport choice, the
29
+ middleware stack, the run calls, and `/healthz` with an optional cache;
30
+ - `failure`: a planned failure's sentence, or a fixed one for anything else, and
31
+ `guarded`, a tool decorator so nothing unplanned escapes a tool;
32
+ - `recent` and `annotations`;
33
+ - `testing`: the security regression checks each server runs on itself.
34
+ - **The audit line names the client** (`client=`; second-brain-joplin #92): the name
35
+ it registered under at sign-in, else the name it gives in the MCP handshake (or in
36
+ each request, on protocols without one), else the first word of its `User-Agent`,
37
+ else `unknown`. Letters, digits and `._/-` only, at most 40 characters, so a hostile
38
+ value can't break or forge a line. It is what the client says about itself: a hint
39
+ for the operator, never proof, and nothing is decided by it. `this_calls_client()`
40
+ gives it to a line a tool logs itself. The tool's name (`tool=`) is cleaned the same
41
+ way, since a client can ask for any name.
42
+ - **The search engine, as the `semantic` extra** (second-brain-joplin #93), moved here
43
+ from second-brain-joplin so the mail server can search by meaning too:
44
+ - `Engine` keeps an index in step with a server's `Source` (its items, their versions,
45
+ which are visible) and searches it. A hidden item never reaches a result: with a
46
+ filter active, every search asks the source what is visible now, whatever the
47
+ index holds.
48
+ - Neutral names (`item_id`, `version`). An index file from second-brain-joplin 1.2 is
49
+ migrated in place, in one transaction, keeping every vector (sqlite-vec); a Chroma
50
+ index from then is rebuilt by itself.
51
+ - The index file records its layout's version, the server that owns it (a second
52
+ server pointed at the same directory is refused, naming the variable, not the path:
53
+ each sync would delete the other's items), and the vectors' width (a new width under the same model name now
54
+ rebuilds the index).
55
+ - **A word index beside the vectors** (sqlite-vec): SQLite FTS5, ignoring case and
56
+ accents; a word hyphenated across a line break is found joined and as written.
57
+ `Engine.word_search` applies the same visibility rule. The Chroma store says plainly
58
+ that it has no word search, and so does a SQLite built without FTS5.
59
+ - An index directory is made private (0700) and the index file 0600, ones made
60
+ before included; a full rebuild's reset is one transaction, so an interrupted
61
+ rebuild leaves the index as it was.
62
+ - `semantic.testing`: in-memory stand-ins (embedder, index, an index another process
63
+ writes to, a source) for any server's tests.
64
+ - **FastMCP's "Error calling tool" log line loses its traceback** in HTTP mode. When an
65
+ exception escaped a tool, FastMCP logged it with the exception's text, which can quote
66
+ what was being processed. `configure_logging` (HTTP mode's log set-up) now drops the
67
+ traceback and keeps the line; on stdio, `guarded` keeps such an exception from
68
+ escaping in the first place.
69
+
70
+ [Unreleased]: https://github.com/second-brain-tools/second-brain-core/compare/v0.1.0...HEAD
71
+ [0.1.0]: https://github.com/second-brain-tools/second-brain-core/releases/tag/v0.1.0
@@ -0,0 +1,65 @@
1
+ # Contributing
2
+
3
+ Thanks for your interest in second-brain-core.
4
+
5
+ **Shared code is fixed here, not in a server.** Fix it here, release, then move each
6
+ server's pin; a server that carries its own copy of a fix is how the copies drifted
7
+ apart before this library existed.
8
+
9
+ ## Development setup
10
+
11
+ We use [uv](https://docs.astral.sh/uv/):
12
+
13
+ ```bash
14
+ git clone https://github.com/second-brain-tools/second-brain-core
15
+ cd second-brain-core
16
+ uv sync
17
+ uv run pre-commit install # enable lint/format on commit
18
+ ```
19
+
20
+ To try a change in a server before it is released, point the server's checkout at
21
+ yours for the moment, and don't commit it:
22
+
23
+ ```toml
24
+ # in the server's pyproject.toml, locally only
25
+ [tool.uv.sources]
26
+ second-brain-core = { path = "../second-brain-core", editable = true }
27
+ ```
28
+
29
+ ## Running tests
30
+
31
+ ```bash
32
+ uv run pytest --cov-fail-under=90
33
+ ```
34
+
35
+ The tests run against a small fake server (`tests/fakeserver`) under two variable
36
+ prefixes, so nothing is tied to one server's names. Coverage is printed on every run;
37
+ the 90 % gate is enforced in CI.
38
+
39
+ ## Linting and type checking
40
+
41
+ ```bash
42
+ uvx pre-commit run --all-files # ruff lint + format + actionlint (the authoritative gate)
43
+ uv run mypy # strict, over src, tests and scripts
44
+ ```
45
+
46
+ ## How CI works
47
+
48
+ [`.github/workflows/checks.yml`](.github/workflows/checks.yml) holds every gate:
49
+ lint, type check, tests on Python 3.11 to 3.15 on Linux and on 3.13 on macOS and
50
+ Windows, and a build with `twine check`. The built wheel is then installed in a
51
+ fresh environment and used ([`scripts/smoke.py`](scripts/smoke.py)) on all three
52
+ systems. [`ci.yml`](.github/workflows/ci.yml) runs it on every push and pull request,
53
+ and [`release.yml`](.github/workflows/release.yml) before publishing.
54
+
55
+ ## License of contributions
56
+
57
+ AGPL-3.0-or-later ([LICENSE](LICENSE)). By opening a pull request you agree to that.
58
+ A sign-off (`git commit -s`) says you have the right to submit the change under those
59
+ terms ([Developer Certificate of Origin](https://developercertificate.org/)).
60
+
61
+ ## Pull requests
62
+
63
+ - Target `main`; the PR title is a lower-case conventional commit (`fix: …`).
64
+ - One logical change per PR, with tests and a CHANGELOG entry.
65
+ - CI must pass before merge. Merges are squashed.