Metadata-Version: 2.4
Name: engawa-scholar
Version: 0.2.0
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の決定的な処理とテスト、7つの
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として明示保存し、過去版と最新草稿を往復する
- 文献探索、推敲、ミラー、版操作、TeX環境診断、background build、engawaへのfeedbackを自然言語から扱う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 repositoryでなければ`main` branchで初期化します。
既存repositoryでは現在のbranch、remote、履歴を変更しません。

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

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へ導入する

新しい論文なら、空のdirectoryでそのまま始められます。

```console
mkdir my-paper
cd my-paper
uvx engawa-scholar init .
git status
uvx engawa-scholar status
uvx engawa-scholar check all
```

既存repositoryへ導入する場合も、そのrootで同じ`init .`を実行します。既存ファイルは
上書きしません。`manuscript/`が既にあれば、そのlayoutと内容をそのまま使います。
存在しない場合だけ、日英それぞれの`main.tex`と基本sectionを含む雛形を作ります。

```text
.engawa/config.toml           # bibliography、version、build設定
.agents/skills/engawa-*       # Codex向けSkill
.codex/agents/engawa-builder.toml # background build用agent
AGENTS.md                     # engawaの短いrepository指示
Makefile                      # PDF buildとcheckの短い入口
references/library.bib        # 人間が追加・acceptした引用可能文献
references/candidates.bib     # AIが探索した未承認候補
references/reference.md       # 候補の概要と確認範囲
materials/README.md           # 過去原稿、論文PDF、補助資料などの置き場
manuscript/{ja,en}/main.tex   # 最小構成のLaTeX entry point
```

生成する雛形は次の構成です。

```text
manuscript/
├── figures/                   # 日英で共有する図とそのsource
├── ja/
│   ├── main.tex
│   └── sections/
│       ├── abstract.tex
│       ├── introduction.tex
│       ├── methods.tex
│       ├── results.tex
│       ├── discussion.tex
│       └── conclusion.tex
└── en/
    ├── main.tex
    └── sections/              # jaと同じ6 section
```

日本語版は`jlreq`、英語版は標準`article`を使う編集開始用の雛形です。投稿先の
document classやbuild commandへ適宜置き換えてください。engawaは既存原稿の
directory構成を強制しません。既存projectでは、実際のTeXとreference fileが
`.engawa/config.toml`の`version.include`に含まれるよう調整してください。
`materials/`は現在の原稿とは別の参考資料用で、engawaのsnapshot対象には既定で
含まれません。必要に応じて`previous-manuscripts/`、`papers/`、`notes/`などに
分けて使えます。

## 日常の使い方

原稿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を同梱しません。初期設定は`latexmk`を使い、日本語版を
LuaLaTeX、英語版をpdfLaTeXでbuildします。投稿先や既存projectに合わせる場合は
`.engawa/config.toml`のcommandを変更してください。commandはtrusted project codeとして
shellを挟まずargvで実行されます。

```toml
[build.ja]
main = "main.tex"
cwd = "manuscript/ja"
output_dir = ".engawa/build/ja"
command = ["latexmk", "-lualatex", "-interaction=nonstopmode", "-halt-on-error", "-outdir={output_dir}", "{main}"]
timeout_seconds = 120

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

```console
make pdf
make pdf-ja
make pdf-en
make check

# Makeを使わない場合
uvx engawa-scholar build ja
uvx engawa-scholar build en
```

引数なしの`make`も`make pdf`と同じです。`Makefile`はengawa CLIのpreflight、build、
postflightをそのまま利用し、PDFを直接別経路で生成しません。通常インストールした
CLIを使う場合は、たとえば`make ENGAWA=engawa pdf`と上書きできます。

結果は`.engawa/build/<target>/`へ保存され、履歴は蓄積せず最新結果だけを更新します。
各runはversion authoring setとconfigを固定した一時snapshot上でpreflight、組版、
postflightを行います。開始時と昇格時のsource digestが一致し、今回のPDFも確認できた
場合だけlatest PDFへ反映します。build中に原稿が変わったrunは`stale`となり、以前の
PDFを保持します。必要なclass、figure、scriptなどのproject-local build inputは
`.engawa/config.toml`の`version.include`へ含めてください。`output_dir`はauthoring set
の外でなければなりません。build commandのnetwork、filesystem、subprocessは
sandboxされません。

### Build中も会話を続ける

Codexへ「PDFをbackgroundでbuildして。待っている間は別の相談を続けたい」と依頼すると、
`engawa-build` Skillがprojectの`engawa-builder` agentへbuildを委譲します。メインthreadは
相談やread-only作業を続けられます。builderは成功結果を要約し、修復も依頼されている
場合だけ、明白なTeX構文や既存fileへのpath typoを一回修正して再buildします。

build中は同じTeX、BibTeX、figure、configをメインagentから編集しません。外部変更が
あった場合もdigest不一致でPDF昇格を止め、builderは古いsnapshotを元に修復せずメインへ
返します。package導入、引用、科学的内容、曖昧なlabelやfigureは自動判断しません。

### TeX環境を用意する

Codexへ「`make pdf`が動くようにTeX環境を診断して」「TeX Liveを入れたい」と
依頼すると、`engawa-setup-tex` Skillが既存環境を先に検査します。既に必要なtoolと
classがあればインストールは行いません。不足がある場合はOSに合う公式GUIまたは
package managerの選択肢と容量・権限・更新方法を示し、明示的な選択と承認を得てから
導入します。診断だけの依頼でsystem packageやPATHを変更することはありません。

### engawaへfeedbackを送る

Codexへ「この不具合をengawaへ報告して」「この改善案をissueにしたい」と依頼すると、
`feedback-engawa` Skillが既存issueとの重複を確認し、再現手順や環境情報を整理します。
原稿本文、未公開結果、credential、local absolute pathなどは含めません。公開されるtitleと
bodyを提示し、明示的な確認を得た後にだけ`Nkzono99/engawa`へGitHub Issueを作成します。

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

`.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)です。
