Metadata-Version: 2.4
Name: oks-connector
Version: 0.1.0
Summary: Independent Level-1 multimodal Raw-Bundle extractor for Open Knowledge Studio
Author: open-agent-power
License: Apache-2.0
Project-URL: Homepage, https://github.com/open-agent-power/oks-connector
Project-URL: Repository, https://github.com/open-agent-power/oks-connector
Keywords: multimodal,extractor,pdf,ocr,transcription,knowledge-base
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia
Classifier: Topic :: Text Processing
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: document
Requires-Dist: markitdown[docx]==0.1.6; extra == "document"
Provides-Extra: pdf
Requires-Dist: mineru==3.4.4; extra == "pdf"
Provides-Extra: watch
Requires-Dist: faster-whisper==1.2.1; extra == "watch"
Requires-Dist: rapidocr==3.9.1; extra == "watch"
Requires-Dist: onnxruntime==1.27.0; extra == "watch"
Requires-Dist: yt-dlp==2026.7.4; extra == "watch"
Provides-Extra: formula
Requires-Dist: paddlepaddle==3.2.0; extra == "formula"
Requires-Dist: paddleocr==3.7.0; extra == "formula"
Requires-Dist: tokenizers==0.23.1; extra == "formula"
Requires-Dist: ftfy==6.3.1; extra == "formula"
Dynamic: license-file

# oks-connector

Independent **Level-1** multimodal extractor for
[Open Knowledge Studio](https://github.com/itxaiohanglover/open-knowledge-studio).
It converts video / audio / image / Office / PDF sources into an OKS **Raw
Bundle** (`content.md` + `evidence.jsonl` provenance sidecar).

This package is deliberately **separate from the OKS core** (`oks` / `cli/`):

- Per CONSTITUTION **P4/P5**, the OKS core stays API-free and never wraps tools
  at runtime. Extractors are L1 capabilities the Agent spawns via Bash, guided
  by the routing table in `settings/handlers.json`.
- Per the reframed **A1**, this is **not** a repo maintenance script (those stay
  in `scripts/` inside the knowledge repo). It is an independently versioned,
  independently installed L1 tool — which is why it lives in its own package.

It **never summarizes, corrects, grades, or promotes** source content. Its only
contract is faithful extraction plus provenance (P3: `raw/` is mechanical).

## Install

The core CLI is stdlib-only. Heavy extractors are opt-in extras, each best
installed in its **own isolated Python 3.12 interpreter** (they pin conflicting
heavyweight deps such as MinerU / PaddleOCR / faster-whisper):

```bash
# one interpreter per modality
pip install "oks-connector[document]"   # docx / pptx via markitdown
pip install "oks-connector[pdf]"        # PDF via MinerU
pip install "oks-connector[watch]"      # video / audio via faster-whisper + rapidocr
pip install "oks-connector[formula]"    # formula OCR via paddleocr
```

## Use

```bash
oks-connector --version
oks-connector route  <source>                       # print the extraction plan
oks-connector image  <img>  --output <bundle_dir>   # OCR + bbox evidence
oks-connector markitdown <docx> --output <bundle_dir>
oks-connector mineru <mineru_result> --source <pdf> --output <bundle_dir>
oks-connector watch  <video> --output <bundle_dir>  # transcript + frames + OCR
oks-connector validate <bundle_dir>                 # check a bundle against v0.1
```

Output contract: `raw-multimodal/v0.1` — see `docs/raw-multimodal-standard.md`
in the OKS repo.

## Wiring into the knowledge repo

Point `settings/handlers.json` `command_argv` at the installed entry point
instead of the in-repo script path. For example:

```json
"command_argv": ["{watch_python}", "-m", "raw_bundle_adapter", "watch", "{input}", "--output", "{output}"]
```

or, if the modality's interpreter is on PATH:

```json
"command_argv": ["oks-connector", "watch", "{input}", "--output", "{output}"]
```

`{watch_python}` / `{mineru_python}` / `{document_python}` are resolved from
`settings/raw-tools.json` so each modality can use its isolated environment.

## Develop / test

```bash
python -m pytest scripts/tests -q
```
