Metadata-Version: 2.4
Name: btcu-harness
Version: 1.1.0
Summary: Balanced Ternary Cognitive Unit Harness - A cognitive architecture for LLM-based agents
Author: BTCU Harness Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/q1z2q3-debug/btcu-harness
Project-URL: Repository, https://github.com/q1z2q3-debug/btcu-harness
Project-URL: Documentation, https://github.com/q1z2q3-debug/btcu-harness#readme
Project-URL: Issues, https://github.com/q1z2q3-debug/btcu-harness/issues
Project-URL: Changelog, https://github.com/q1z2q3-debug/btcu-harness/releases
Keywords: ternary,cognitive-architecture,agent,LLM,balanced-ternary,cognition,ai,memory-ecology,third-choice,emergent-semantics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai>=0.5; extra == "gemini"
Provides-Extra: llm
Requires-Dist: openai>=1.0; extra == "llm"
Requires-Dist: anthropic>=0.20; extra == "llm"
Requires-Dist: google-genai>=0.5; extra == "llm"
Provides-Extra: mongo
Requires-Dist: pymongo>=4.0; extra == "mongo"
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == "api"
Requires-Dist: uvicorn[standard]>=0.20; extra == "api"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.20; extra == "all"
Requires-Dist: google-genai>=0.5; extra == "all"
Requires-Dist: pymongo>=4.0; extra == "all"
Requires-Dist: fastapi>=0.100; extra == "all"
Requires-Dist: uvicorn[standard]>=0.20; extra == "all"
Requires-Dist: mkdocs>=1.5; extra == "all"
Requires-Dist: mkdocs-material>=9.0; extra == "all"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "all"

# BTCU Harness

**Balanced Ternary Cognitive Unit Harness** — 基于平衡三进制认知单元的智能体认知驾驭架构

[![CI](https://github.com/q1z2q3-debug/btcu-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/q1z2q3-debug/btcu-harness/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests: 96 passed](https://img.shields.io/badge/tests-96%20passed-brightgreen.svg)](#)

---

## 什么是 BTCU Harness？

BTCU Harness 是一个以三态集合 {-1, 0, +1} 为最小认知基元，以 3^9 = 19683 离散认知空间为核心，面向大语言模型（LLM）与智能体（Agent）的认知驾驭架构。

它不替代大模型，而是作为大模型与 Agent 之间的**结构化认知层**，逐步实现从"高频调用大模型"到"内部认知自主"的演进。

### 核心特性

- **三态认知基元**：阴(-1)、空(0)、阳(+1)，公理 -1+1=0
- **19683 状态空间**：九维三元向量，每个状态有唯一整数编号
- **涌现式语义**：不预设状态含义，全靠 Agent 实践积累
- **三阶段成长**：school -> internalize -> graduate，成本从 C proportional to N_call 降至 C proportional to N_unknown
- **NLP 自我层**：Dilts 8 层身份模型作为认知吸引子
- **第三选择**：二元冲突时生成 5 策略候选，四维评分
- **认知气候**：极性趋势、探索阶段、气候区域、认知漂移
- **持久化**：JSON 存储完整认知状态，支持 save/load 往返
- **CLI 工具**：命令行操作认知空间
- **性能优化**：LRU 缓存、批量操作、邻域预计算

---

## 快速上手

### 安装

```bash
pip install btcu-harness

# 可选依赖
pip install btcu-harness[llm]    # OpenAI API 支持
pip install btcu-harness[mongo]  # MongoDB 存储
pip install btcu-harness[dev]    # 开发工具
pip install btcu-harness[all]    # 全部
```

### 5 分钟入门

```python
from btcu_harness.agent import BTCUAgent
from btcu_harness.core.state import CognitiveState
from btcu_harness.llm.bridge import LLMBridge

# 1. 创建 LLM 桥接（callback 模式或 API 模式）
bridge = LLMBridge(callback=my_llm_function)
# 或：bridge = LLMBridge(api_key="sk-...", model="gpt-4o-mini")

# 2. 创建 Agent
agent = BTCUAgent(growth_stage="school")

# 3. 初始化项目（定义九维）
agent.init_project(
    domain="custom",
    dim_labels=[
        "技术深度", "用户体验", "创新性", "可维护性",
        "社区影响", "商业价值", "学习成长", "风险评估", "长期愿景",
    ],
    llm_bridge=bridge,
)

# 4. 设置使命（身份锚点）
agent.set_self_level(
    name="mission",
    description="Be a helpful cognitive companion",
    state=CognitiveState.from_values([1, 1, 1, 0, 1, 0, 1, -1, 1]),
    weight=1.0,
    stability=0.95,
)

# 5. 处理认知输入
response = agent.process("Should we focus on deep innovation?")
print(f"State: #{response.current_state.index}")
print(f"Self alignment: {response.self_alignment:.1%}")

# 6. 记录结果（触发自我强化）
agent.record_outcome(
    state=response.current_state,
    outcome_positive=True,
)

# 7. 保存认知状态
agent.save()
```

### CLI 使用

```bash
# 初始化项目
btcu init --domain agent --mission "My AI assistant"

# 投影输入
btcu project "Should we prioritize innovation?"

# 查看状态
btcu status

# 发现认知节气
btcu seasons

# 生成气候报告
btcu climate

# 探索状态空间
btcu explore --index 9841
btcu explore --values "1,0,-1,1,0,0,-1,1,-1"

# 保存/加载
btcu save
btcu load
```

---

## 架构总览

```
btcu_harness/
|-- core/              # 核心层：Trit, CognitiveState, CognitiveSpace
|-- memory/            # 记忆层：ecology, trajectory, climate, state/transition memory
|-- mapping/           # 映射层：dimension_adapter, projector, pattern_learner
|-- decision/          # 决策层：pathfinder, third_choice
|-- self_layer/        # NLP 自我层：Dilts 8 层模型
|-- llm/               # LLM 协同层：bridge (OpenAI 兼容)
|-- storage/           # 持久化层：JSON (未来 MongoDB)
|-- agent.py           # 主 Agent：11 步认知流水线
|-- cli.py             # CLI 入口
|-- config.py          # 配置 (环境变量)
|-- performance.py     # 性能优化：LRU 缓存、批量操作
|-- logging_config.py  # 日志系统
```

### 认知流水线（11 步）

| 步骤 | 认知层 | 说明 |
|------|--------|------|
| 1 | 映射世界 | 模式匹配（internalize+） |
| 2 | 映射世界 | LLM 投影（school/模式未命中时） |
| 3 | 理解世界 | 记忆回溯 |
| 4 | 理解世界 | 自我对齐检查 |
| 5 | 创造世界 | 决策路径生成 |
| 6 | 创造世界 | 第三选择生成 |
| 7 | 创造世界 | LLM 建议（可选） |
| 8 | 映射世界 | 模式学习 |
| 9 | 理解世界 | 轨迹记录 |
| 10 | 理解世界 | 记忆记录 |
| 11 | 解释世界 | 气候快照 |

---

## 核心概念

### 三态基元

| 值 | 名称 | 含义 |
|----|------|------|
| -1 | 阴 (YIN) | 否定、收缩、抑制、退守 |
| 0 | 空 (VOID) | 转化、创造、悬置、等待 |
| +1 | 阳 (YANG) | 肯定、扩张、激活、前进 |

公理：**-1 + 1 = 0**（对立交互归空）

### 19683 状态空间

九维三元向量的全组合：3^9 = 19683 个离散状态，每个有唯一编号 0-19682。

| 特殊状态 | 编号 | 含义 |
|----------|------|------|
| 全阴 | #0 | 全维度否定 |
| 全空 | #9841 | 创造潜能（中点，取反不变） |
| 全阳 | #19682 | 全维度肯定 |

### 三阶段成长

| 阶段 | LLM 依赖 | 成本模型 | 能力 |
|------|----------|----------|------|
| school | 每次调用 | C proportional to N_call | 基础投影 |
| internalize | 仅新模式 | C proportional to N_pattern_miss | 模式匹配 |
| graduate | 仅未知 | C proportional to N_unknown | 自主认知 |

---

## 文档

| 文档 | 内容 |
|------|------|
| [白皮书 v0.2](docs/BTCU_Harness_Paper_v0.2.md) | 完整架构设计 |
| [哲学基础](docs/philosophy.md) | 道生三/空性/易经/pi与e |
| [四层认知](docs/cognition_layers.md) | 映射/理解/解释/创造世界 |
| [记忆系统](docs/memory_spec.md) | 四层记忆+索引号系统 |
| [NLP 自我层](docs/nlp_self.md) | Dilts 8 层模型+吸引子 |
| [决策规格](docs/decision_spec.md) | 路径搜索+第三选择 |
| [投影器](docs/projector.md) | LLM/模式/规则投影器 |
| [开放性](docs/openness.md) | 维度自创+运算发现 |
| [存储架构](docs/storage_design.md) | JSON+MongoDB 设计 |
| [LLM 协同](docs/llm_advisor.md) | 调用时机+成本控制 |
| [安全伦理](docs/safety_ethics.md) | 威胁模型+防护机制 |
| [评估验证](docs/evaluation.md) | 基准测试+实验设计 |
| [领域模板](docs/domains/) | Agent/决策/中医/心理/教育 |

---

## 测试

```bash
# 运行全部测试
pytest tests/ -v

# 带覆盖率
pytest tests/ --cov=btcu_harness --cov-report=term-missing

# 仅集成测试
pytest tests/test_integration.py -v
```

当前：**96 项测试全部通过**，覆盖：三态运算、状态编码、空间拓扑、记忆生态、决策路径、第三选择、认知气候、性能缓存、CLI、错误处理、端到端流水线。

---

## 配置

通过环境变量或 `.env` 文件配置：

```bash
# LLM
BTCU_LLM_API_BASE=https://api.openai.com/v1
BTCU_LLM_API_KEY=your-key-here
BTCU_LLM_MODEL=gpt-4o-mini

# MongoDB (未来)
BTCU_MONGO_URI=mongodb://localhost:27017
BTCU_MONGO_DB=btcu_harness

# 认知空间
BTCU_NUM_DIMENSIONS=9
BTCU_GROWTH_STAGE=school
```

---

## 许可证

MIT License

---

## 引用

```bibtex
@software{btcu_harness,
  title={BTCU Harness: Balanced Ternary Cognitive Unit Architecture},
  author={BTCU Harness Contributors},
  year={2026},
  url={https://github.com/q1z2q3-debug/btcu-harness}
}
```
