holder-kit 0.0.2__tar.gz → 0.2.5__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 (90) hide show
  1. {holder_kit-0.0.2 → holder_kit-0.2.5}/.gitignore +0 -1
  2. holder_kit-0.2.5/AGENTS.md +20 -0
  3. {holder_kit-0.0.2 → holder_kit-0.2.5}/CMakeLists.txt +1 -1
  4. {holder_kit-0.0.2 → holder_kit-0.2.5}/PKG-INFO +38 -23
  5. holder_kit-0.2.5/README.md +111 -0
  6. holder_kit-0.2.5/docs/building.md +128 -0
  7. {holder_kit-0.0.2 → holder_kit-0.2.5}/docs/development.md +39 -8
  8. {holder_kit-0.0.2 → holder_kit-0.2.5}/docs/packaging.md +41 -64
  9. holder_kit-0.2.5/docs/publication.md +100 -0
  10. {holder_kit-0.0.2 → holder_kit-0.2.5}/docs/record-contracts.md +172 -6
  11. holder_kit-0.2.5/docs/storage.md +142 -0
  12. holder_kit-0.2.5/docs/walkthrough.md +247 -0
  13. holder_kit-0.2.5/docs/which_holder_python_api.png +0 -0
  14. holder_kit-0.2.5/examples/card_lifecycle.py +31 -0
  15. holder_kit-0.2.5/examples/finish_project.py +34 -0
  16. holder_kit-0.2.5/examples/make_project.py +16 -0
  17. holder_kit-0.2.5/examples/reopen_project.py +25 -0
  18. {holder_kit-0.0.2 → holder_kit-0.2.5}/packaging/linux/debian/control +7 -1
  19. {holder_kit-0.0.2 → holder_kit-0.2.5}/packaging/linux/debian/copyright +1 -1
  20. {holder_kit-0.0.2 → holder_kit-0.2.5}/packaging/linux/debian/rules +6 -0
  21. {holder_kit-0.0.2 → holder_kit-0.2.5}/pyproject.toml +2 -2
  22. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/check-release-distributions.py +12 -7
  23. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/develop.py +42 -132
  24. holder_kit-0.2.5/scripts/licenses/microsoft-runtime.txt +36 -0
  25. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/pypi_readme.py +5 -2
  26. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/test-installed-debian.py +6 -0
  27. holder_kit-0.2.5/scripts/test-installed-wheel.py +114 -0
  28. holder_kit-0.2.5/scripts/ubuntu-package-ci.sh +23 -0
  29. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/wheel-notices.py +5 -21
  30. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/__init__.py +15 -3
  31. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/_native.pyi +13 -0
  32. holder_kit-0.2.5/src/holderkit/_publication.py +168 -0
  33. holder_kit-0.2.5/src/holderkit/_storage.py +433 -0
  34. holder_kit-0.2.5/src/holderkit/card_collections.py +133 -0
  35. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/collections.py +12 -10
  36. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/data/__init__.py +3 -2
  37. holder_kit-0.2.5/src/holderkit/data/card.py +317 -0
  38. holder_kit-0.2.5/src/holderkit/data/project.py +403 -0
  39. holder_kit-0.2.5/src/holderkit/project_collections.py +337 -0
  40. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/native/module.c +206 -0
  41. holder_kit-0.2.5/tests/test_card_batches.py +253 -0
  42. holder_kit-0.2.5/tests/test_card_collections.py +205 -0
  43. holder_kit-0.2.5/tests/test_card_movement.py +119 -0
  44. holder_kit-0.2.5/tests/test_card_navigation.py +138 -0
  45. {holder_kit-0.0.2 → holder_kit-0.2.5}/tests/test_graph.py +2 -1
  46. {holder_kit-0.0.2 → holder_kit-0.2.5}/tests/test_holder.py +6 -7
  47. holder_kit-0.2.5/tests/test_live_cards.py +197 -0
  48. {holder_kit-0.0.2 → holder_kit-0.2.5}/tests/test_make.py +49 -87
  49. {holder_kit-0.0.2 → holder_kit-0.2.5}/tests/test_pandas.py +4 -2
  50. holder_kit-0.2.5/tests/test_projects.py +818 -0
  51. holder_kit-0.0.2/.github/actions/core-sdk/action.yml +0 -21
  52. holder_kit-0.0.2/.github/workflows/ci.yml +0 -325
  53. holder_kit-0.0.2/.github/workflows/launchpad.yml +0 -79
  54. holder_kit-0.0.2/.github/workflows/release.yml +0 -248
  55. holder_kit-0.0.2/.github/workflows/ubuntu-packages.yml +0 -47
  56. holder_kit-0.0.2/README.md +0 -96
  57. holder_kit-0.0.2/core-source.json +0 -4
  58. holder_kit-0.0.2/docs/building.md +0 -171
  59. holder_kit-0.0.2/docs/walkthrough.md +0 -125
  60. holder_kit-0.0.2/examples/card_lifecycle.py +0 -34
  61. holder_kit-0.0.2/release-core.json +0 -5
  62. holder_kit-0.0.2/scripts/configure-holder-ppa.sh +0 -14
  63. holder_kit-0.0.2/scripts/core-sdk.py +0 -17
  64. holder_kit-0.0.2/scripts/prepare-debian-source.py +0 -54
  65. holder_kit-0.0.2/scripts/test-installed-wheel.py +0 -48
  66. holder_kit-0.0.2/scripts/ubuntu-package-ci.sh +0 -40
  67. holder_kit-0.0.2/src/holderkit/data/card.py +0 -166
  68. holder_kit-0.0.2/src/holderkit/data/project.py +0 -96
  69. {holder_kit-0.0.2 → holder_kit-0.2.5}/LICENSE +0 -0
  70. {holder_kit-0.0.2 → holder_kit-0.2.5}/docs/workflow.png +0 -0
  71. {holder_kit-0.0.2 → holder_kit-0.2.5}/examples/detached_records.py +0 -0
  72. {holder_kit-0.0.2 → holder_kit-0.2.5}/examples/graph_analysis.py +0 -0
  73. {holder_kit-0.0.2 → holder_kit-0.2.5}/examples/milestone_analysis.py +0 -0
  74. {holder_kit-0.0.2 → holder_kit-0.2.5}/examples/pandas_analysis.py +0 -0
  75. {holder_kit-0.0.2 → holder_kit-0.2.5}/examples/tag_analysis.py +0 -0
  76. {holder_kit-0.0.2 → holder_kit-0.2.5}/make.sh +0 -0
  77. {holder_kit-0.0.2 → holder_kit-0.2.5}/packaging/linux/debian/changelog +0 -0
  78. {holder_kit-0.0.2 → holder_kit-0.2.5}/packaging/linux/debian/source/format +0 -0
  79. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/__init__.py +0 -0
  80. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/repair-linux-wheel.py +0 -0
  81. {holder_kit-0.0.2 → holder_kit-0.2.5}/scripts/system-core-build-info.py +0 -0
  82. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/data/connection.py +0 -0
  83. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/data/milestone.py +0 -0
  84. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/data/tag.py +0 -0
  85. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/dataframe.py +0 -0
  86. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/graph.py +0 -0
  87. {holder_kit-0.0.2 → holder_kit-0.2.5}/src/holderkit/py.typed +0 -0
  88. {holder_kit-0.0.2 → holder_kit-0.2.5}/tests/test_connections.py +0 -0
  89. {holder_kit-0.0.2 → holder_kit-0.2.5}/tests/test_milestones.py +0 -0
  90. {holder_kit-0.0.2 → holder_kit-0.2.5}/tests/test_tags.py +0 -0
@@ -4,7 +4,6 @@
4
4
  **/__pycache__/
5
5
  *.egg-info/
6
6
  *.so
7
- /.core-sdk/
8
7
  /out/
9
8
  /dist/
10
9
  /debian/
@@ -0,0 +1,20 @@
1
+ # Coding-agent instructions
2
+
3
+ Holder Kit is the CPython binding over libholder: `src/native/module.c` wraps core's C API and
4
+ `src/holderkit` is the Python layer over it. Reusable storage and domain behaviour belongs in core
5
+ (`../../core`), not here; Kit exposes it to Python.
6
+
7
+ # Core
8
+
9
+ Core lives in `../../core` in this repository. Make core changes there, with core's own tests, in
10
+ the same pull request as the Kit changes that need them.
11
+
12
+ Kit uses only core's stable C API (`#include <holder/holder.h>`), through what core installs: that
13
+ header, the `holder` CMake package and the schema. Do not include core's other headers, and do not
14
+ refer to files in `../../core` by path from Kit's code, CMake or scripts. CI enforces this: it builds
15
+ Kit against the SDK that `Core / SDK` builds from `core/` in the same commit, and a boundary check
16
+ rejects other core headers and paths into core.
17
+
18
+ `./make.sh` builds `../../core` from source with Kit for local development (or
19
+ `HOLDER_KIT_CORE_SOURCE`). `./make.sh --sdk` with `HOLDER_CORE_SDK` builds against a prepared SDK
20
+ instead.
@@ -45,7 +45,7 @@ elseif(HOLDER_KIT_CORE_SOURCE)
45
45
  set(holder_schema "${HOLDER_KIT_CORE_SOURCE}/schema/schema.sql")
46
46
  else()
47
47
  if(NOT EXISTS "${HOLDER_CORE_SDK}/libholder-manifest.json")
48
- message(FATAL_ERROR "Missing core SDK. Run scripts/core-sdk.py resolve and fetch, then set HOLDER_CORE_SDK. No automatic source fallback is available.")
48
+ message(FATAL_ERROR "Missing core SDK. Set HOLDER_CORE_SDK to a prepared core SDK, or set HOLDER_KIT_CORE_SOURCE to build core from source (./make.sh uses ../../core).")
49
49
  endif()
50
50
  set(holder_DIR "${HOLDER_CORE_SDK}/lib/cmake/holder" CACHE PATH "Selected core CMake package" FORCE)
51
51
  find_package(holder CONFIG REQUIRED PATHS "${holder_DIR}" NO_DEFAULT_PATH)
@@ -1,9 +1,9 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: holder-kit
3
- Version: 0.0.2
3
+ Version: 0.2.5
4
4
  Summary: Holder Kit: CPython bindings for embedded libholder
5
5
  License-Expression: GPL-3.0-only
6
- Project-URL: Repository, https://github.com/HolderTeam/holder-kit
6
+ Project-URL: Repository, https://github.com/HolderTeam/holder/tree/main/python/kit
7
7
  Requires-Python: >=3.10
8
8
  Provides-Extra: test
9
9
  Requires-Dist: mypy>=1.15; extra == "test"
@@ -39,7 +39,7 @@ The base package exposes ordinary Python records and has no data-science depende
39
39
 
40
40
  A typical workflow looks like this:
41
41
 
42
- ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder-kit/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/workflow.png)
42
+ ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/workflow.png)
43
43
 
44
44
  1. You make a new project, or clone an existing one.
45
45
  2. You do work and analysis.
@@ -50,19 +50,32 @@ A typical workflow looks like this:
50
50
  ```python
51
51
  import holderkit
52
52
 
53
- with holderkit.open("./knowledge") as holder:
54
- project = holder.create_project("Research")
55
-
56
- card = holder.create_card(
57
- project.project_id,
53
+ with holderkit.create("Research") as project:
54
+ card = project.create_card(
58
55
  "Interesting question",
59
56
  "Something worth investigating.",
60
57
  )
61
58
 
62
- print(card.title)
59
+ print(project.cards.to_records(include_content=True))
63
60
  ```
64
61
 
65
- Follow the [walkthrough](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/walkthrough.md) to create connected cards, add tags
62
+ Or clone an existing Holder project and explore its cards:
63
+
64
+ ```python
65
+ with holderkit.clone("git@example.org:research.git") as project:
66
+ for card in project.cards.to_records(include_content=True):
67
+ print(card["title"], card["content"])
68
+ ```
69
+
70
+ Replace the example URL with your project's Git remote. Holder Kit chooses
71
+ local storage automatically. These examples need Git installed.
72
+
73
+ When your experiment is ready, publish it while the project is open with
74
+ `project.push(remote_url="git@example.org:research.git", branch="experiments/results")`.
75
+ Use `project.close()` to keep your work, or `project.discard(confirm=True)` to
76
+ remove it locally. See [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md).
77
+
78
+ Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md) to create connected cards, add tags
66
79
  and milestones, and analyse detached records with pandas and NetworkX.
67
80
 
68
81
  ## Installation
@@ -71,7 +84,7 @@ Holder Kit is currently in early development.
71
84
 
72
85
  The Python distribution is named `holder-kit` and the import package is `holderkit`.
73
86
 
74
- See [Building Holder Kit](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/building.md) for installing the current version from source.
87
+ See [Building Holder Kit](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md) for installing the current version from source.
75
88
 
76
89
  Ubuntu packages are also available as `python3-holder-kit` for supported Holder package repositories.
77
90
 
@@ -82,11 +95,10 @@ the Python process. This makes it suitable for scripts, notebooks, data analysis
82
95
  and applications that want to embed Holder functionality.
83
96
 
84
97
  To control a running Holder installation through the Framework API, use
85
- [holder-python](https://github.com/HolderTeam/holder-python).
98
+ [holder-python](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/holder).
86
99
 
87
- Holder Kit is versioned independently from the
88
- [Holder Framework](https://github.com/HolderTeam/holder-framework) and
89
- [core library](https://github.com/HolderTeam/holder-core).
100
+ Holder Kit is part of [Holder](https://github.com/HolderTeam/holder) and is
101
+ released with it, at the same version.
90
102
 
91
103
  ## Examples
92
104
 
@@ -97,17 +109,20 @@ The repository includes examples covering:
97
109
  - pandas analysis;
98
110
  - connection graphs;
99
111
  - tag analysis;
100
- - milestone and calendar analysis.
112
+ - milestone and calendar analysis;
113
+ - creating projects, retaining local edits and explicitly finishing an experiment.
101
114
 
102
- See the [`examples/`](https://github.com/HolderTeam/holder-kit/tree/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/examples) directory.
115
+ See the [`examples/`](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/examples) directory.
103
116
 
104
117
  ## Documentation
105
118
 
106
- - [Walkthrough](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/walkthrough.md)
107
- - [Detached record contracts](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/record-contracts.md)
108
- - [Building from source](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/building.md)
109
- - [Development](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/development.md)
110
- - [Packaging](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/packaging.md)
119
+ - [Walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md)
120
+ - [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md)
121
+ - [Detached record contracts](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/record-contracts.md)
122
+ - [Advanced: storage and reopening](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/storage.md)
123
+ - [Building from source](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md)
124
+ - [Development](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/development.md)
125
+ - [Packaging](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/packaging.md)
111
126
 
112
127
  ## Status
113
128
 
@@ -115,4 +130,4 @@ Holder Kit is under active development. The current API covers projects, cards,
115
130
 
116
131
  ## Licence
117
132
 
118
- See [LICENSE](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/LICENSE).
133
+ See [LICENSE](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/LICENSE).
@@ -0,0 +1,111 @@
1
+ # Holder Kit
2
+
3
+ **Analyse, transform and import Holder data with Python.**
4
+
5
+ Holder Kit gives Python programs direct access to Holder projects, cards, connections, tags and milestones.
6
+
7
+ Typical uses include:
8
+
9
+ - **Data analysis** — load Holder data into pandas and explore it with familiar Python tools.
10
+ - **Bulk import and transformation** — create or modify large collections of cards programmatically.
11
+ - **Machine learning** — extract Holder content for classification, clustering, embeddings, ranking and other experiments.
12
+ - **Graph analysis** — export explicit connections between cards to NetworkX.
13
+ - **Dataset and corpus preparation** — turn a Holder knowledge base into structured Python records for further processing.
14
+ - **Offline automation** — perform maintenance, migration and batch operations without running the Holder daemon.
15
+
16
+ The base package exposes ordinary Python records and has no data-science dependencies. pandas and NetworkX integrations are available as optional extras.
17
+
18
+ A typical workflow looks like this:
19
+
20
+ ![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/workflow.png)
21
+
22
+ 1. You make a new project, or clone an existing one.
23
+ 2. You do work and analysis.
24
+ 3. You push your experiment, or discard it.
25
+
26
+ ## A first example
27
+
28
+ ```python
29
+ import holderkit
30
+
31
+ with holderkit.create("Research") as project:
32
+ card = project.create_card(
33
+ "Interesting question",
34
+ "Something worth investigating.",
35
+ )
36
+
37
+ print(project.cards.to_records(include_content=True))
38
+ ```
39
+
40
+ Or clone an existing Holder project and explore its cards:
41
+
42
+ ```python
43
+ with holderkit.clone("git@example.org:research.git") as project:
44
+ for card in project.cards.to_records(include_content=True):
45
+ print(card["title"], card["content"])
46
+ ```
47
+
48
+ Replace the example URL with your project's Git remote. Holder Kit chooses
49
+ local storage automatically. These examples need Git installed.
50
+
51
+ When your experiment is ready, publish it while the project is open with
52
+ `project.push(remote_url="git@example.org:research.git", branch="experiments/results")`.
53
+ Use `project.close()` to keep your work, or `project.discard(confirm=True)` to
54
+ remove it locally. See [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md).
55
+
56
+ Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md) to create connected cards, add tags
57
+ and milestones, and analyse detached records with pandas and NetworkX.
58
+
59
+ ## Installation
60
+
61
+ Holder Kit is currently in early development.
62
+
63
+ The Python distribution is named `holder-kit` and the import package is `holderkit`.
64
+
65
+ See [Building Holder Kit](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md) for installing the current version from source.
66
+
67
+ Ubuntu packages are also available as `python3-holder-kit` for supported Holder package repositories.
68
+
69
+ ## How Holder Kit fits into Holder
70
+
71
+ Holder Kit is a Python binding over `libholder`, running Holder directly inside
72
+ the Python process. This makes it suitable for scripts, notebooks, data analysis
73
+ and applications that want to embed Holder functionality.
74
+
75
+ To control a running Holder installation through the Framework API, use
76
+ [holder-python](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/holder).
77
+
78
+ Holder Kit is part of [Holder](https://github.com/HolderTeam/holder) and is
79
+ released with it, at the same version.
80
+
81
+ ## Examples
82
+
83
+ The repository includes examples covering:
84
+
85
+ - card creation and lifecycle;
86
+ - detached Python records;
87
+ - pandas analysis;
88
+ - connection graphs;
89
+ - tag analysis;
90
+ - milestone and calendar analysis;
91
+ - creating projects, retaining local edits and explicitly finishing an experiment.
92
+
93
+ See the [`examples/`](https://github.com/HolderTeam/holder/tree/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/examples) directory.
94
+
95
+ ## Documentation
96
+
97
+ - [Walkthrough](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/walkthrough.md)
98
+ - [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/publication.md)
99
+ - [Detached record contracts](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/record-contracts.md)
100
+ - [Advanced: storage and reopening](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/storage.md)
101
+ - [Building from source](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/building.md)
102
+ - [Development](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/development.md)
103
+ - [Packaging](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/docs/packaging.md)
104
+
105
+ ## Status
106
+
107
+ Holder Kit is under active development. The current API covers projects, cards, explicit connections, tags, milestones and analytical exports, with more of the `libholder` API to follow.
108
+
109
+ ## Licence
110
+
111
+ See [LICENSE](https://github.com/HolderTeam/holder/blob/9f3155a328431c6a5bde1b6194895834ac751437/python/kit/LICENSE).
@@ -0,0 +1,128 @@
1
+ # Building Holder Kit
2
+
3
+ This guide covers building and installing a checkout. See
4
+ [Development](development.md) for tests and code changes, and
5
+ [Packaging](packaging.md) for wheels and Ubuntu packages.
6
+
7
+ ## Prerequisites
8
+
9
+ Holder Kit requires Python 3.10 or newer with virtualenv support and development
10
+ headers, CMake 3.22 or newer, and C/C++ compilers. Linux, macOS and BSD builds
11
+ also need `pkg-config` and core's native development dependencies. Use core's
12
+ README (`../../core/README.md`) and CMake configuration for that dependency list.
13
+
14
+ On macOS, install Xcode Command Line Tools and the required Homebrew packages.
15
+ The developer script discovers Homebrew and its OpenSSL prefixes; set
16
+ `CMAKE_PREFIX_PATH` if CMake cannot find a library. On BSD, use the platform's
17
+ ports or package manager. The script does not install system packages.
18
+
19
+ ## Build with core source
20
+
21
+ `make.sh` is the Bash entry point on Linux, macOS and BSD. It runs
22
+ `scripts/develop.py`, creates or reuses `.venv`, and installs Holder Kit as an
23
+ editable package with all test dependencies, including pandas and NetworkX.
24
+
25
+ From `python/kit/` in a checkout of the holder repository:
26
+
27
+ ```sh
28
+ ./make.sh setup
29
+ ```
30
+
31
+ This builds core from source in the same checkout (`../../core`), so Kit is
32
+ always built against the core beside it. Set `HOLDER_KIT_CORE_SOURCE` to build
33
+ against a different core source directory. Builds leave the checkout on its
34
+ current branch and revision. They print core's revision and working-tree status,
35
+ and record them in `out/make/core-source.json`.
36
+
37
+ Before creating a virtualenv or installing Python packages, the source workflow
38
+ checks tools, Python headers and core's CMake prerequisites with
39
+ `BUILD_TESTING=OFF`. If configuration fails, fix the reported prerequisite and
40
+ rerun the command.
41
+
42
+ The script uses its own directory and invokes the virtualenv directly; shell
43
+ activation is optional.
44
+
45
+ For a manual build without the developer script, create a virtualenv and pass
46
+ the core source path explicitly:
47
+
48
+ ```sh
49
+ python3 -m venv .venv
50
+ . .venv/bin/activate
51
+ python -m pip install -e . \
52
+ --config-settings=cmake.define.HOLDER_KIT_CORE_SOURCE="$PWD/../../core"
53
+ ```
54
+
55
+ Direct pip/CMake builds require an explicit core selection; the default above
56
+ belongs to the developer script.
57
+
58
+ ## Build with a core SDK
59
+
60
+ SDK builds use a prebuilt core library instead of building core: a Holder
61
+ release's core SDK, or one that a CI run's `Core / SDK` workflow built. Fetch
62
+ and verify it with core's `scripts/core-sdk.py`, then point `HOLDER_CORE_SDK`
63
+ at the prepared SDK directory (the one containing `libholder-manifest.json`):
64
+
65
+ ```sh
66
+ HOLDER_CORE_SDK=/path/to/sdk ./make.sh --sdk setup
67
+ ```
68
+
69
+ `HOLDER_CORE_SDK` selects the SDK workflow unless `HOLDER_KIT_CORE_SOURCE` is
70
+ set. Combining `--sdk` with an explicit source path is rejected, and `--sdk`
71
+ without a prepared SDK stops before creating a virtualenv. For manual builds on
72
+ Linux or macOS, set `HOLDER_CORE_SDK` and `SKBUILD_CMAKE_BUILD_TYPE` (matching
73
+ the SDK's configuration) and run `python -m pip install -e .`.
74
+
75
+ Linux and macOS SDK builds still need core's native development dependencies.
76
+ The Linux SDK uses the Ubuntu 24.04 dependency ABI. Mixing it with another
77
+ distribution's C++ dependency ABI can cause import failures; use a source build
78
+ or the series-specific [Ubuntu package](packaging.md#ubuntu-packages).
79
+
80
+ ### Windows
81
+
82
+ Use an MSVC developer environment and a supported Python. Run the Python helper
83
+ directly if Bash is unavailable:
84
+
85
+ ```powershell
86
+ $env:HOLDER_CORE_SDK = "C:\path\to\sdk"
87
+ python scripts/develop.py --sdk setup
88
+ ```
89
+
90
+ The helper configures the SDK's bundled vcpkg toolchain and prebuilt dependencies.
91
+ For direct pip/CMake builds, set `HOLDER_CORE_SDK` and pass these CMake
92
+ definitions:
93
+
94
+ | Definition | Value |
95
+ | --- | --- |
96
+ | `CMAKE_TOOLCHAIN_FILE` | `<sdk>/vcpkg/scripts/buildsystems/vcpkg.cmake` |
97
+ | `VCPKG_INSTALLED_DIR` | `<sdk>/vcpkg/installed` |
98
+ | `VCPKG_TARGET_TRIPLET` | `x64-windows` |
99
+ | `VCPKG_MANIFEST_MODE` | `OFF` |
100
+ | `VCPKG_APPLOCAL_DEPS` | `OFF` |
101
+
102
+ Holder Kit does not bootstrap vcpkg or compile the SDK's dependencies. Windows
103
+ SDKs without bundled development dependencies are rejected.
104
+
105
+ ## Build settings and output
106
+
107
+ Build commands accept `Debug`, `Release`, `RelWithDebInfo` or `MinSizeRel`:
108
+
109
+ ```sh
110
+ ./make.sh setup Debug
111
+ ./make.sh --sdk setup Release
112
+ ```
113
+
114
+ The default is `RelWithDebInfo`. Source and SDK builds, and each build type, have
115
+ separate native directories under `build/make`.
116
+
117
+ | Environment variable | Purpose |
118
+ | --- | --- |
119
+ | `HOLDER_KIT` | Bootstrap Python interpreter; otherwise reuse the selected venv or use `python3` |
120
+ | `HOLDER_KIT_VENV` | Virtualenv path; defaults to `.venv` |
121
+ | `HOLDER_KIT_CORE_SOURCE` | Core source directory; defaults to `../../core` |
122
+ | `HOLDER_CORE_SDK` | Prepared SDK directory containing `libholder-manifest.json` |
123
+ | `BUILD_TYPE` | Default native build type |
124
+ | `CMAKE_BUILD_PARALLEL_LEVEL` | Build parallelism limit |
125
+
126
+ `./make.sh clean` removes only `build/make` and `out/make`. It retains `.venv`
127
+ and other build directories. Run
128
+ `./make.sh --help` for the complete command reference.
@@ -13,14 +13,15 @@ Holder Kit embeds libholder in the Python process. It does not talk to a running
13
13
  | `src/native/module.c` | CPython extension, exposed as `holderkit._native` |
14
14
  | `src/holderkit/` | Public Python API, typed records and optional adapters |
15
15
  | `tests/` | API, adapter and developer-script tests |
16
- | `examples/` | Runnable examples using temporary Holder data |
16
+ | `examples/` | Runnable examples for project and analysis APIs |
17
17
  | `scripts/develop.py` | Developer environment and build commands |
18
18
  | `CMakeLists.txt` | Native extension build and resource installation |
19
19
 
20
- Keep reusable storage and domain behavior in holder-core. The Python layer calls
21
- core's semantic operations, including tag and milestone edits, rather than
22
- reimplementing them by parsing or rewriting card files. Core also owns SDK
23
- selection and validation; `scripts/core-sdk.py` delegates to its shared tool.
20
+ Keep reusable storage and domain behavior in core (`../../core`). The Python
21
+ layer calls core's semantic operations, including tag and milestone edits, rather
22
+ than reimplementing them by parsing or rewriting card files. Kit uses only core's
23
+ C API; see [AGENTS.md](../AGENTS.md). A change that needs both goes in one pull
24
+ request.
24
25
 
25
26
  The package ships the schema from the selected core source or SDK as
26
27
  `holderkit/_schema.sql`. Installed packages must work without a source checkout.
@@ -59,18 +60,34 @@ directory or contact a running daemon. Follow that pattern for new tests.
59
60
  ./make.sh examples graph
60
61
  ./make.sh examples tags
61
62
  ./make.sh examples milestones
63
+ ./make.sh examples make_project
64
+ ./make.sh examples finish_project
62
65
  ```
63
66
 
64
- Examples use temporary data directories and clean up on exit. They can also be
65
- run directly with the development environment's Python. The pandas, tag and
67
+ `make_project` uses automatic storage and keeps the project it creates. The other
68
+ examples use temporary data directories and clean up on exit. Examples can also
69
+ be run directly with the development environment's Python. The pandas, tag and
66
70
  milestone analysis examples require the pandas extra; graph analysis uses both
67
71
  pandas and graph extras. Ordinary base-package use imports neither dependency.
68
72
 
73
+ The workspace tests start disposable Git servers on loopback to test real remote
74
+ clones. They require Git and permission to bind/connect local sockets. Fixtures
75
+ use temporary contexts and bare repositories, never a live Holder project.
76
+
69
77
  ## Public API contracts
70
78
 
71
79
  `Context` owns the native `holder_context`; close it explicitly or use a context
72
80
  manager. Native runtime failures raise `holderkit.HolderError`, and invalid core
73
- arguments raise `ValueError`. `Project` and `Card` are frozen, slotted dataclasses.
81
+ arguments raise `ValueError`. `Project` is a live interface to one project;
82
+ its properties read current state. `Card` is also live and keeps its owning
83
+ Project through `card.project`. Use `Project.to_record()` and `Card.to_record()`
84
+ for detached values. Card identity is stable; reads and edits require an open owner. Managed Projects own
85
+ their context; Projects obtained from a Context borrow it and close independently.
86
+
87
+ Card-scoped tags, connections and milestones are adapters over the existing
88
+ Project and collection operations. Keep ownership/lifetime checks on live handles,
89
+ and reuse Core semantics and detached record schemas. Single-card exports must
90
+ not scan an entire project to select their source.
74
91
 
75
92
  Records, DataFrames and graphs are detached data. They remain usable after the
76
93
  context closes, and editing them does not write back to Holder. Card exports
@@ -83,6 +100,13 @@ mutation limits. Consult those contracts when changing the API, and keep them
83
100
  and the examples consistent with the code. Test empty exports, optional
84
101
  dependencies, ownership checks and failure behavior where relevant.
85
102
 
103
+ ## Clone build requirements
104
+
105
+ Clone uses core's `holder_project_import` API, which the core beside Kit
106
+ provides. Building against an older core SDK without project import support
107
+ still makes clone raise `NotImplementedError` before creating storage or
108
+ contacting the remote.
109
+
86
110
  ## Native sanitizers
87
111
 
88
112
  For native memory-safety work, use a separate pip/CMake build with
@@ -126,3 +150,10 @@ is `HolderTeam/holder-kit`. When updating an older environment, uninstall the
126
150
  former `holder` distribution and replace `import holder` with `import holderkit`.
127
151
  Dependency declarations use `holder-kit`, `holder-kit[pandas]` or
128
152
  `holder-kit[graph]`. There is no compatibility import shim.
153
+
154
+ ## Filtered card batch build requirements
155
+
156
+ Filtered `project.cards(...)` batches use Core's `holder_card_collection_page_json`
157
+ API, advertised by `HOLDER_HAS_CARD_COLLECTION_PAGE`, which the core beside Kit
158
+ provides. Existing unfiltered batches work with older SDKs; requesting filters
159
+ or explicit ordering without this API raises `NotImplementedError`.
@@ -15,16 +15,15 @@ The build backend is scikit-build-core, which invokes CMake to compile
15
15
  not stable-ABI wheels.
16
16
 
17
17
  ```sh
18
- ./make.sh wheel Release # build with local core source
19
- ./make.sh --sdk wheel Release # build with the selected core SDK
18
+ ./make.sh wheel Release # build with ../../core from source
19
+ ./make.sh --sdk wheel Release # build with the core SDK in HOLDER_CORE_SDK
20
20
  ```
21
21
 
22
- Both commands write wheels to `out/make/wheels`. For a manual SDK build, select
23
- a Release SDK and a matching build configuration:
22
+ Both commands write wheels to `out/make/wheels`. For a manual SDK build, use a
23
+ prepared Release SDK and a matching build configuration:
24
24
 
25
25
  ```sh
26
- python scripts/core-sdk.py resolve --core-ref <tag-or-full-SHA>
27
- export HOLDER_CORE_SDK="$(python scripts/core-sdk.py fetch --build-type Release)"
26
+ export HOLDER_CORE_SDK=/path/to/release-sdk
28
27
  export SKBUILD_CMAKE_BUILD_TYPE=Release
29
28
  python -m pip install build
30
29
  python -m build --wheel --outdir dist
@@ -45,13 +44,14 @@ and checks the resulting wheel's platform compatibility as described below.
45
44
  Validate a wheel in a fresh virtualenv outside the source checkout: import
46
45
  `holderkit`, create temporary data, exercise the card lifecycle, and verify the
47
46
  schema and typing resources. Test base use before installing optional adapters.
48
- The Linux job in [`ci.yml`](../.github/workflows/ci.yml) provides the installed
49
- SDK-wheel smoke test, including `_core_build.json` validation.
47
+ The Linux job in [Kit / CI](../../../.github/workflows/kit-ci.yml) provides the
48
+ installed SDK-wheel smoke test, including `_core_build.json` validation.
50
49
 
51
50
  ### Release wheels
52
51
 
53
- [`release.yml`](../.github/workflows/release.yml) builds wheels for CPython
54
- 3.10–3.14 and a source archive. Supported wheel platforms are:
52
+ `Release / Kit to PyPI`
53
+ ([`release-kit-pypi.yml`](../../../.github/workflows/release-kit-pypi.yml))
54
+ builds wheels for CPython 3.10–3.14 and a source archive. Supported wheel platforms are:
55
55
 
56
56
  | Platform | Architecture | Minimum runtime |
57
57
  | --- | --- | --- |
@@ -59,9 +59,9 @@ SDK-wheel smoke test, including `_core_build.json` validation.
59
59
  | Windows | x86_64 | Windows 10/11 |
60
60
  | macOS | ARM64 | macOS 15 |
61
61
 
62
- Release builds use the exact core commit and `Release` SDK configuration in
63
- [`release-core.json`](../release-core.json). Ordinary development CI continues
64
- to use latest-green. A Framework release should set this file to its core pin.
62
+ Release builds use `Release` core SDKs that `Core / SDK` builds in the same run
63
+ from `core/` in the same commit. They are cached by `core/`'s tree, so a release
64
+ usually reuses the SDKs its Daemon CI run built.
65
65
 
66
66
  Before building wheels and the source archive, the release workflow rewrites
67
67
  relative README links in its checkout to absolute URLs at the release commit.
@@ -83,11 +83,12 @@ notices are carried in the distribution's licence metadata.
83
83
  Each wheel is installed in a fresh virtualenv and tested before optional
84
84
  adapters are installed, then runs the installed integration tests. Linux also
85
85
  runs in clean Debian Python containers. The source archive is built and
86
- installed with the same pinned SDK. The final distribution check requires all
87
- 15 wheels and the source archive, validates core identity and metadata, and
88
- records file sizes and SHA256 hashes in the `release-manifest` artifact.
86
+ installed with the same Release SDK. The final distribution check requires all
87
+ 15 wheels and the source archive, checks each wheel's core against the SDKs'
88
+ `core-selection`, validates metadata, and records the core and the file sizes
89
+ and SHA256 hashes in the `kit-release-manifest` artifact.
89
90
 
90
- To inspect a candidate from the `release-distributions` artifact:
91
+ To inspect a candidate from the `kit-release-distributions` artifact:
91
92
 
92
93
  ```sh
93
94
  python -m venv .venv
@@ -103,8 +104,10 @@ explicit [native source build](building.md).
103
104
  The manual workflow's `destination` defaults to `none`, which builds and tests
104
105
  candidates. `pypi` or `testpypi` publishes only after all distribution checks
105
106
  pass, using the corresponding GitHub environment and Trusted Publishing.
106
- Publication requires the matching version tag, such as `v0.0.1` for the
107
- version in `pyproject.toml`. Pull requests build candidates without publishing.
107
+ Holder Kit is released with the rest of Holder, at the same version: publishing
108
+ must run from the release's `holder-v<version>` tag, and requires the version in
109
+ `pyproject.toml`, the repository's `VERSION` and core's version to equal it. Pull requests build candidates without
110
+ publishing.
108
111
 
109
112
  ## Ubuntu packages
110
113
 
@@ -141,51 +144,25 @@ dpkg-buildpackage -b -us -uc
141
144
 
142
145
  ### Package validation
143
146
 
144
- [`ubuntu-packages.yml`](../.github/workflows/ubuntu-packages.yml) builds and tests
145
- Noble (Ubuntu 24.04) and Resolute (Ubuntu 26.04) separately. It installs each
146
- binary in a fresh container without development packages, tests ordinary Python
147
- use, then installs optional adapters and runs integration tests.
148
-
149
- To reproduce the Noble build and runtime checks with Docker:
150
-
151
- ```sh
152
- mkdir -p out/packages
153
- docker run --rm -v "$PWD:/source:ro" -v "$PWD/out/packages:/out" \
154
- ubuntu:24.04 bash /source/scripts/ubuntu-package-ci.sh build noble
155
- docker run --rm -v "$PWD:/source:ro" -v "$PWD/out/packages:/out:ro" \
156
- ubuntu:24.04 bash /source/scripts/ubuntu-package-ci.sh install noble
157
- ```
158
-
159
- For Resolute, use `ubuntu:26.04` and `resolute`. Keep each series' artifacts in
160
- a separate output directory if testing both locally.
147
+ Kit / CI ([`kit-ci.yml`](../../../.github/workflows/kit-ci.yml)) builds the
148
+ package for Noble (Ubuntu 24.04) and Resolute (Ubuntu 26.04) separately, as
149
+ Launchpad does: from `python/kit/` copied out on its own, against libholder
150
+ packages built in the same job from `core/` in the same commit. It checks that
151
+ the package requires `libholder0` of the same upstream version (Kit installs
152
+ that core's schema and hands it to `libholder0` at runtime). It then installs
153
+ the packages in a fresh container without development packages or a compiler,
154
+ tests ordinary Python use with
155
+ [`scripts/ubuntu-package-ci.sh`](../scripts/ubuntu-package-ci.sh), then
156
+ installs optional adapters and runs integration tests.
161
157
 
162
158
  ### Launchpad source packages
163
159
 
164
- [`launchpad.yml`](../.github/workflows/launchpad.yml) is a manual workflow that
165
- prepares source candidates for both Ubuntu series. Its inputs are:
166
-
167
- | Input | Meaning |
168
- | --- | --- |
169
- | `version` | Must match `pyproject.toml` |
170
- | `package_revision` | Positive Debian revision; increment for replacement uploads |
171
- | `core_package_version` | Exact core package version before the Ubuntu suffix, such as `0.2.0-1` |
172
- | `upload` | Defaults to false; when true, sign and upload to `ppa:holderteam/holder` |
173
-
174
- Each candidate pins `libholder-dev` to the exact series-specific package version,
175
- such as `0.2.0-1~noble1`. Runtime dependencies are generated against the compatible
176
- shared ABI. Uploading requires the repository's `PPA_GPG_PRIVATE_KEY` secret.
177
-
178
- To prepare a source candidate manually, use a clean disposable checkout and
179
- Python 3.11 or newer (the preparation script uses `tomllib`):
180
-
181
- ```sh
182
- python3 scripts/prepare-debian-source.py \
183
- --version 0.0.1 --package-revision 1 --series noble \
184
- --core-package-version '0.2.0-1~noble1'
185
- debuild -S -d -us -uc
186
- ```
187
-
188
- Use the actual Kit and core versions for the candidate. The script packages
189
- committed files from `HEAD`, creates `debian/`, and writes the upstream archive
190
- in the parent directory. The workflow saves the unsigned source candidate as an
191
- artifact before optional signing and upload.
160
+ `holder-kit` is one of the source packages that `Release / Launchpad`
161
+ ([`release-launchpad.yml`](../../../.github/workflows/release-launchpad.yml))
162
+ uploads to `ppa:holderteam/holder`, with `holder-core` and `holder-daemon`. The
163
+ release tag uploads all three. A manual run with `packages=kit` and a new
164
+ `package_revision` uploads only Kit, for a packaging-only fix. Kit's version
165
+ must equal core's: its source package builds against `libholder-dev` of that
166
+ version, so on Launchpad it waits for the core packages from the same upload.
167
+ The upstream tarball is `python/kit/` as committed. Pull requests that change
168
+ the packaging build the source package unsigned without uploading.