crewforge 0.2.0__tar.gz → 0.2.1__tar.gz

{crewforge-0.2.0/src/crewforge.egg-info → crewforge-0.2.1}/PKG-INFO

@@ -1,17 +1,22 @@
 Metadata-Version: 2.4
 Name: crewforge
-Version: 0.2.0
+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,academic-writing,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,6 +50,8 @@ 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
@@ -51,7 +62,8 @@ Dynamic: license-file
 
 [![CI](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/crewforge)](https://pypi.org/project/crewforge/)
-![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+[![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
@@ -161,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)
@@ -232,6 +249,11 @@ 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: ...
@@ -309,36 +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<br/>academic plan · feedback · cite · disclose"] --> R
-
-    subgraph R["Recipes (src/crewforge/recipes)"]
-        RV[review]
-        DC[docs]
-        AP[api]
-        CT[content]
-        AC[academic]
-    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
@@ -422,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.2.0 → crewforge-0.2.1}/README.md

@@ -4,7 +4,8 @@
 
 [![CI](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/crewforge)](https://pypi.org/project/crewforge/)
-![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+[![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
@@ -114,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)
@@ -185,6 +191,11 @@ 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: ...
@@ -262,36 +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<br/>academic plan · feedback · cite · disclose"] --> R
-
-    subgraph R["Recipes (src/crewforge/recipes)"]
-        RV[review]
-        DC[docs]
-        AP[api]
-        CT[content]
-        AC[academic]
-    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
@@ -375,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.2.0 → crewforge-0.2.1}/pyproject.toml

@@ -4,18 +4,36 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crewforge"
-version = "0.2.0"
+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", "academic-writing", "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"
@@ -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.0 → crewforge-0.2.1}/src/crewforge/__init__.py

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

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/academic/citations.py

@@ -66,12 +66,13 @@ class Identifiers:
 def identifiers(text: str) -> Identifiers:
     """Find the identifiers in a reference. URLs pointing at doi.org count as the DOI."""
     dois = {_strip_trailing(m.group(1)).lower() for m in _DOI.finditer(text)}
-    urls = set()
+    urls: set[str] = set()
     for m in _URL.finditer(text):
         url = _strip_trailing(m.group(0)).rstrip("/")
         if not any(host in url.lower() for host in _DOI_HOSTS):
             urls.add(url)
-    valid, invalid = set(), set()
+    valid: set[str] = set()
+    invalid: set[str] = set()
     # Springer-style DOIs embed an ISBN ("10.1007/978-3-..."): search the rest only.
     rest = _URL.sub(" ", _DOI.sub(" ", text))
     raw_isbns = [m.group(1) for m in _ISBN_LABELLED.finditer(rest)]

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/academic/cli.py

@@ -21,6 +21,7 @@ from ...cli_support import (
     run,
 )
 from ...core.errors import ConfigError
+from ...core.usage import UsageTracker
 from ..docs.ingest import IngestAgent
 from .agents import FEEDBACK_AGENTS, STYLES
 from .citations import split_references
@@ -147,6 +148,14 @@ def _record(
     err_console.print(t(language, "labels.recorded", path=path), highlight=False, soft_wrap=True)
 
 
+def _usage(tracker: UsageTracker | None) -> int:
+    """Print the provider-reported usage table and return its token total."""
+    if tracker is None:  # every AcademicCrew result carries its tracker
+        raise RuntimeError("academic step returned no usage tracker")
+    print_usage(tracker)
+    return tracker.total_tokens
+
+
 def _header(ctx: click.Context, step: str, target: str, language: str) -> None:
     config = llm_config(ctx)
     err_console.print(
@@ -190,7 +199,7 @@ def plan_cmd(ctx, brief, words, language, style, fmt, output, log_path, no_log):
     result = run(crew.plan(text, words=words, style=style.lower() if style else None))
     _emit(plan_markdown(result), plan_dict(result), fmt, output)
     _warn_malay(result.malay_issues, language)
-    print_usage(result.tracker)
+    tokens = _usage(result.tracker)
     _record(
         ctx,
         settings,
@@ -201,7 +210,7 @@ def plan_cmd(ctx, brief, words, language, style, fmt, output, log_path, no_log):
         inputs=[(brief, text)],
         counts=result.counts(),
         style=result.style,
-        tokens=result.tracker.total_tokens,
+        tokens=tokens,
     )
 
 
@@ -252,7 +261,7 @@ def feedback_cmd(
     )
     _emit(feedback_markdown(result), feedback_dict(result), fmt, output)
     _warn_malay(result.malay_issues, language)
-    print_usage(result.tracker)
+    tokens = _usage(result.tracker)
     inputs = [(draft, text)] + ([(brief_path, brief_text)] if brief_path else [])
     _record(
         ctx,
@@ -264,7 +273,7 @@ def feedback_cmd(
         inputs=inputs,
         counts=result.counts(),
         style=result.style,
-        tokens=result.tracker.total_tokens,
+        tokens=tokens,
     )
 
 
@@ -285,7 +294,7 @@ def cite_cmd(ctx, references, language, style, fmt, output, log_path, no_log):
     crew = AcademicCrew(llm_config(ctx), language=language)
     result = run(crew.cite(refs, style=style))
     _emit(cite_markdown(result), cite_dict(result), fmt, output)
-    print_usage(result.tracker)
+    tokens = _usage(result.tracker)
     _record(
         ctx,
         settings,
@@ -296,7 +305,7 @@ def cite_cmd(ctx, references, language, style, fmt, output, log_path, no_log):
         inputs=[(references, text)],
         counts=result.counts(),
         style=style,
-        tokens=result.tracker.total_tokens,
+        tokens=tokens,
     )
 
 

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/academic/language.py

@@ -28,7 +28,9 @@ def locale(lang: str) -> dict[str, Any]:
         raise ConfigError(f"language must be one of {', '.join(LANGUAGES)}, not '{lang}'")
     text = (
         resources.files("crewforge.recipes.academic")
-        .joinpath("locales", f"{lang}.yaml")
+        # One segment per call: Traversable.joinpath takes a single child before 3.11.
+        .joinpath("locales")
+        .joinpath(f"{lang}.yaml")
         .read_text(encoding="utf-8")
     )
     return yaml.safe_load(text)

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/api/agents.py

@@ -493,7 +493,9 @@ class ValidateAgent:
             errors.append("Missing paths object")
         elif not paths:
             errors.append("No endpoints defined (paths is empty)")
-        info = spec.get("info") if isinstance(spec.get("info"), dict) else {}
+        info = spec.get("info")
+        if not isinstance(info, dict):
+            info = {}
         if not info.get("title"):
             errors.append("Missing API title")
         if not info.get("version"):

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/docs/agents.py

@@ -178,9 +178,10 @@ class FactCheckAgent(Agent):
                     raise OutputParseError(self.name, "no claims and no overall verdict")
                 overall_verdict = _derive_overall(verdicts)
             else:
-                overall_verdict = _normalize_verdict(overall)
-                if overall_verdict is None:
+                normalized = _normalize_verdict(overall)
+                if normalized is None:
                     raise OutputParseError(self.name, f"unknown overall verdict {overall!r}")
+                overall_verdict = normalized
             issues = [
                 f"{c['verdict'].upper()}: {c.get('claim', '')}".strip()
                 for c in claims
@@ -188,13 +189,14 @@ class FactCheckAgent(Agent):
             ]
         else:
             match = _OVERALL.search(content)
-            overall_verdict = _normalize_verdict(match.group(1)) if match else None
-            if overall_verdict is None:
+            parsed = _normalize_verdict(match.group(1)) if match else None
+            if parsed is None:
                 raise OutputParseError(
                     self.name,
                     "no JSON verdict and no 'OVERALL: <verdict>' line",
                     _excerpt(content),
                 )
+            overall_verdict = parsed
             verdicts, issues = [], []
             for line in content.splitlines():
                 if _OVERALL.search(line):

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/docs/ingest.py

@@ -95,14 +95,14 @@ class IngestAgent:
             import pymupdf
         except ImportError:
             try:
-                import fitz as pymupdf  # older PyMuPDF releases
+                import fitz as pymupdf  # type: ignore[no-redef]  # older PyMuPDF releases
             except ImportError as exc:
                 raise ConfigError(
                     f"reading PDF files needs PyMuPDF: {_DOCS_EXTRA} ({path.name})"
                 ) from exc
         doc = pymupdf.open(str(path))
         try:
-            return "\n\n".join(page.get_text() for page in doc)
+            return "\n\n".join(page.get_text() for page in doc.pages())
         finally:
             doc.close()
 

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/docs/pipeline.py

@@ -9,10 +9,11 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, TypeVar
 
 import httpx
 
+from ...core.agent import Agent
 from ...core.client import LLMClient
 from ...core.config import LLMConfig
 from ...core.crew import Crew
@@ -34,6 +35,8 @@ from .ingest import Document, IngestAgent, TextChunk
 from .retrieve import RetrievalResult, RetrieverAgent
 from .settings import DocsSettings
 
+A = TypeVar("A", bound=Agent)
+
 
 @dataclass
 class PipelineResult:
@@ -62,7 +65,7 @@ class DocsPipeline:
         self._client = client
         self._transport = transport
         self._crew: Crew | None = None
-        self._llm_agents: dict[str, object] = {}
+        self._llm_agents: dict[str, Agent] = {}
         self.tracker = UsageTracker()
 
         self.ingester = IngestAgent(self.settings)
@@ -90,11 +93,12 @@ class DocsPipeline:
             self.retriever.reranker = self._crew.agent(RerankAgent)
         return self._crew
 
-    def _llm_agent(self, cls, **kwargs):
+    def _llm_agent(self, cls: type[A], **kwargs: Any) -> A:
         agent = self._llm_agents.get(cls.name)
-        if agent is None:
-            agent = self._llm_agents[cls.name] = self.crew.agent(cls, **kwargs)
-        return agent
+        if isinstance(agent, cls):
+            return agent
+        created = self._llm_agents[cls.name] = self.crew.agent(cls, **kwargs)
+        return created
 
     @property
     def answerer(self) -> AnswerAgent:
@@ -172,7 +176,9 @@ class DocsPipeline:
             crew.failures.append(failure)
             raise CrewFailedError(crew.name, [failure])
         if rerank:
-            chunks = await crew.step("reranker", self.retriever.reranker.rerank(question, chunks))
+            reranker = self.retriever.reranker
+            assert reranker is not None  # attached by the crew property above
+            chunks = await crew.step("reranker", reranker.rerank(question, chunks))
         return chunks
 
     async def ask(self, question: str, rerank: bool = False) -> Answer:

{crewforge-0.2.0 → crewforge-0.2.1}/src/crewforge/recipes/review/agents.py

@@ -312,7 +312,7 @@ REVIEW_AGENTS: list[str] = [
     "documentation",
 ]
 
-AGENT_REGISTRY: dict[str, type[Agent]] = {
+AGENT_REGISTRY: dict[str, type[ReviewerAgent] | type[SummaryAgent]] = {
     "security": SecurityAgent,
     "style": StyleAgent,
     "complexity": ComplexityAgent,
@@ -323,7 +323,7 @@ AGENT_REGISTRY: dict[str, type[Agent]] = {
 }
 
 
-def get_agent(name: str, **kwargs: Any) -> Agent:
+def get_agent(name: str, **kwargs: Any) -> ReviewerAgent | SummaryAgent:
     """Instantiate a review agent by name (``client=``, ``tracker=`` keyword args)."""
     cls = AGENT_REGISTRY.get(name)
     if cls is None:

{crewforge-0.2.0 → crewforge-0.2.1/src/crewforge.egg-info}/PKG-INFO

@@ -1,17 +1,22 @@
 Metadata-Version: 2.4
 Name: crewforge
-Version: 0.2.0
+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,academic-writing,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,6 +50,8 @@ 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
@@ -51,7 +62,8 @@ Dynamic: license-file
 
 [![CI](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml/badge.svg)](https://github.com/aimanmalib/crewforge/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/crewforge)](https://pypi.org/project/crewforge/)
-![Python 3.10–3.13](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+[![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
@@ -161,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)
@@ -232,6 +249,11 @@ 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: ...
@@ -309,36 +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<br/>academic plan · feedback · cite · disclose"] --> R
-
-    subgraph R["Recipes (src/crewforge/recipes)"]
-        RV[review]
-        DC[docs]
-        AP[api]
-        CT[content]
-        AC[academic]
-    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
@@ -422,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.2.0 → crewforge-0.2.1}/src/crewforge.egg-info/requires.txt

@@ -13,6 +13,8 @@ pytest>=8.0
 pytest-asyncio>=0.23
 pytest-cov>=5.0
 ruff>=0.6
+mypy>=1.10
+types-PyYAML>=6.0
 fastapi>=0.110
 httpx>=0.27