Metadata-Version: 2.5
Name: octx
Version: 0.1.5
Summary: Reference implementation for Open Context
Author: OCTX contributors
License: MIT License
        
        Copyright (c) 2026 OCTX contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,context,knowledge,octx,okf
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.21
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rfc8785>=0.1.4
Requires-Dist: uuid6>=2024.7.10
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pyarrow>=15; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Provides-Extra: vectors
Requires-Dist: pyarrow>=15; extra == 'vectors'
Description-Content-Type: text/markdown

# Open Context

Open Context（简称 OCTX）是一种建立在 Google Open Knowledge Format（OKF）之上的开放上下文标准。它把可读 Markdown、稳定身份、版本、完整性信息及可选的 chunks、events、entities、关系和向量封装为可传播的 `.octx` Package。

Open Context 兼容 [SAG](sag.md) 的 Chunk-Event-Entity 超图数据结构，但规范和参考工具不依赖 SAG、`zleap-sag`、特定数据库或向量后端。

## 阅读顺序

1. **OCTX v0.1 规范**（`spec-v0.1.md`）：容器、manifest、知识文档、身份、摘要、版本和扩展规则。
2. **SAG 是什么**（`sag.md`）：SAG 应用、检索架构、`zleap-sag` 及其与 OCTX 的关系。
3. **SAG-Structured v0.1 Capability**（`sag-structured-v0.1.md`）：完整的 chunks、events、entities 和关系。
4. **Vectors v0.1 Capability**（`vectors-v0.1.md`）：六种语义角色向量、生成 recipe、输入摘要与兼容性判定。
5. **工具链概览**（`tooling-lifecycle.md`）：工具分层及 Asset、Release、Package、Installation 等核心对象。
6. **构建与集成**：`creating-octx.md`、`opening-validating-octx.md`、`importing-octx.md`、`exporting-octx.md` 分别说明创建、校验、导入和导出。
7. **Python API**（`api/overview.md`）：按功能拆分的创建、读取、校验、安全解包和 CLI 文档。
8. **机器可读 Schema**（`schemas/README.md`）：JSON Schema Draft 2020-12 与语义校验边界。
9. **领域词汇表**（`GLOSSARY.md`）：OCTX、SAG 和 zleap-sag 的统一术语。

## Python 快速开始

需要 Python 3.11 或更高版本。从 PyPI 安装：

```bash
pip install octx
```

需要向量功能时，安装带 extras 的版本：

```bash
pip install "octx[vectors]"
```

从源码安装（开发模式）：

```bash
git clone <repository-url> open-context
cd open-context
pip install -e ".[dev]"
```

从 Markdown 目录创建 Package，然后打开并校验：

```python
from octx import create_octx, open_octx, validate_octx

result = create_octx(
    "./.octx-workspace",
    source="./knowledge",
    name="Product Guide",
    output="./product-guide.octx",
)

with open_octx(result.output) as package:
    for document in package.iter_documents():
        print(document.path, document.metadata["title"])

report = validate_octx(result.output)
assert report.valid
```

`source` 不会被修改。持续使用同一个 workspace，可以保留 Asset、Document 和 Release 的稳定身份。向量读取需要安装 `octx[vectors]`。完整接口见 `api/overview.md`。

展开的外部 Package 未修改时可以无损重新封装；修改或增强后，使用 `create_octx(..., derive=True)` 创建带 `asset.derived_from` 的新 Asset，避免冒充原发布者的后续版本。

## CLI 快速开始

```bash
octx create ./.octx-workspace --from ./knowledge --name "Product Guide" -o ./product-guide.octx
octx inspect ./product-guide.octx
octx validate ./product-guide.octx
octx unpack ./product-guide.octx ./product-guide-expanded
```

`inspect` 只读取摘要，不代替完整校验。`validate` 有效时退出 `0`，无效时退出 `1`；所有命令都支持 `--json`。

## 官网与文档站

官网域名是 [opencontext.wiki](https://opencontext.wiki)。独立网站源码位于 `site/`，直接发布本目录中的完整规范、Python API、Schema 和词汇表，不依赖 SAG 项目的应用代码。

## v0.1 要点

- 发布文件扩展名是 `.octx`，外层使用 ZIP / ZIP64。
- 每个 Package 至少包含一篇 OKF Concept Markdown。
- OCTX 的 `knowledge/` 是符合 OKF v0.1 的知识层；完整 OCTX Package 还要求 manifest、资产身份、Release、摘要和可选派生数据。普通 OKF Bundle 不是 OCTX Package。
- OCTX Package 可以只有 Markdown，不要求预先生成 chunks、events、entities 或 vectors。
- `sag-structured/0.1` 是单一显式 Capability，整体包含 chunks、events、entities 和关系，不能根据文件存在情况自动推断。
- `.octx` 是不可变完整快照，不是数据库备份、增量包或同步协议。
- OCTX 不定义搜索 API、召回算法、Agent 协议或向量数据库。

## 参考实现边界

独立 `octx` 包提供：

- `create_octx()`
- `open_octx()`
- `validate_octx()`
- `unpack_octx()`
- `octx create / inspect / validate / unpack`

`zleap-sag` 依赖并重新导出这些入口，同时增加：

- `import_octx()`
- `export_octx()`

其他知识系统可以直接使用 `octx` 并实现自己的适配层。
