crewforge 0.1.0__tar.gz → 0.2.1__tar.gz

{crewforge-0.1.0 → crewforge-0.2.1}/PKG-INFO

@@ -1,17 +1,22 @@
 Metadata-Version: 2.4
 Name: crewforge
-Version: 0.1.0
-Summary: One crew of LLM agents, four recipes: code review, document Q&A, API scaffolding and content — on any OpenAI-compatible provider.
+Version: 0.2.1
+Summary: One crew of LLM agents, five recipes: code review, document Q&A, API scaffolding, content and honest academic-writing help — on any OpenAI-compatible provider.
 Author: Muhammad Aiman
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/aimanmalib/crewforge
-Project-URL: Repository, https://github.com/aimanmalib/crewforge
-Project-URL: Issues, https://github.com/aimanmalib/crewforge/issues
+Project-URL: Documentation, https://github.com/aimanmalib/crewforge#readme
 Project-URL: Changelog, https://github.com/aimanmalib/crewforge/blob/main/CHANGELOG.md
-Keywords: llm,agents,multi-agent,openai,code-review,rag,fastapi,content-generation,cli
+Project-URL: Issues, https://github.com/aimanmalib/crewforge/issues
+Project-URL: Source, https://github.com/aimanmalib/crewforge
+Project-URL: Security, https://github.com/aimanmalib/crewforge/security/policy
+Keywords: llm,agents,multi-agent,ai-agents,openai,openai-compatible,code-review,rag,document-qa,fastapi,api-scaffolding,content-generation,academic-writing,cli
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Malay
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -19,8 +24,12 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
 Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: General
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -41,16 +50,20 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Requires-Dist: fastapi>=0.110; extra == "dev"
 Requires-Dist: httpx>=0.27; extra == "dev"
 Dynamic: license-file
 
 # crewforge
 
-**One crew of LLM agents, four recipes — code review, document Q&A, API scaffolding and content — on any OpenAI-compatible provider, and it fails loudly instead of pretending.**
+**One crew of LLM agents, five recipes — code review, document Q&A, API scaffolding, content and honest academic-writing help — on any OpenAI-compatible provider, and it fails loudly instead of pretending.**
 
 [![CI](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml)
-![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+[![PyPI](https://img.shields.io/pypi/v/crewforge)](https://pypi.org/project/crewforge/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aimanmalib/crewforge/badge)](https://scorecard.dev/viewer/?uri=github.com/aimanmalib/crewforge)
+![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 
 ```bash
@@ -58,6 +71,7 @@ crewforge review src/                                  # six reviewers + a summa
 crewforge ask handbook.pdf -q "How many leave days?" --verify
 crewforge scaffold "Todo API: list, create and delete todos" -o todo-api
 crewforge write "Why unit tests matter" -f markdown -f html
+crewforge academic feedback draft.md --brief brief.md --language ms
 ```
 
 <p align="center">
@@ -65,7 +79,7 @@ crewforge write "Why unit tests matter" -f markdown -f html
 </p>
 <p align="center"><sub>A real run of <code>crewforge review</code>: seven agents, ~25 s, provider-reported tokens. Recorded with <a href="https://github.com/charmbracelet/vhs">VHS</a> from <a href="https://github.com/aimanmalib/crewforge/blob/main/docs/demo/review.tape"><code>docs/demo/review.tape</code></a> using Gemini 3.8 Flash through an OpenAI-compatible gateway (the <code>custom</code> provider). The wait for the model is shown in full.</sub></p>
 
-## Why one crew, four recipes
+## Why one crew, many recipes
 
 crewforge started as four separate command-line tools —
 [codeguard](https://github.com/aimanmalib/codeguard),
@@ -87,6 +101,10 @@ apply to every recipe: non-streaming requests, bounded retries, usage numbers
 taken only from the provider, keys only from the environment, and no run that
 reports success when an agent produced nothing.
 
+A fifth recipe, `academic`, replaces a standalone "academic writing pipeline"
+that drafted essays and marketed itself as AI-detector-resistant. Only the
+honest parts were kept; see [docs/porting.md](https://github.com/aimanmalib/crewforge/blob/main/docs/porting.md#academic-from-hermes-mimo-writer).
+
 ## 60-second quickstart
 
 ```bash
@@ -128,6 +146,10 @@ tables are trimmed to their totals.
 | `scaffold "DESCRIPTION"` | parser → schema → router, model, auth, test_gen, doc_gen (parallel) → validator | A runnable FastAPI project with `openapi.json`, tests and docs |
 | `validate PATH` | validator (no LLM) | Spec check; for a project directory, also checks the app serves every spec operation |
 | `write "TOPIC"` | research → outline → writer → SEO → editor ⇄ quality → translator → publisher | Article as Markdown/HTML/JSON, social snippets, a usage file |
+| `academic plan BRIEF` | brief → planner | Research questions, an outline with a word budget that adds up, sources to find, suggested readings labelled UNVERIFIED |
+| `academic feedback DRAFT` | structure, argument, clarity, citations (parallel) + a citation cross-check (no LLM) | Comments tied to quoted text in your draft; no rewriting |
+| `academic cite REFS` | formatter | Your references in APA 7, IEEE or Harvard; nothing added, missing details listed |
+| `academic disclose` | none (no LLM) | An AI-use statement built from the record of what the tool did |
 
 ### `review`
 
@@ -151,6 +173,11 @@ total   7 calls   22,366 tokens (provider-reported)
 
 ### `ask` and `summarize`
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aimanmalib/crewforge/main/docs/demo/ask.gif" alt="Terminal demo: crewforge ask --verify answers two questions about a short project brief with [Source N] citations; the second answer says the document does not give the cost, and both answers are fact-checked claim by claim" width="900">
+</p>
+<p align="center"><sub>A real run of <code>crewforge ask --verify</code>: the answerer cites the passages it used as <code>[Source N]</code>, a second agent checks every claim against those passages, and the question the document does not answer is answered as such. Provider-reported tokens. Recorded with <a href="https://github.com/charmbracelet/vhs">VHS</a> from <a href="https://github.com/aimanmalib/crewforge/blob/main/docs/demo/ask.tape"><code>docs/demo/ask.tape</code></a> (the document is invented) using Gemini 3.8 Flash through an OpenAI-compatible gateway (the <code>custom</code> provider). The wait for the model is shown in full.</sub></p>
+
 ```text
 $ crewforge ask kestrel.md -q "How many sensors does Project Kestrel use, and who leads it?" --verify --export session.md
 ✓ ingested kestrel.md (1 chunks)
@@ -212,6 +239,73 @@ length (`--words` is a target given to the agents, not a hard limit), and the
 research agent has no web access, so statistics it quotes come from the model's
 training data. Review articles before publishing them.
 
+### `academic`
+
+An honest assistant for a student's or researcher's **own** work. It plans,
+comments and formats; it does not write the assignment, does not invent
+references, and has no "humanise" or AI-detector-evasion feature. Output in
+English or Malaysian Malay (`--language en|ms`; Malay output is checked for
+Indonesian forms such as *karena* or *kualitas*). Every step is recorded
+(file names and hashes, never content or keys) so `disclose` can write the
+AI-use statement many universities now ask for.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aimanmalib/crewforge/main/docs/demo/academic.gif" alt="Terminal demo: crewforge academic feedback --language ms comments in Malay on a student's essay draft, quoting the sentences it refers to, then a no-AI citation check lists (Lim, 2024) as cited in the text but missing from the reference list" width="900">
+</p>
+<p align="center"><sub>A real run of <code>crewforge academic feedback --language ms</code> on a short essay draft in Malay. Each comment quotes the student's own sentence and suggests a fix; nothing is rewritten. The citation check after it uses no AI: it finds <em>(Lim, 2024)</em> cited in the text but missing from the reference list. Only the <code>argument</code> reviewer is run so the result fits on one screen. Recorded with <a href="https://github.com/charmbracelet/vhs">VHS</a> from <a href="https://github.com/aimanmalib/crewforge/blob/main/docs/demo/academic.tape"><code>docs/demo/academic.tape</code></a> (draft, brief and reference are invented) using Gemini 3.8 Flash through an OpenAI-compatible gateway (the <code>custom</code> provider). The wait for the model is shown in full.</sub></p>
+
+```text
+$ crewforge academic plan brief.md -f markdown          # a 1,200-word TSL3013 essay brief
+# Assignment plan: Regulated Integration over Prohibition: ...
+- **Target length:** 1,200 words
+- **Citation style:** APA 7th edition
+## Research questions
+1. What pedagogical benefits does generative AI offer secondary school students completing homework tasks?
+...
+| # | Section | Words | Purpose |
+| 1 | Introduction | 150 | ... |   ...   Total: 1,200 words
+## Suggested readings (UNVERIFIED)
+> The AI proposed these. They may not exist, or may not say what is claimed. ...
+- ⚠ **UNVERIFIED: proposed or altered by the AI, check it** — Holmes, W., & Tuomi, I. (2022). ...
+total   2 calls   9,034 tokens (provider-reported)
+
+$ crewforge academic feedback draft.md --brief brief.md -f markdown
+## Argument
+- **Paragraph 2** (major): “Everyone knows that tuition in Malaysia is very expensive.”
+  - This is an unsupported generalization and an informal assertion rather than an evidence-based academic claim.
+  - *Suggestion:* Replace the appeal to common knowledge with scholarly evidence or empirical data ...
+## Citation check (no AI)
+**Cited in the text but not in the reference list:**
+- Lim, 2024
+total   4 calls   17,892 tokens (provider-reported)
+
+$ crewforge academic cite refs.txt --style ieee --language ms -f markdown
+[4] W. Holmes, M. Bialik, and C. Fadel, *Artificial Intelligence in Education: ...*. Center for Curriculum Redesign, 2019, ISBN: 978-1-7941-1293-0.
+  - ⚠ nombor semak ISBN salah: 9781794112930
+  - Butiran yang perlu ditambah: tempat penerbitan
+
+$ crewforge academic disclose --language ms             # no LLM, no key
+## Pernyataan Penggunaan AI
+Saya menggunakan crewforge academic (versi 0.1.0), sebuah alat berbantukan AI, dengan model gemini-3.8-flash (melalui gateway serasi OpenAI), bagi bahagian tugasan berikut:
+- 22 Oktober 2026: Perancangan: alat ini menukar taklimat tugasan (brief-ms.md) kepada 3 soalan kajian, rangka 5 bahagian dan peruntukan perkataan. ...
+```
+
+How sources are labelled — there is no "verified" status, because the tool
+cannot check that a source exists:
+
+| Source | Label |
+|---|---|
+| You supplied it | *supplied by you (not checked online)* |
+| The model proposed it, with a DOI, URL or valid ISBN | **UNVERIFIED** — check it |
+| The model proposed it with none of those | **LIKELY FABRICATED** |
+| The model added a DOI/URL/ISBN to a reference you supplied | **UNVERIFIED**, naming the added identifier |
+
+A DOI the model proposes can be made up too, which is why even those stay
+unverified. All text the student sees lives in
+`src/crewforge/recipes/academic/locales/{en,ms}.yaml`; defaults (language,
+style, log file, input size, suggestion length) are the `academic:` section of
+`crewforge.yaml`.
+
 ## Providers
 
 The table is checked against the code by `tests/test_readme.py`.
@@ -237,35 +331,9 @@ An unknown provider name is a configuration error, not a silent fallback.
 
 ## Architecture
 
-```mermaid
-flowchart LR
-    CLI["crewforge CLI<br/>review · ask · summarize · ingest<br/>scaffold · validate · write"] --> R
-
-    subgraph R["Recipes (src/crewforge/recipes)"]
-        RV[review]
-        DC[docs]
-        AP[api]
-        CT[content]
-    end
-
-    R --> CREW
-
-    subgraph CORE["Core (src/crewforge/core)"]
-        CREW["Crew<br/>step() · parallel()<br/>names failed agents"]
-        AG["Agent<br/>ask() · ask_json()<br/>rejects empty output"]
-        PA["parsing<br/>tolerant JSON + schema"]
-        CL["LLMClient<br/>stream=false · retries 429/5xx only"]
-        US["UsageTracker<br/>provider-reported tokens"]
-        CF["LLMConfig + provider presets<br/>keys from env only"]
-        CREW --> AG
-        AG --> PA
-        AG --> CL
-        AG --> US
-        CL --> CF
-    end
-
-    CL -->|"/chat/completions"| P[("Any OpenAI-compatible provider")]
-```
+<p align="center"><img src="https://raw.githubusercontent.com/aimanmalib/crewforge/main/docs/architecture.png" alt="Architecture: the CLI dispatches to five recipes; each recipe builds a Crew of Agents on the shared core (parsing, LLMClient, LLMConfig, UsageTracker), which talks to any OpenAI-compatible provider over /chat/completions" width="100%"></p>
+
+<sub>Source: [docs/architecture.mmd](https://github.com/aimanmalib/crewforge/blob/main/docs/architecture.mmd) (re-render with `scripts/render_architecture.py`).</sub>
 
 - **`core/client.py`** — one async client. It always sends `"stream": false`,
   retries only HTTP 429, 5xx and network/timeout errors (with capped exponential
@@ -317,7 +385,7 @@ Validation: INVALID · 0/100 (0 operation(s) checked, 1 error(s), 0 warning(s))
   ERROR: No endpoints defined (paths is empty)
 ```
 
-| Situation | Before (the four tools) | crewforge |
+| Situation | Before (the earlier tools) | crewforge |
 |---|---|---|
 | Every reviewer returns nothing | "Review Complete!", exit 0 | exit 1, names each reviewer |
 | A reviewer answers in prose | treated as a review | exit 1, `agent 'style' (parse)` |
@@ -327,6 +395,9 @@ Validation: INVALID · 0/100 (0 operation(s) checked, 1 error(s), 0 warning(s))
 | Quality never reaches the threshold | article published | exit 1 unless `--accept-below-threshold` |
 | Question matches no passage | model asked to answer from nothing | exit 1, names `retriever`, no LLM call |
 | Generated code does not compile | template silently reused | exit 1, names the agent |
+| Model proposes a reference with no DOI/URL/ISBN | hermes-mimo-writer put invented "plausible" references in the bibliography | labelled LIKELY FABRICATED, never verified |
+| Formatter skips a reference you supplied | n/a | exit 1, names `formatter` |
+| `disclose` finds no recorded AI use | n/a | exit 1, no statement written |
 
 Exit codes: `0` success · `1` run failed (agent, validator or provider) · `2`
 usage or configuration error (bad flag, unknown provider, missing key).
@@ -346,14 +417,15 @@ were carried over into this repository (see [docs/porting.md](https://github.com
 for what was ported, re-targeted at the shared core, or dropped and why).
 
 The evidence that it works is meant to be checkable: the test suite (run
-`pytest`; it needs no key and no network), CI on Python 3.10–3.13, and the
+`pytest`; it needs no key and no network), CI on Python 3.10–3.14, and the
 real-provider runs shown above, two of which found bugs that were fixed with
 tests before the output was recorded.
 
 ## Contributing
 
-See [CONTRIBUTING.md](https://github.com/aimanmalib/crewforge/blob/main/CONTRIBUTING.md). In short: `pip install -e ".[dev,docs]"`,
-`pytest`, `ruff check . && ruff format --check .`, and every new failure path
+See [CONTRIBUTING.md](https://github.com/aimanmalib/crewforge/blob/main/CONTRIBUTING.md). In short: `uv sync --extra dev --extra docs`
+(versions from the committed `uv.lock`, as in CI), `uv run pytest`,
+`uv run ruff check . && uv run ruff format --check .`, and every new failure path
 needs a test that fails if the guard is removed.
 
 ## Security

crewforge-0.1.0/src/crewforge.egg-info/PKG-INFO → crewforge-0.2.1/README.md

@@ -1,56 +1,11 @@
-Metadata-Version: 2.4
-Name: crewforge
-Version: 0.1.0
-Summary: One crew of LLM agents, four recipes: code review, document Q&A, API scaffolding and content — on any OpenAI-compatible provider.
-Author: Muhammad Aiman
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/aimanmalib/crewforge
-Project-URL: Repository, https://github.com/aimanmalib/crewforge
-Project-URL: Issues, https://github.com/aimanmalib/crewforge/issues
-Project-URL: Changelog, https://github.com/aimanmalib/crewforge/blob/main/CHANGELOG.md
-Keywords: llm,agents,multi-agent,openai,code-review,rag,fastapi,content-generation,cli
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: httpx>=0.27
-Requires-Dist: pydantic>=2.5
-Requires-Dist: click>=8.1
-Requires-Dist: rich>=13.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: jinja2>=3.1
-Provides-Extra: docs
-Requires-Dist: pymupdf>=1.24; extra == "docs"
-Requires-Dist: python-docx>=1.1; extra == "docs"
-Provides-Extra: api
-Requires-Dist: fastapi>=0.110; extra == "api"
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
-Requires-Dist: pytest-cov>=5.0; extra == "dev"
-Requires-Dist: ruff>=0.6; extra == "dev"
-Requires-Dist: fastapi>=0.110; extra == "dev"
-Requires-Dist: httpx>=0.27; extra == "dev"
-Dynamic: license-file
-
 # crewforge
 
-**One crew of LLM agents, four recipes — code review, document Q&A, API scaffolding and content — on any OpenAI-compatible provider, and it fails loudly instead of pretending.**
+**One crew of LLM agents, five recipes — code review, document Q&A, API scaffolding, content and honest academic-writing help — on any OpenAI-compatible provider, and it fails loudly instead of pretending.**
 
 [![CI](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml)
-![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+[![PyPI](https://img.shields.io/pypi/v/crewforge)](https://pypi.org/project/crewforge/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aimanmalib/crewforge/badge)](https://scorecard.dev/viewer/?uri=github.com/aimanmalib/crewforge)
+![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue)
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 
 ```bash
@@ -58,6 +13,7 @@ crewforge review src/                                  # six reviewers + a summa
 crewforge ask handbook.pdf -q "How many leave days?" --verify
 crewforge scaffold "Todo API: list, create and delete todos" -o todo-api
 crewforge write "Why unit tests matter" -f markdown -f html
+crewforge academic feedback draft.md --brief brief.md --language ms
 ```
 
 <p align="center">
@@ -65,7 +21,7 @@ crewforge write "Why unit tests matter" -f markdown -f html
 </p>
 <p align="center"><sub>A real run of <code>crewforge review</code>: seven agents, ~25 s, provider-reported tokens. Recorded with <a href="https://github.com/charmbracelet/vhs">VHS</a> from <a href="https://github.com/aimanmalib/crewforge/blob/main/docs/demo/review.tape"><code>docs/demo/review.tape</code></a> using Gemini 3.8 Flash through an OpenAI-compatible gateway (the <code>custom</code> provider). The wait for the model is shown in full.</sub></p>
 
-## Why one crew, four recipes
+## Why one crew, many recipes
 
 crewforge started as four separate command-line tools —
 [codeguard](https://github.com/aimanmalib/codeguard),
@@ -87,6 +43,10 @@ apply to every recipe: non-streaming requests, bounded retries, usage numbers
 taken only from the provider, keys only from the environment, and no run that
 reports success when an agent produced nothing.
 
+A fifth recipe, `academic`, replaces a standalone "academic writing pipeline"
+that drafted essays and marketed itself as AI-detector-resistant. Only the
+honest parts were kept; see [docs/porting.md](https://github.com/aimanmalib/crewforge/blob/main/docs/porting.md#academic-from-hermes-mimo-writer).
+
 ## 60-second quickstart
 
 ```bash
@@ -128,6 +88,10 @@ tables are trimmed to their totals.
 | `scaffold "DESCRIPTION"` | parser → schema → router, model, auth, test_gen, doc_gen (parallel) → validator | A runnable FastAPI project with `openapi.json`, tests and docs |
 | `validate PATH` | validator (no LLM) | Spec check; for a project directory, also checks the app serves every spec operation |
 | `write "TOPIC"` | research → outline → writer → SEO → editor ⇄ quality → translator → publisher | Article as Markdown/HTML/JSON, social snippets, a usage file |
+| `academic plan BRIEF` | brief → planner | Research questions, an outline with a word budget that adds up, sources to find, suggested readings labelled UNVERIFIED |
+| `academic feedback DRAFT` | structure, argument, clarity, citations (parallel) + a citation cross-check (no LLM) | Comments tied to quoted text in your draft; no rewriting |
+| `academic cite REFS` | formatter | Your references in APA 7, IEEE or Harvard; nothing added, missing details listed |
+| `academic disclose` | none (no LLM) | An AI-use statement built from the record of what the tool did |
 
 ### `review`
 
@@ -151,6 +115,11 @@ total   7 calls   22,366 tokens (provider-reported)
 
 ### `ask` and `summarize`
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aimanmalib/crewforge/main/docs/demo/ask.gif" alt="Terminal demo: crewforge ask --verify answers two questions about a short project brief with [Source N] citations; the second answer says the document does not give the cost, and both answers are fact-checked claim by claim" width="900">
+</p>
+<p align="center"><sub>A real run of <code>crewforge ask --verify</code>: the answerer cites the passages it used as <code>[Source N]</code>, a second agent checks every claim against those passages, and the question the document does not answer is answered as such. Provider-reported tokens. Recorded with <a href="https://github.com/charmbracelet/vhs">VHS</a> from <a href="https://github.com/aimanmalib/crewforge/blob/main/docs/demo/ask.tape"><code>docs/demo/ask.tape</code></a> (the document is invented) using Gemini 3.8 Flash through an OpenAI-compatible gateway (the <code>custom</code> provider). The wait for the model is shown in full.</sub></p>
+
 ```text
 $ crewforge ask kestrel.md -q "How many sensors does Project Kestrel use, and who leads it?" --verify --export session.md
 ✓ ingested kestrel.md (1 chunks)
@@ -212,6 +181,73 @@ length (`--words` is a target given to the agents, not a hard limit), and the
 research agent has no web access, so statistics it quotes come from the model's
 training data. Review articles before publishing them.
 
+### `academic`
+
+An honest assistant for a student's or researcher's **own** work. It plans,
+comments and formats; it does not write the assignment, does not invent
+references, and has no "humanise" or AI-detector-evasion feature. Output in
+English or Malaysian Malay (`--language en|ms`; Malay output is checked for
+Indonesian forms such as *karena* or *kualitas*). Every step is recorded
+(file names and hashes, never content or keys) so `disclose` can write the
+AI-use statement many universities now ask for.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/aimanmalib/crewforge/main/docs/demo/academic.gif" alt="Terminal demo: crewforge academic feedback --language ms comments in Malay on a student's essay draft, quoting the sentences it refers to, then a no-AI citation check lists (Lim, 2024) as cited in the text but missing from the reference list" width="900">
+</p>
+<p align="center"><sub>A real run of <code>crewforge academic feedback --language ms</code> on a short essay draft in Malay. Each comment quotes the student's own sentence and suggests a fix; nothing is rewritten. The citation check after it uses no AI: it finds <em>(Lim, 2024)</em> cited in the text but missing from the reference list. Only the <code>argument</code> reviewer is run so the result fits on one screen. Recorded with <a href="https://github.com/charmbracelet/vhs">VHS</a> from <a href="https://github.com/aimanmalib/crewforge/blob/main/docs/demo/academic.tape"><code>docs/demo/academic.tape</code></a> (draft, brief and reference are invented) using Gemini 3.8 Flash through an OpenAI-compatible gateway (the <code>custom</code> provider). The wait for the model is shown in full.</sub></p>
+
+```text
+$ crewforge academic plan brief.md -f markdown          # a 1,200-word TSL3013 essay brief
+# Assignment plan: Regulated Integration over Prohibition: ...
+- **Target length:** 1,200 words
+- **Citation style:** APA 7th edition
+## Research questions
+1. What pedagogical benefits does generative AI offer secondary school students completing homework tasks?
+...
+| # | Section | Words | Purpose |
+| 1 | Introduction | 150 | ... |   ...   Total: 1,200 words
+## Suggested readings (UNVERIFIED)
+> The AI proposed these. They may not exist, or may not say what is claimed. ...
+- ⚠ **UNVERIFIED: proposed or altered by the AI, check it** — Holmes, W., & Tuomi, I. (2022). ...
+total   2 calls   9,034 tokens (provider-reported)
+
+$ crewforge academic feedback draft.md --brief brief.md -f markdown
+## Argument
+- **Paragraph 2** (major): “Everyone knows that tuition in Malaysia is very expensive.”
+  - This is an unsupported generalization and an informal assertion rather than an evidence-based academic claim.
+  - *Suggestion:* Replace the appeal to common knowledge with scholarly evidence or empirical data ...
+## Citation check (no AI)
+**Cited in the text but not in the reference list:**
+- Lim, 2024
+total   4 calls   17,892 tokens (provider-reported)
+
+$ crewforge academic cite refs.txt --style ieee --language ms -f markdown
+[4] W. Holmes, M. Bialik, and C. Fadel, *Artificial Intelligence in Education: ...*. Center for Curriculum Redesign, 2019, ISBN: 978-1-7941-1293-0.
+  - ⚠ nombor semak ISBN salah: 9781794112930
+  - Butiran yang perlu ditambah: tempat penerbitan
+
+$ crewforge academic disclose --language ms             # no LLM, no key
+## Pernyataan Penggunaan AI
+Saya menggunakan crewforge academic (versi 0.1.0), sebuah alat berbantukan AI, dengan model gemini-3.8-flash (melalui gateway serasi OpenAI), bagi bahagian tugasan berikut:
+- 22 Oktober 2026: Perancangan: alat ini menukar taklimat tugasan (brief-ms.md) kepada 3 soalan kajian, rangka 5 bahagian dan peruntukan perkataan. ...
+```
+
+How sources are labelled — there is no "verified" status, because the tool
+cannot check that a source exists:
+
+| Source | Label |
+|---|---|
+| You supplied it | *supplied by you (not checked online)* |
+| The model proposed it, with a DOI, URL or valid ISBN | **UNVERIFIED** — check it |
+| The model proposed it with none of those | **LIKELY FABRICATED** |
+| The model added a DOI/URL/ISBN to a reference you supplied | **UNVERIFIED**, naming the added identifier |
+
+A DOI the model proposes can be made up too, which is why even those stay
+unverified. All text the student sees lives in
+`src/crewforge/recipes/academic/locales/{en,ms}.yaml`; defaults (language,
+style, log file, input size, suggestion length) are the `academic:` section of
+`crewforge.yaml`.
+
 ## Providers
 
 The table is checked against the code by `tests/test_readme.py`.
@@ -237,35 +273,9 @@ An unknown provider name is a configuration error, not a silent fallback.
 
 ## Architecture
 
-```mermaid
-flowchart LR
-    CLI["crewforge CLI<br/>review · ask · summarize · ingest<br/>scaffold · validate · write"] --> R
-
-    subgraph R["Recipes (src/crewforge/recipes)"]
-        RV[review]
-        DC[docs]
-        AP[api]
-        CT[content]
-    end
-
-    R --> CREW
-
-    subgraph CORE["Core (src/crewforge/core)"]
-        CREW["Crew<br/>step() · parallel()<br/>names failed agents"]
-        AG["Agent<br/>ask() · ask_json()<br/>rejects empty output"]
-        PA["parsing<br/>tolerant JSON + schema"]
-        CL["LLMClient<br/>stream=false · retries 429/5xx only"]
-        US["UsageTracker<br/>provider-reported tokens"]
-        CF["LLMConfig + provider presets<br/>keys from env only"]
-        CREW --> AG
-        AG --> PA
-        AG --> CL
-        AG --> US
-        CL --> CF
-    end
-
-    CL -->|"/chat/completions"| P[("Any OpenAI-compatible provider")]
-```
+<p align="center"><img src="https://raw.githubusercontent.com/aimanmalib/crewforge/main/docs/architecture.png" alt="Architecture: the CLI dispatches to five recipes; each recipe builds a Crew of Agents on the shared core (parsing, LLMClient, LLMConfig, UsageTracker), which talks to any OpenAI-compatible provider over /chat/completions" width="100%"></p>
+
+<sub>Source: [docs/architecture.mmd](https://github.com/aimanmalib/crewforge/blob/main/docs/architecture.mmd) (re-render with `scripts/render_architecture.py`).</sub>
 
 - **`core/client.py`** — one async client. It always sends `"stream": false`,
   retries only HTTP 429, 5xx and network/timeout errors (with capped exponential
@@ -317,7 +327,7 @@ Validation: INVALID · 0/100 (0 operation(s) checked, 1 error(s), 0 warning(s))
   ERROR: No endpoints defined (paths is empty)
 ```
 
-| Situation | Before (the four tools) | crewforge |
+| Situation | Before (the earlier tools) | crewforge |
 |---|---|---|
 | Every reviewer returns nothing | "Review Complete!", exit 0 | exit 1, names each reviewer |
 | A reviewer answers in prose | treated as a review | exit 1, `agent 'style' (parse)` |
@@ -327,6 +337,9 @@ Validation: INVALID · 0/100 (0 operation(s) checked, 1 error(s), 0 warning(s))
 | Quality never reaches the threshold | article published | exit 1 unless `--accept-below-threshold` |
 | Question matches no passage | model asked to answer from nothing | exit 1, names `retriever`, no LLM call |
 | Generated code does not compile | template silently reused | exit 1, names the agent |
+| Model proposes a reference with no DOI/URL/ISBN | hermes-mimo-writer put invented "plausible" references in the bibliography | labelled LIKELY FABRICATED, never verified |
+| Formatter skips a reference you supplied | n/a | exit 1, names `formatter` |
+| `disclose` finds no recorded AI use | n/a | exit 1, no statement written |
 
 Exit codes: `0` success · `1` run failed (agent, validator or provider) · `2`
 usage or configuration error (bad flag, unknown provider, missing key).
@@ -346,14 +359,15 @@ were carried over into this repository (see [docs/porting.md](https://github.com
 for what was ported, re-targeted at the shared core, or dropped and why).
 
 The evidence that it works is meant to be checkable: the test suite (run
-`pytest`; it needs no key and no network), CI on Python 3.10–3.13, and the
+`pytest`; it needs no key and no network), CI on Python 3.10–3.14, and the
 real-provider runs shown above, two of which found bugs that were fixed with
 tests before the output was recorded.
 
 ## Contributing
 
-See [CONTRIBUTING.md](https://github.com/aimanmalib/crewforge/blob/main/CONTRIBUTING.md). In short: `pip install -e ".[dev,docs]"`,
-`pytest`, `ruff check . && ruff format --check .`, and every new failure path
+See [CONTRIBUTING.md](https://github.com/aimanmalib/crewforge/blob/main/CONTRIBUTING.md). In short: `uv sync --extra dev --extra docs`
+(versions from the committed `uv.lock`, as in CI), `uv run pytest`,
+`uv run ruff check . && uv run ruff format --check .`, and every new failure path
 needs a test that fails if the guard is removed.
 
 ## Security

{crewforge-0.1.0 → crewforge-0.2.1}/pyproject.toml

@@ -4,18 +4,36 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crewforge"
-version = "0.1.0"
-description = "One crew of LLM agents, four recipes: code review, document Q&A, API scaffolding and content — on any OpenAI-compatible provider."
+version = "0.2.1"
+description = "One crew of LLM agents, five recipes: code review, document Q&A, API scaffolding, content and honest academic-writing help — on any OpenAI-compatible provider."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.10"
 authors = [{ name = "Muhammad Aiman" }]
-keywords = ["llm", "agents", "multi-agent", "openai", "code-review", "rag", "fastapi", "content-generation", "cli"]
+keywords = [
+    "llm",
+    "agents",
+    "multi-agent",
+    "ai-agents",
+    "openai",
+    "openai-compatible",
+    "code-review",
+    "rag",
+    "document-qa",
+    "fastapi",
+    "api-scaffolding",
+    "content-generation",
+    "academic-writing",
+    "cli",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",
     "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Natural Language :: English",
+    "Natural Language :: Malay",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
@@ -23,8 +41,12 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Code Generators",
     "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Text Processing :: General",
     "Typing :: Typed",
 ]
 dependencies = [
@@ -44,15 +66,19 @@ dev = [
     "pytest-asyncio>=0.23",
     "pytest-cov>=5.0",
     "ruff>=0.6",
+    "mypy>=1.10",
+    "types-PyYAML>=6.0",
     "fastapi>=0.110",
     "httpx>=0.27",
 ]
 
 [project.urls]
 Homepage = "https://github.com/aimanmalib/crewforge"
-Repository = "https://github.com/aimanmalib/crewforge"
-Issues = "https://github.com/aimanmalib/crewforge/issues"
+Documentation = "https://github.com/aimanmalib/crewforge#readme"
 Changelog = "https://github.com/aimanmalib/crewforge/blob/main/CHANGELOG.md"
+Issues = "https://github.com/aimanmalib/crewforge/issues"
+Source = "https://github.com/aimanmalib/crewforge"
+Security = "https://github.com/aimanmalib/crewforge/security/policy"
 
 [project.scripts]
 crewforge = "crewforge.cli:main"
@@ -61,7 +87,7 @@ crewforge = "crewforge.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-crewforge = ["py.typed", "recipes/api/templates/*.j2"]
+crewforge = ["py.typed", "recipes/api/templates/*.j2", "recipes/academic/locales/*.yaml"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -80,6 +106,22 @@ select = ["E", "F", "W", "I", "UP", "B"]
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["B011"]
 
+[tool.mypy]
+# CI runs `mypy` (lint job). Bodies of unannotated functions are checked too.
+files = ["src/crewforge"]
+python_version = "3.10"
+plugins = ["pydantic.mypy"]
+check_untyped_defs = true
+strict_equality = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+# Pre-1.24 PyMuPDF import name, used only as a fallback; it ships no type information.
+module = ["fitz"]
+ignore_missing_imports = true
+
 [tool.coverage.run]
 source = ["crewforge"]
 branch = true

crewforge-0.2.1/src/crewforge/__init__.py

@@ -0,0 +1,3 @@
+"""crewforge — one crew of LLM agents, five recipes, any OpenAI-compatible provider."""
+
+__version__ = "0.2.1"