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.
- second_brain_core-0.1.0/.editorconfig +18 -0
- second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/bug.yml +32 -0
- second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/epic.yml +24 -0
- second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/feature.yml +27 -0
- second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/spike.yml +25 -0
- second_brain_core-0.1.0/.github/ISSUE_TEMPLATE/task.yml +22 -0
- second_brain_core-0.1.0/.github/dependabot.yml +16 -0
- second_brain_core-0.1.0/.github/labeler.yml +27 -0
- second_brain_core-0.1.0/.github/project.yml +41 -0
- second_brain_core-0.1.0/.github/workflows/checks.yml +135 -0
- second_brain_core-0.1.0/.github/workflows/ci.yml +18 -0
- second_brain_core-0.1.0/.github/workflows/labeler.yml +27 -0
- second_brain_core-0.1.0/.github/workflows/release.yml +58 -0
- second_brain_core-0.1.0/.gitignore +27 -0
- second_brain_core-0.1.0/.pre-commit-config.yaml +23 -0
- second_brain_core-0.1.0/.python-version +1 -0
- second_brain_core-0.1.0/CHANGELOG.md +71 -0
- second_brain_core-0.1.0/CONTRIBUTING.md +65 -0
- second_brain_core-0.1.0/LICENSE +661 -0
- second_brain_core-0.1.0/PKG-INFO +106 -0
- second_brain_core-0.1.0/README.md +70 -0
- second_brain_core-0.1.0/SECURITY.md +51 -0
- second_brain_core-0.1.0/docs/releasing.md +46 -0
- second_brain_core-0.1.0/pyproject.toml +100 -0
- second_brain_core-0.1.0/scripts/github-release.sh +58 -0
- second_brain_core-0.1.0/scripts/smoke.py +103 -0
- second_brain_core-0.1.0/src/second_brain_core/__init__.py +32 -0
- second_brain_core-0.1.0/src/second_brain_core/annotations.py +15 -0
- second_brain_core-0.1.0/src/second_brain_core/audit.py +275 -0
- second_brain_core-0.1.0/src/second_brain_core/auth.py +235 -0
- second_brain_core-0.1.0/src/second_brain_core/env.py +171 -0
- second_brain_core-0.1.0/src/second_brain_core/errors.py +37 -0
- second_brain_core-0.1.0/src/second_brain_core/failure.py +87 -0
- second_brain_core-0.1.0/src/second_brain_core/health.py +48 -0
- second_brain_core-0.1.0/src/second_brain_core/py.typed +0 -0
- second_brain_core-0.1.0/src/second_brain_core/recent.py +69 -0
- second_brain_core-0.1.0/src/second_brain_core/remote.py +252 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/__init__.py +7 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/chunking.py +48 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/embedders.py +68 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/engine.py +218 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/stores.py +539 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/sync.py +17 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/testing.py +183 -0
- second_brain_core-0.1.0/src/second_brain_core/semantic/types.py +130 -0
- second_brain_core-0.1.0/src/second_brain_core/server.py +44 -0
- second_brain_core-0.1.0/src/second_brain_core/testing.py +57 -0
- second_brain_core-0.1.0/tests/fakeserver/__init__.py +14 -0
- second_brain_core-0.1.0/tests/fakeserver/app.py +104 -0
- second_brain_core-0.1.0/tests/test_audit.py +427 -0
- second_brain_core-0.1.0/tests/test_auth.py +353 -0
- second_brain_core-0.1.0/tests/test_env.py +196 -0
- second_brain_core-0.1.0/tests/test_remote.py +376 -0
- second_brain_core-0.1.0/tests/test_semantic_chunking.py +50 -0
- second_brain_core-0.1.0/tests/test_semantic_engine.py +246 -0
- second_brain_core-0.1.0/tests/test_semantic_stores.py +444 -0
- second_brain_core-0.1.0/tests/test_semantic_sync.py +41 -0
- second_brain_core-0.1.0/tests/test_server.py +122 -0
- 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.
|