Metadata-Version: 2.4
Name: mira-okf
Version: 0.0.1a8
Summary: Local, read-only Python library and CLI for inspecting Open Knowledge Format bundles.
Maintainer: gnunesmoura
License-Expression: MIT
Project-URL: Repository, https://github.com/gnunesmoura/mira-okf
Project-URL: Documentation, https://github.com/gnunesmoura/mira-okf/tree/main/docs
Project-URL: Issues, https://github.com/gnunesmoura/mira-okf/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: lint
Requires-Dist: pymarkdownlnt>=0.9; extra == "lint"
Requires-Dist: PyYAML>=6.0; extra == "lint"
Dynamic: license-file

# MIRA OKF

MIRA OKF is a local tool for exploring and checking Open Knowledge Format
(OKF) bundles. It reads Markdown-based knowledge bases without changing them,
so you can browse concepts, inspect links, project metadata, validate
structure, and review bundle health from the terminal.

MIRA stands for **Markdown Indexing, Retrieval & Analysis**. The `OKF` suffix
makes the supported format explicit.

## Try it

```bash
mira-okf tree path/to/bundle --depth 2 --summary
mira-okf show path/to/bundle concept-id
mira-okf validate path/to/bundle --json
```

The CLI is read-only and works locally: it does not require Obsidian, a
database, a network connection, or a hosted service.

The full interface is documented in [`docs/`](docs/).

To install the four public MIRA OKF skills into a supported AI tool target:

```bash
mira-okf skills install
# or install into the user home directory
mira-okf skills install --location home
# or select a specific AI tool target
mira-okf skills install --ai-tool opencode
```

The installer is local and distribution-owned: it installs only
`okf-authoring`, `okf-context`, `okf-answer`, and `okf-update`, and does not
modify an OKF bundle. `--ai-tool` defaults to `agents` and `--location`
defaults to `local`, so a bare install writes below the current directory's
`.agents/skills/`. See [`docs/commands/skills.md`](docs/commands/skills.md).

The repository's `docs/` directory is itself an OKF bundle, so it can be used
as a local example when trying the commands above.

## Install

Python 3.12 or newer is required. This alpha release is installed from PyPI
with `--pre`:

```bash
python3 -m pip install --user --upgrade --pre mira-okf
mira-okf --version
```

If you already cloned this repository, install the checkout instead:

```bash
python3 -m pip install --user --upgrade .
mira-okf --version
```

On Windows, use `py -m pip` instead of `python3 -m pip`. If `mira-okf` is not
found after a user install, add Python's user `Scripts` directory to `PATH`.

## Quick start

With a built wheel or source distribution, an isolated environment is also
supported:

```bash
python3 -m venv /tmp/mira-okf-venv
/tmp/mira-okf-venv/bin/python -m pip install /path/to/mira_okf-0.0.1a5-py3-none-any.whl
/tmp/mira-okf-venv/bin/mira-okf tree /path/to/bundle --depth 2 --summary
```

From this checkout, the public documentation bundle is `docs/`:

```bash
python -m mira_okf tree docs --depth 2 --summary
python -m mira_okf validate docs --json
```

Generic automatic discovery can be ambiguous for this nested documentation
tree, so use the explicit `docs/` path for commands run from this checkout.

## Compatibility and support

The project is alpha, supports OKF Specification 0.1, and officially supports
validated Linux environments. Windows is best effort and macOS is outside the
declared scope. Documented commands, JSON envelopes, exit codes, and the OKF
reader behavior are public compatibility surfaces.

The supported Python package surface for this alpha is `import mira_okf` and
`mira_okf.__version__`. The `mira_okf.okf` models and other implementation
modules are not stable integration interfaces yet.

For bugs, usage help, and in-scope feature requests, use the [public issue
tracker](https://github.com/gnunesmoura/mira-okf/issues). Support is best
effort with no SLA. See [CONTRIBUTING.md](CONTRIBUTING.md),
[SECURITY.md](SECURITY.md), and [CHANGELOG.md](CHANGELOG.md).

This project is available under the [MIT License](LICENSE).
