Metadata-Version: 2.4
Name: holder-kit
Version: 0.0.2
Summary: Holder Kit: CPython bindings for embedded libholder
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/HolderTeam/holder-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-kit/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/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.open("./knowledge") as holder:
    project = holder.create_project("Research")

    card = holder.create_card(
        project.project_id,
        "Interesting question",
        "Something worth investigating.",
    )

    print(card.title)
```

Follow the [walkthrough](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/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-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/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-python).

Holder Kit is versioned independently from the
[Holder Framework](https://github.com/HolderTeam/holder-framework) and
[core library](https://github.com/HolderTeam/holder-core).

## Examples

The repository includes examples covering:

- card creation and lifecycle;
- detached Python records;
- pandas analysis;
- connection graphs;
- tag analysis;
- milestone and calendar analysis.

See the [`examples/`](https://github.com/HolderTeam/holder-kit/tree/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/examples) directory.

## Documentation

- [Walkthrough](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/walkthrough.md)
- [Detached record contracts](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/record-contracts.md)
- [Building from source](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/building.md)
- [Development](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/docs/development.md)
- [Packaging](https://github.com/HolderTeam/holder-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/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-kit/blob/3fa699ac2cc0c7a2cc84deef4e6dc90756bcb9ad/LICENSE).
