Metadata-Version: 2.4
Name: py-dianoia
Version: 0.2.1
Summary: Open-source expert reasoning framework distillation tool
Author: Dianoia AI Contributors
License: Apache-2.0
Keywords: ai,llm,distillation,expert-reasoning,code-review,skill-extraction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: openai>=1.0
Requires-Dist: anthropic>=0.18
Requires-Dist: tenacity>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Dianoia AI 格物致知

![CI](https://github.com/bigmoon-dev/dianoia-ai/actions/workflows/ci.yml/badge.svg?v=2)
![Coverage](https://img.shields.io/badge/coverage-77%25-yellowgreen?v=3)
![PyPI](https://img.shields.io/pypi/v/py-dianoia?color=blue&v=2)
![Python](https://img.shields.io/pypi/pyversions/py-dianoia?color=blue&v=2)
![Issues](https://img.shields.io/github/issues/bigmoon-dev/dianoia-ai)
![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?v=2)
![Downloads](https://img.shields.io/pypi/dm/py-dianoia?v=2)

> Open-source expert reasoning framework distillation tool

[English](#english) | [中文](./README.zh-CN.md)

---

<a id="english"></a>

## What is Dianoia?

Dianoia (格物致知) distills expert reasoning patterns from public artifacts — documents, code reviews, design docs — into **profile.yaml** and **SKILL.md** formats that any AI agent can consume.

Unlike knowledge extraction, Dianoia captures **how experts think**: how they define problems, judge quality, prioritize trade-offs, and decide when "good enough" is acceptable.

Inspired by [The Relic Condition](https://arxiv.org/abs/2604.16116) research on reasoning architecture extraction.

## Install

```bash
pip install py-dianoia
```

Requires Python 3.11+

## Quick Start

```bash
# 1. Initialize a project
dianoia init my-expert

# 2. Add corpus files to my-expert/corpus/
cp ~/expert-docs/*.md my-expert/corpus/

# 3. Extract reasoning patterns
dianoia extract my-expert

# 4. Build output files (profile.yaml + SKILL.md)
dianoia build my-expert

# 5. Validate outputs
dianoia validate my-expert
```

## V2 Features

### Interactive TUI for Expert Reasoning

**`dianoia tui init`** — First-run setup wizard to configure your LLM provider, model, API key, and expert directory. Saves to `~/.config/dianoia/config.yaml`.

**`dianoia tui`** — Launch an interactive terminal session to reason with a distilled expert. Select an expert from your configured experts directory and start a phase-guided reasoning conversation.

### Interactive Model Switching

Switch providers and models mid-session with `/model`. Supports 11 providers across international and China markets.

### File Reading and Modification

Mention a file path in chat and the expert auto-reads it. After discussion, use `/apply` to let the expert write changes back — with preview, confirmation, and automatic `.bak` backup.

### Supported Providers

| Provider | Models | Env Var |
|----------|--------|---------|
| OpenAI | gpt-4o, o3, o4-mini | `OPENAI_API_KEY` |
| Anthropic | Claude Sonnet 4, Opus 4 | `ANTHROPIC_API_KEY` |
| Google | Gemini 2.5 Pro | `GOOGLE_API_KEY` |
| Groq | llama, mixtral | `GROQ_API_KEY` |
| Mistral | mistral-large, mistral-medium | `MISTRAL_API_KEY` |
| xAI | grok | `XAI_API_KEY` |
| Together AI | open-source models | `TOGETHER_API_KEY` |
| DeepSeek | deepseek-chat, deepseek-reasoner | `DEEPSEEK_API_KEY` |
| Zhipu/智谱 | glm-4-flash, glm-5.1 | `ZHIPU_API_KEY` |
| Moonshot/月之暗面 | moonshot-v1, kimi-k2 | `MOONSHOT_API_KEY` |
| Alibaba Qwen/阿里百炼 | qwen-turbo, qwen-plus, qwen-max | `DASHSCOPE_API_KEY` |

## V2 TUI Quick Start

```bash
# First time setup — configure provider, model, API key, experts directory
dianoia tui init

# Distill an expert (existing CLI workflow)
dianoia init my-expert
cp ~/docs/*.md my-expert/corpus/
dianoia extract my-expert
dianoia build my-expert

# Chat with your distilled expert
dianoia tui
```

## Architecture

```
Corpus Files → ExtractionPipeline (8 layers) → IR → ProfileMapper → profile.yaml
                                                     → SkillRenderer  → SKILL.md
```

### 8-Layer Extraction Method

| # | Layer | Extracts |
|---|-------|----------|
| 1 | Ontological | Problem boundaries, classification systems |
| 2 | Teleological | Goals, purposes, end-driven reasoning |
| 3 | Methodological | Procedures, systematic approaches |
| 4 | Axiological | Values, priorities, decision criteria |
| 5 | Epistemological | Knowledge sources, evidence standards |
| 6 | Conditional | Context-dependent decisions |
| 7 | Priority | Trade-off ordering (engineering-specific) |
| 8 | Pragmatic | "Good enough" thresholds, practical shortcuts |

### Stability Filtering

Features only survive if they appear in ≥2 independent texts AND ≥3 distinct contexts. This filters noise and ensures distilled patterns represent genuine expert consensus.

## Output Formats

### profile.yaml

Structured data for workflow engines (e.g., kitchen-ent):

```yaml
version: "1.0"
sections:
  identity:
    - key: domain
      value: engineering
      confidence: 0.85
      sources: [doc1.md, doc2.md]
```

### SKILL.md

Follows the [Agent Skills](https://agentskills.io) open standard:

```markdown
---
name: "my-expert"
description: "Expert reasoning distilled from ..."
---

# My Expert

## Extracted Reasoning Patterns
...
```

## Language Overlay

Distill once in a language-agnostic base profile, then overlay language-specific customizations:

```
base-profile.yaml (language-agnostic skeleton)
  + overlay-python.yaml
  + overlay-rust.yaml
  + overlay-go.yaml
```

## Documentation

- [Distillation Principle](docs/distillation-principle.md)
- [Architecture](docs/architecture.md)
- [CLI Reference](docs/cli-reference.md)
- [Language Overlay](docs/language-overlay.md)
- [Profile Deliverable](docs/profile-deliverable.md)
- [SKILL Deliverable](docs/skill-deliverable.md)
- [Contributing](docs/contributing.md)

## Specifications

- [IR Schema](spec/ir-schema.json) — JSON Schema for the Intermediate Representation
- [Profile Spec](spec/profile-spec.yaml) — profile.yaml format specification
- [SKILL Spec](spec/skill-spec.md) — SKILL.md format specification

## Development

```bash
git clone https://github.com/bigmoon-dev/dianoia-ai.git
cd dianoia-ai
pip install -e ".[dev]"
pytest
```

## License

Apache-2.0
