Metadata-Version: 2.4
Name: engawa-scholar
Version: 0.1.1
Summary: Human-led scholarly writing, with AI at the margins
Author: Nkzono99
License-Expression: MIT
Project-URL: Homepage, https://github.com/Nkzono99/engawa
Project-URL: Repository, https://github.com/Nkzono99/engawa
Project-URL: Issues, https://github.com/Nkzono99/engawa/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# engawa

Human-led scholarly writing, with AI at the margins.

engawaは、人間がLaTeX原稿を主導して書き、CodexなどのAIに文献探索、
推敲、日英ミラー、組版、版の退避と復元を任せるためのrepository-localな
CLIとSkillです。日常的に見るものは原稿のTeXとAIとの会話だけに絞り、
Gitとengawaのsnapshotを安全網として使います。

現在は初期usable versionです。CLIの決定的な処理とテスト、4つの
repository-local Skillを含みます。仕様の正本は
[SPEC.md](https://github.com/Nkzono99/engawa/blob/main/SPEC.md)です。

## できること

- accepted/candidate bibliographyを分離し、未承認文献の引用混入を検出する
- 引用、参照、数式、図表などのTeX anchorを静的検査する
- projectが設定したLaTeX build commandを実行し、最新PDFとlogを保存する
- 日本語TeXと英語TeXをfile単位で安全にミラーする
- working treeの原稿をGit objectとして明示保存し、過去版と最新草稿を往復する
- 文献探索、推敲、ミラー、版操作を自然言語から扱うSkillを導入する

engawa自身はLLM APIを呼びません。文章生成と検索は、原稿repositoryで起動した
CodexなどがSkillに従って行い、CLIは検査、状態管理、build、snapshotを担当します。

## 必要なもの

- [uv](https://docs.astral.sh/uv/)
- Git
- Codexなどrepository-local Skillを利用できるAI（AIなしでもCLIは使用可能）
- buildする場合だけ、projectで使用するTeX distributionとbuild tool

`engawa init`は`git init`を実行しません。導入先は既存のGit repositoryである
必要があります。

## インストールせずに使う

PyPI上のdistribution名は`engawa-scholar`です。`uvx`が隔離環境を自動作成して
cacheするため、engawa自体の事前installや仮想環境の管理は不要です。

```console
uvx engawa-scholar --version
```

通常のpackageとしてinstallする場合も、短い`engawa` commandを利用できます。

```console
uv tool install engawa-scholar
engawa --version
```

## 論文repositoryへ導入する

導入先のrootで実行します。

```console
cd path/to/paper
git status
uvx engawa-scholar init .
uvx engawa-scholar status
uvx engawa-scholar check all
```

既存ファイルは上書きしません。初期化により、足りないものだけが追加されます。

```text
.engawa/config.toml           # bibliography、version、build設定
.agents/skills/engawa-*       # Codex向けSkill
AGENTS.md                     # engawaの短いrepository指示
references/library.bib        # 人間が追加・acceptした引用可能文献
references/candidates.bib     # AIが探索した未承認候補
references/reference.md       # 候補の概要と確認範囲
```

原稿のdirectory構成は強制しません。既定では`manuscript/**`をversion対象にするため、
例えば次のように置けます。

```text
manuscript/
├── ja/
│   ├── main.tex
│   └── sections/
└── en/
    ├── main.tex
    └── sections/
```

既存projectでは、実際のTeXとreference fileが
`.engawa/config.toml`の`version.include`に含まれるよう調整してください。

## 日常の使い方

原稿repositoryのrootでCodexを起動し、通常の言葉で依頼します。

```text
この段落を、主張と不確実性を変えずに読みやすくして
この主張を支持する最近の文献を探して。まだ引用には入れないで
候補のsmith2025をacceptして、この文末に引用を追加して
日本語版のintroductionの変更を英語版へ反映して
いまの原稿を「before-analysis」として保存して
前の版を試したい。あとで最新へ戻れるようにして
```

AIは対象TeXを直接編集します。通常の編集前にsnapshotを自動作成せず、保存を依頼した
場合だけ`version save`を使います。変更後は関連する`engawa check`を実行し、変更箇所と
未解決事項を短く報告します。

### 実行モデル

engawaは、依頼を満たす最小十分なworkflowで著者が認識できる進捗を早く返すことを
目標にします。一つのcontext ownerが読解から編集、検査までを一貫して扱い、通常編集は
一回の編集と一回の成功した関連検査で完了します。CLIは文章生成やLLM orchestrationを
行わないため、coordination overheadを追加しません。

全体reviewでは、依頼されたcoverageを満たすために読む範囲と検査を広げ、必要な時間を
使います。日本語可読性ガイドは、明示的な読みやすさ改善または段落以上の改稿でだけ
context ownerが参照します。

### 日本語の読みやすさ

`engawa-polish`には、段落の役割、論証のつながり、指示対象、認知負荷、冗長な
LLM調の表現を点検する軽量ガイドを同梱しています。これは技術書向けの文章規範を
論文用に翻案した観点であり、固定文体ではありません。著者の文体、投稿先の
規定、科学的な正確さを優先し、敬体化、一文一行、劇的な語りなどを強制しません。

## 文献の扱い

引用可能な正本は`references/library.bib`です。AIが見つけた文献は、実在性とmetadataを
確認した後でも、まず`references/candidates.bib`と`references/reference.md`へ入ります。
人間が文献を指定またはacceptするまでTeXへ引用しません。

```console
uvx engawa-scholar check all
```

この検査はcandidate-only citation、未登録またはcandidate bibliographyのbuild登録、
重複key・DOI・arXiv ID、未定義のcitation/referenceなどを検出します。

## Buildを設定する

engawaはTeX distributionを同梱しません。`.engawa/config.toml`へproject固有のcommandを
argvとして設定します。commandはtrusted project codeとしてshellを挟まず実行されます。

```toml
[build.ja]
main = "main.tex"
cwd = "manuscript/ja"
output_dir = ".engawa/build/ja"
command = ["latexmk", "-pdf", "-outdir={output_dir}", "{main}"]
timeout_seconds = 120

[build.en]
main = "main.tex"
cwd = "manuscript/en"
output_dir = ".engawa/build/en"
command = ["latexmk", "-pdf", "-outdir={output_dir}", "{main}"]
timeout_seconds = 120
```

```console
uvx engawa-scholar build ja
uvx engawa-scholar build en
```

結果は`.engawa/build/<target>/`へ保存され、履歴は蓄積せず最新結果だけを更新します。
各runは固有の一時outputへ生成し、今回のPDFとpost-build checkを確認してからだけ
latest PDFへ反映します。失敗時に以前のPDFを今回の成功結果として報告しません。
build commandのnetwork、filesystem、subprocessはsandboxされません。

## 日英ミラーを設定する

`.engawa/mirror.toml`にfile pairを登録します。

```toml
schema_version = 1

[[pair]]
id = "introduction"
source = "manuscript/ja/sections/introduction.tex"
target = "manuscript/en/sections/introduction.tex"
```

```console
uvx engawa-scholar mirror status introduction
```

通常はCodexへ「introductionを英語版へ反映して」と依頼してください。Skillは
`mirror begin`で同時変更を監視し、英語TeXを直接編集した後、anchorとhashを検査して
`mirror finalize`します。英語側にも独自変更がある場合は黙って上書きしません。

既に意味が対応しているpairを初めて登録した場合だけ、人間の確認後にbaselineを採用します。

```console
uvx engawa-scholar mirror adopt introduction
```

## 原稿の版を保存する

```console
uvx engawa-scholar version save first-draft
uvx engawa-scholar version list
uvx engawa-scholar version diff first-draft
uvx engawa-scholar version switch first-draft
uvx engawa-scholar version latest
```

`switch`は切替直前の草稿を自動保存します。過去版を編集中に`latest`を実行すると、その編集も
保存してから最初の最新草稿へ戻ります。特定のTeX fileだけを再利用することもできます。

```console
uvx engawa-scholar version take first-draft --file manuscript/ja/sections/method.tex
```

snapshotはlocal Git objectとnamespaced tagだけで構成され、通常のindex、HEAD、branchを
変更しません。保存前後と復元直前にauthoring set全体のpath、literal bytes、Git modeを
検査し、同時変更があれば原稿を書き換えず停止します。`.git`、engawaのcache/build、
submoduleはauthoring setへ取り込みません。現在、snapshotの`push / fetch`とblock単位の
`take`は未実装です。

## CLI概要

```text
uvx engawa-scholar init [path]
uvx engawa-scholar status
uvx engawa-scholar check [ja|en|all]
uvx engawa-scholar build [ja|en|all]
uvx engawa-scholar mirror status|begin|finalize|abort|adopt ...
uvx engawa-scholar version save|list|show|diff|switch|latest|take|adopt|recover ...
```

診断commandは`--json`に対応します。exit codeは成功が`0`、検査・build・競合などの
作業上の失敗が`1`、設定不備または利用不能機能が`2`、復旧が必要な中断状態が`3`です。

## 設計上の境界

- research question、story、claim、結果解釈、結論は人間が決める
- TeXへ会話ログ、approval台帳、engawa固有markerを増やさない
- AIは明示依頼なしにcommit、push、投稿、メール、submissionを行わない
- acceptedになった文献も、個々のclaimを支持するかは別途確認する
- build成功は最終PDFの視覚確認や論文完成を意味しない

詳細な安全保証、snapshot format、check項目は
[SPEC.md](https://github.com/Nkzono99/engawa/blob/main/SPEC.md)を参照してください。

## 開発

```console
git clone https://github.com/Nkzono99/engawa.git
cd engawa
uv sync --extra dev
uv run python -m compileall -q src
uv run pytest
uv build --no-sources
```

テストは一時Git repositoryだけを使用し、networkへ接続しません。

## ライセンス

[MIT License](https://github.com/Nkzono99/engawa/blob/main/LICENSE)です。
