Metadata-Version: 2.4
Name: holder-kit
Version: 0.2.5
Summary: Holder Kit: CPython bindings for embedded libholder
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/HolderTeam/holder/tree/main/python/kit
Requires-Python: >=3.10
Provides-Extra: test
Requires-Dist: mypy>=1.15; extra == "test"
Requires-Dist: pandas; extra == "test"
Requires-Dist: pandas-stubs; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: networkx; extra == "test"
Requires-Dist: types-networkx; extra == "test"
Provides-Extra: pandas
Requires-Dist: pandas; extra == "pandas"
Requires-Dist: pandas-stubs; extra == "pandas"
Provides-Extra: graph
Requires-Dist: networkx; extra == "graph"
Requires-Dist: types-networkx; extra == "graph"
Description-Content-Type: text/markdown
License-File: third-party/common-licenses/Apache-2.0
License-File: third-party/common-licenses/Artistic
License-File: third-party/common-licenses/BSD
License-File: third-party/common-licenses/CC0-1.0
License-File: third-party/common-licenses/GFDL
License-File: third-party/common-licenses/GFDL-1.2
License-File: third-party/common-licenses/GFDL-1.3
License-File: third-party/common-licenses/GPL
License-File: third-party/common-licenses/GPL-1
License-File: third-party/common-licenses/GPL-2
License-File: third-party/common-licenses/GPL-3
License-File: third-party/common-licenses/LGPL
License-File: third-party/common-licenses/LGPL-2
License-File: third-party/common-licenses/LGPL-2.1
License-File: third-party/common-licenses/LGPL-3
License-File: third-party/common-licenses/MPL-1.1
License-File: third-party/common-licenses/MPL-2.0
License-File: third-party/libblkid1.copyright
License-File: third-party/libcom-err2.copyright
License-File: third-party/libffi8.copyright
License-File: third-party/libfmt9.copyright
License-File: third-party/libgcc-s1.copyright
License-File: third-party/libgcrypt20.copyright
License-File: third-party/libgit2-1.7.copyright
License-File: third-party/libglib2.0-0t64.copyright
License-File: third-party/libgpg-error0.copyright
License-File: third-party/libgssapi-krb5-2.copyright
License-File: third-party/libhttp-parser2.9.copyright
License-File: third-party/libk5crypto3.copyright
License-File: third-party/libkeyutils1.copyright
License-File: third-party/libkrb5-3.copyright
License-File: third-party/libkrb5support0.copyright
License-File: third-party/libmd4c0.copyright
License-File: third-party/libmount1.copyright
License-File: third-party/libpcre2-8-0.copyright
License-File: third-party/libsecret-1-0.copyright
License-File: third-party/libselinux1.copyright
License-File: third-party/libsodium23.copyright
License-File: third-party/libspdlog1.12.copyright
License-File: third-party/libsqlite3-0.copyright
License-File: third-party/libssh2-1t64.copyright
License-File: third-party/libssl3t64.copyright
License-File: third-party/libstdc++6.copyright
License-File: third-party/libyaml-cpp0.8.copyright
License-File: third-party/nlohmann-json3-dev.copyright
License-File: third-party/zlib1g.copyright

# Holder Kit

**Analyse, transform and import Holder data with Python.**

Holder Kit gives Python programs direct access to Holder projects, cards, connections, tags and milestones.

Typical uses include:

- **Data analysis** — load Holder data into pandas and explore it with familiar Python tools.
- **Bulk import and transformation** — create or modify large collections of cards programmatically.
- **Machine learning** — extract Holder content for classification, clustering, embeddings, ranking and other experiments.
- **Graph analysis** — export explicit connections between cards to NetworkX.
- **Dataset and corpus preparation** — turn a Holder knowledge base into structured Python records for further processing.
- **Offline automation** — perform maintenance, migration and batch operations without running the Holder daemon.

The base package exposes ordinary Python records and has no data-science dependencies. pandas and NetworkX integrations are available as optional extras.

A typical workflow looks like this:

![AI generated image](https://raw.githubusercontent.com/HolderTeam/holder/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/workflow.png)

1. You make a new project, or clone an existing one.
2. You do work and analysis.
3. You push your experiment, or discard it.

## A first example

```python
import holderkit

with holderkit.create("Research") as project:
    card = project.create_card(
        "Interesting question",
        "Something worth investigating.",
    )

    print(project.cards.to_records(include_content=True))
```

Or clone an existing Holder project and explore its cards:

```python
with holderkit.clone("git@example.org:research.git") as project:
    for card in project.cards.to_records(include_content=True):
        print(card["title"], card["content"])
```

Replace the example URL with your project's Git remote. Holder Kit chooses
local storage automatically. These examples need Git installed.

When your experiment is ready, publish it while the project is open with
`project.push(remote_url="git@example.org:research.git", branch="experiments/results")`.
Use `project.close()` to keep your work, or `project.discard(confirm=True)` to
remove it locally. See [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/publication.md).

Follow the [walkthrough](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/walkthrough.md) to create connected cards, add tags
and milestones, and analyse detached records with pandas and NetworkX.

## Installation

Holder Kit is currently in early development.

The Python distribution is named `holder-kit` and the import package is `holderkit`.

See [Building Holder Kit](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/building.md) for installing the current version from source.

Ubuntu packages are also available as `python3-holder-kit` for supported Holder package repositories.

## How Holder Kit fits into Holder

Holder Kit is a Python binding over `libholder`, running Holder directly inside
the Python process. This makes it suitable for scripts, notebooks, data analysis
and applications that want to embed Holder functionality.

To control a running Holder installation through the Framework API, use
[holder-python](https://github.com/HolderTeam/holder/tree/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/holder).

Holder Kit is part of [Holder](https://github.com/HolderTeam/holder) and is
released with it, at the same version.

## Examples

The repository includes examples covering:

- card creation and lifecycle;
- detached Python records;
- pandas analysis;
- connection graphs;
- tag analysis;
- milestone and calendar analysis;
- creating projects, retaining local edits and explicitly finishing an experiment.

See the [`examples/`](https://github.com/HolderTeam/holder/tree/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/examples) directory.

## Documentation

- [Walkthrough](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/walkthrough.md)
- [Publishing and finishing a project](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/publication.md)
- [Detached record contracts](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/record-contracts.md)
- [Advanced: storage and reopening](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/storage.md)
- [Building from source](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/building.md)
- [Development](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/development.md)
- [Packaging](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/docs/packaging.md)

## Status

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.

## Licence

See [LICENSE](https://github.com/HolderTeam/holder/blob/476aeeeaba3d48ad8a07483742609c9a76d3d56d/python/kit/LICENSE).
