academicflow 0.1.0.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,43 @@
1
+ """academicflow: an academic-writing pipeline for Jupyter notebooks.
2
+
3
+ Quick start in a notebook::
4
+
5
+ %load_ext academicflow
6
+ %acite refs.bib
7
+ %%academic --style=apa --section=introduction
8
+ Transformers changed NLP [@vaswani2017].
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ __version__ = "0.1.0.dev0"
14
+
15
+ from academicflow.cite import Bibliography, check_integrity, find_citations, render
16
+ from academicflow.core import analyze
17
+ from academicflow.style import check, check_document, load_profile
18
+ from academicflow.summarize import generate_abstract, summarize
19
+ from academicflow.types import Issue, TextStats
20
+
21
+ __all__ = [
22
+ "__version__",
23
+ "Issue",
24
+ "TextStats",
25
+ "analyze",
26
+ "check",
27
+ "check_document",
28
+ "load_profile",
29
+ "Bibliography",
30
+ "find_citations",
31
+ "render",
32
+ "check_integrity",
33
+ "summarize",
34
+ "generate_abstract",
35
+ "load_ipython_extension",
36
+ ]
37
+
38
+
39
+ def load_ipython_extension(ipython): # pragma: no cover - thin wrapper
40
+ """Enable ``%load_ext academicflow`` (implemented in academicflow.magics)."""
41
+ from academicflow.magics import load_ipython_extension as _load
42
+
43
+ _load(ipython)
@@ -0,0 +1,14 @@
1
+ """Citation manager: BibTeX parsing, APA/IEEE/Nature formatting, integrity checks.
2
+
3
+ Owner: Member 3.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.cite.bib import Bibliography
9
+ from academicflow.cite.integrity import check_integrity
10
+ from academicflow.cite.render import find_citations, render
11
+
12
+ STYLES = ("apa", "ieee", "nature")
13
+
14
+ __all__ = ["Bibliography", "find_citations", "render", "check_integrity", "STYLES"]
@@ -0,0 +1,64 @@
1
+ """BibTeX loading.
2
+
3
+ Owner: Member 3.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from pathlib import Path
9
+
10
+
11
+ class Bibliography:
12
+ """A collection of BibTeX entries, keyed by citation key."""
13
+
14
+ def __init__(self, entries: dict[str, dict] | None = None) -> None:
15
+ self.entries: dict[str, dict] = entries or {}
16
+
17
+ @classmethod
18
+ def from_string(cls, bibtex: str) -> Bibliography:
19
+ """Parse BibTeX source text.
20
+
21
+ TODO(member 3): normalise authors/fields, LaTeX accents, clear errors.
22
+ """
23
+ from pybtex.database import parse_string
24
+
25
+ data = parse_string(bibtex, "bibtex")
26
+ entries = {}
27
+ for key, entry in data.entries.items():
28
+ fields = {k.lower(): str(v) for k, v in entry.fields.items()}
29
+ authors = [
30
+ (" ".join(p.first_names + p.middle_names), " ".join(p.last_names))
31
+ for p in entry.persons.get("author", [])
32
+ ]
33
+ entries[key] = {"type": entry.type, "authors": authors, **fields}
34
+ return cls(entries)
35
+
36
+ @classmethod
37
+ def from_file(cls, path: str | Path) -> Bibliography:
38
+ """Load a ``.bib`` file."""
39
+ return cls.from_string(Path(path).read_text(encoding="utf-8"))
40
+
41
+ def keys(self) -> list[str]:
42
+ """Return all citation keys in file order."""
43
+ return list(self.entries)
44
+
45
+ def get(self, key: str) -> dict:
46
+ """Return the normalised entry for ``key``."""
47
+ if key not in self.entries:
48
+ raise KeyError(f"Citation key {key!r} not found in bibliography")
49
+ return self.entries[key]
50
+
51
+ def format_reference(self, key: str, style: str) -> str:
52
+ """Format one reference in ``"apa"``, ``"ieee"`` or ``"nature"`` style.
53
+
54
+ TODO(member 3): implement in styles.py.
55
+ """
56
+ from academicflow.cite.styles import format_entry
57
+
58
+ return format_entry(self.get(key), style)
59
+
60
+ def __contains__(self, key: object) -> bool:
61
+ return key in self.entries
62
+
63
+ def __len__(self) -> int:
64
+ return len(self.entries)
@@ -0,0 +1,17 @@
1
+ """Citation integrity checks.
2
+
3
+ Owner: Member 3.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.cite.bib import Bibliography
9
+ from academicflow.types import Issue
10
+
11
+
12
+ def check_integrity(text: str, bib: Bibliography) -> list[Issue]:
13
+ """Check citations against the bibliography.
14
+
15
+ TODO(member 3): cite-missing-key, cite-unused, cite-duplicate-doi, cite-incomplete.
16
+ """
17
+ return []
@@ -0,0 +1,38 @@
1
+ """Inline citation rendering.
2
+
3
+ Owner: Member 3. Citation syntax is pandoc-style: ``[@key]``, ``[@a; @b]``, ``[@key, p. 12]``.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.cite.bib import Bibliography
9
+
10
+
11
+ def find_citations(text: str) -> list[tuple[str, int, int]]:
12
+ """Find every cited key.
13
+
14
+ Returns:
15
+ ``(key, start, end)`` for each key occurrence.
16
+
17
+ TODO(member 3).
18
+ """
19
+ return []
20
+
21
+
22
+ def render(
23
+ text: str, bib: Bibliography, style: str, target: str = "markdown"
24
+ ) -> tuple[str, list[str]]:
25
+ """Replace citations with formatted inline citations.
26
+
27
+ Args:
28
+ text: Text containing ``[@key]`` citations.
29
+ bib: The bibliography.
30
+ style: ``"apa"``, ``"ieee"`` or ``"nature"``.
31
+ target: ``"markdown"``, ``"pandoc"`` or ``"latex"``.
32
+
33
+ Returns:
34
+ ``(rendered_text, ordered_reference_list)``.
35
+
36
+ TODO(member 3).
37
+ """
38
+ return text, []
@@ -0,0 +1,15 @@
1
+ """Reference formatters for APA 7, IEEE and Nature.
2
+
3
+ Owner: Member 3.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+
9
+ def format_entry(entry: dict, style: str) -> str:
10
+ """Format a normalised entry as a markdown reference string.
11
+
12
+ TODO(member 3): real APA / IEEE / Nature formatting per entry type.
13
+ """
14
+ authors = ", ".join(last for _, last in entry.get("authors", []))
15
+ return f"{authors} ({entry.get('year', 'n.d.')}). {entry.get('title', '')}."
@@ -0,0 +1,22 @@
1
+ """Text analysis core: readability, word count, reading time, keywords, passive voice.
2
+
3
+ Owner: Member 1.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.core.keywords import extract_keywords
9
+ from academicflow.core.passive import detect_passive
10
+ from academicflow.core.readability import analyze, count_syllables, readability
11
+ from academicflow.core.text import split_sentences, strip_markdown, tokenize
12
+
13
+ __all__ = [
14
+ "split_sentences",
15
+ "tokenize",
16
+ "strip_markdown",
17
+ "count_syllables",
18
+ "readability",
19
+ "extract_keywords",
20
+ "detect_passive",
21
+ "analyze",
22
+ ]
@@ -0,0 +1,24 @@
1
+ # English stopwords, one per line. TODO(member 1): complete the list.
2
+ a
3
+ an
4
+ and
5
+ are
6
+ as
7
+ at
8
+ be
9
+ by
10
+ for
11
+ from
12
+ in
13
+ is
14
+ it
15
+ of
16
+ on
17
+ or
18
+ that
19
+ the
20
+ this
21
+ to
22
+ was
23
+ were
24
+ with
@@ -0,0 +1,21 @@
1
+ """Keyword extraction.
2
+
3
+ Owner: Member 1.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+
9
+ def extract_keywords(text: str, top_n: int = 10) -> list[tuple[str, float]]:
10
+ """Extract the most important phrases.
11
+
12
+ Args:
13
+ text: Input text.
14
+ top_n: Maximum number of keywords.
15
+
16
+ Returns:
17
+ ``(phrase, score)`` pairs, best first, scores in 0-1.
18
+
19
+ TODO(member 1): RAKE/TF scoring with the bundled stopword list.
20
+ """
21
+ return []
@@ -0,0 +1,19 @@
1
+ """Passive-voice detection.
2
+
3
+ Owner: Member 1.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.types import Issue
9
+
10
+
11
+ def detect_passive(text: str) -> list[Issue]:
12
+ """Find passive-voice constructions.
13
+
14
+ Returns:
15
+ Issues with ``rule="passive-voice"`` and ``severity="info"``.
16
+
17
+ TODO(member 1): be-verb + past participle heuristic, spaCy when installed.
18
+ """
19
+ return []
@@ -0,0 +1,57 @@
1
+ """Readability scores and the combined ``analyze`` function.
2
+
3
+ Owner: Member 1.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import re
9
+
10
+ from academicflow.core.keywords import extract_keywords
11
+ from academicflow.core.passive import detect_passive
12
+ from academicflow.core.text import split_sentences, tokenize
13
+ from academicflow.types import TextStats
14
+
15
+ WORDS_PER_MINUTE = 238
16
+
17
+
18
+ def count_syllables(word: str) -> int:
19
+ """Estimate the number of syllables in a word.
20
+
21
+ TODO(member 1): silent final e, -le endings, exceptions list.
22
+ """
23
+ return max(1, len(re.findall(r"[aeiouy]+", word.lower())))
24
+
25
+
26
+ def readability(text: str) -> dict[str, float]:
27
+ """Compute Flesch Reading Ease and Flesch-Kincaid Grade.
28
+
29
+ TODO(member 1): implement the standard formulas.
30
+ """
31
+ return {"flesch_reading_ease": 0.0, "flesch_kincaid_grade": 0.0}
32
+
33
+
34
+ def analyze(text: str) -> TextStats:
35
+ """Compute all statistics for ``text``.
36
+
37
+ Args:
38
+ text: Input text (markdown allowed).
39
+
40
+ Returns:
41
+ A :class:`~academicflow.types.TextStats`.
42
+ """
43
+ words = tokenize(text)
44
+ sentences = split_sentences(text)
45
+ n_words, n_sents = len(words), len(sentences)
46
+ scores = readability(text)
47
+ passive = detect_passive(text)
48
+ return TextStats(
49
+ word_count=n_words,
50
+ sentence_count=n_sents,
51
+ reading_time_min=round(n_words / WORDS_PER_MINUTE, 2),
52
+ flesch_reading_ease=scores["flesch_reading_ease"],
53
+ flesch_kincaid_grade=scores["flesch_kincaid_grade"],
54
+ avg_sentence_length=round(n_words / n_sents, 2) if n_sents else 0.0,
55
+ keywords=extract_keywords(text),
56
+ passive_ratio=round(len(passive) / n_sents, 3) if n_sents else 0.0,
57
+ )
@@ -0,0 +1,60 @@
1
+ """Low-level text utilities shared by every module.
2
+
3
+ Owner: Member 1. Other members import ``split_sentences`` and ``tokenize``, so keep the
4
+ signatures stable. The versions below are simple placeholders that already work well
5
+ enough for integration.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+
12
+ _WORD_RE = re.compile(r"[A-Za-z0-9]+(?:[-'][A-Za-z0-9]+)*")
13
+ _CITE_RE = re.compile(r"\[@[^\]]*\]")
14
+ _SENT_END_RE = re.compile(r"[.!?]+(?=\s|$)")
15
+
16
+
17
+ def strip_markdown(text: str) -> str:
18
+ """Remove markdown/LaTeX syntax so it is not counted as words.
19
+
20
+ TODO(member 1): strip headings, emphasis, inline code, $...$ math, links.
21
+ """
22
+ return text
23
+
24
+
25
+ def split_sentences(text: str) -> list[tuple[int, int]]:
26
+ """Split text into sentences.
27
+
28
+ Args:
29
+ text: Input text.
30
+
31
+ Returns:
32
+ ``(start, end)`` character offsets of each sentence, whitespace trimmed.
33
+
34
+ TODO(member 1): handle abbreviations (e.g., i.e., et al., Fig.), decimals and
35
+ citations such as ``[@smith2020]``.
36
+ """
37
+ spans: list[tuple[int, int]] = []
38
+
39
+ def _add(s: int, e: int) -> None:
40
+ while s < e and text[s].isspace():
41
+ s += 1
42
+ while e > s and text[e - 1].isspace():
43
+ e -= 1
44
+ if s < e:
45
+ spans.append((s, e))
46
+
47
+ start = 0
48
+ for m in _SENT_END_RE.finditer(text):
49
+ _add(start, m.end())
50
+ start = m.end()
51
+ _add(start, len(text))
52
+ return spans
53
+
54
+
55
+ def tokenize(text: str) -> list[str]:
56
+ """Return lowercase word tokens, ignoring punctuation and ``[@key]`` citations.
57
+
58
+ TODO(member 1): refine (hyphenated words, numbers, markdown).
59
+ """
60
+ return [w.lower() for w in _WORD_RE.findall(_CITE_RE.sub(" ", text))]
@@ -0,0 +1,58 @@
1
+ """Export a paper to DOCX, LaTeX or Markdown.
2
+
3
+ Owner: Member 4.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from pathlib import Path
9
+
10
+
11
+ def _assemble_markdown(session) -> str:
12
+ parts = []
13
+ if session.title:
14
+ parts.append(f"# {session.title}")
15
+ if session.abstract:
16
+ parts.append(f"## Abstract\n\n{session.abstract}")
17
+ for name, text in session.sections.items():
18
+ if name.lower() != "abstract":
19
+ parts.append(f"## {name.replace('-', ' ').title()}\n\n{text}")
20
+ return "\n\n".join(parts) + "\n"
21
+
22
+
23
+ def export_document(session, path: str, fmt: str | None = None) -> str:
24
+ """Export the session's paper.
25
+
26
+ Args:
27
+ session: An :class:`academicflow.magics.Session`.
28
+ path: Output path.
29
+ fmt: ``"docx"``, ``"latex"`` or ``"md"``; inferred from the extension if omitted.
30
+
31
+ Returns:
32
+ The absolute output path.
33
+
34
+ TODO(member 4): citations via cite.render(target="pandoc"), docx and latex output.
35
+ """
36
+ out = Path(path)
37
+ fmt = fmt or {".docx": "docx", ".tex": "latex"}.get(out.suffix.lower(), "md")
38
+ if fmt != "md":
39
+ raise NotImplementedError(f"Export to {fmt} is not implemented yet (member 4)")
40
+ out.write_text(_assemble_markdown(session), encoding="utf-8")
41
+ return str(out.resolve())
42
+
43
+
44
+ def export_notebook(
45
+ nb_path: str,
46
+ out_path: str,
47
+ fmt: str = "docx",
48
+ style: str = "apa",
49
+ bib_path: str | None = None,
50
+ ) -> str:
51
+ """Export a notebook file directly (no running kernel needed).
52
+
53
+ TODO(member 4).
54
+ """
55
+ raise NotImplementedError("export_notebook is not implemented yet (member 4)")
56
+
57
+
58
+ __all__ = ["export_document", "export_notebook"]
@@ -0,0 +1,18 @@
1
+ """Jupyter magics for academicflow.
2
+
3
+ Owner: Member 4.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.magics.session import Session, get_session, reset_session
9
+
10
+
11
+ def load_ipython_extension(ipython) -> None:
12
+ """Register the magics; called by ``%load_ext academicflow``."""
13
+ from academicflow.magics.magics import AcademicMagics
14
+
15
+ ipython.register_magics(AcademicMagics)
16
+
17
+
18
+ __all__ = ["Session", "get_session", "reset_session", "load_ipython_extension"]
@@ -0,0 +1,30 @@
1
+ """HTML helpers for magic output (works in light and dark themes).
2
+
3
+ Owner: Member 4.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import html
9
+
10
+ from academicflow.types import Issue
11
+
12
+ _COLORS = {"info": "#3b82f6", "warning": "#d97706", "error": "#dc2626"}
13
+
14
+
15
+ def issues_html(issues: list[Issue], title: str = "Style issues") -> str:
16
+ """Render issues as a collapsible panel.
17
+
18
+ TODO(member 4): group by section, show counts per severity, nicer styling.
19
+ """
20
+ if not issues:
21
+ return f"<details><summary>{html.escape(title)}: none found</summary></details>"
22
+ rows = "".join(
23
+ f'<li><b style="color:{_COLORS.get(i.severity, "inherit")}">{i.severity}</b> '
24
+ f"[{html.escape(i.rule)}] {html.escape(i.message)}"
25
+ + (f" <i>→ {html.escape(i.suggestion)}</i>" if i.suggestion else "")
26
+ + "</li>"
27
+ for i in issues
28
+ )
29
+ summary = f"{html.escape(title)} ({len(issues)})"
30
+ return f"<details open><summary>{summary}</summary><ul>{rows}</ul></details>"
@@ -0,0 +1,86 @@
1
+ """IPython magics: %acite, %%academic, %astats, %acheck, %aabstract, %aexport.
2
+
3
+ Owner: Member 4.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from IPython.core.magic import Magics, cell_magic, line_magic, magics_class
9
+ from IPython.core.magic_arguments import argument, magic_arguments, parse_argstring
10
+ from IPython.display import HTML, Markdown, display
11
+
12
+ from academicflow import cite, core, style, summarize
13
+ from academicflow.magics.display import issues_html
14
+ from academicflow.magics.session import get_session
15
+
16
+
17
+ @magics_class
18
+ class AcademicMagics(Magics):
19
+ """Magics registered by ``%load_ext academicflow``."""
20
+
21
+ @line_magic
22
+ def acite(self, line: str) -> None:
23
+ """%acite PATH - load a BibTeX file into the session."""
24
+ path = line.strip()
25
+ if not path:
26
+ print("Usage: %acite refs.bib")
27
+ return
28
+ session = get_session()
29
+ session.bib = cite.Bibliography.from_file(path)
30
+ session.bib_path = path
31
+ print(f"Loaded {len(session.bib)} references from {path}")
32
+
33
+ @magic_arguments()
34
+ @argument("--style", default=None, help="apa | ieee | nature (persists)")
35
+ @argument("--section", default=None, help="section name, e.g. introduction")
36
+ @argument("--no-check", action="store_true", help="hide style issues")
37
+ @cell_magic
38
+ def academic(self, line: str, cell: str) -> None:
39
+ """%%academic [--style=apa] [--section=NAME] [--no-check]"""
40
+ args = parse_argstring(self.academic, line)
41
+ session = get_session()
42
+ if args.style:
43
+ session.profile = args.style.lower()
44
+ name = args.section or f"section-{len(session.sections) + 1}"
45
+ session.set_section(name, cell)
46
+
47
+ text, refs = cell, []
48
+ if session.bib is not None:
49
+ text, refs = cite.render(cell, session.bib, session.profile, target="markdown")
50
+ elif cite.find_citations(cell):
51
+ print("Hint: run %acite refs.bib to format citations.")
52
+ md = text + ("\n\n**References**\n\n" + "\n".join(f"- {r}" for r in refs) if refs else "")
53
+ display(Markdown(md))
54
+ if not args.no_check:
55
+ display(HTML(issues_html(style.check(cell, session.profile, section=name))))
56
+
57
+ @line_magic
58
+ def astats(self, line: str) -> None:
59
+ """%astats [SECTION] - text statistics (TODO(member 4): HTML table)."""
60
+ session = get_session()
61
+ text = session.sections.get(line.strip(), "") if line.strip() else session.full_text()
62
+ print(core.analyze(text))
63
+
64
+ @line_magic
65
+ def acheck(self, line: str) -> None:
66
+ """%acheck - check the whole document and its citations."""
67
+ session = get_session()
68
+ issues = style.check_document(session.sections, session.profile)
69
+ if session.bib is not None:
70
+ issues += cite.check_integrity(session.full_text(), session.bib)
71
+ display(HTML(issues_html(issues, title="Document issues")))
72
+
73
+ @line_magic
74
+ def aabstract(self, line: str) -> None:
75
+ """%aabstract - generate an abstract (TODO(member 4): --words, --llm)."""
76
+ session = get_session()
77
+ session.abstract = summarize.generate_abstract(session.sections)
78
+ display(Markdown(f"**Abstract.** {session.abstract}"))
79
+
80
+ @line_magic
81
+ def aexport(self, line: str) -> None:
82
+ """%aexport PATH [--format=docx|latex|md] (TODO(member 4))."""
83
+ from academicflow.export import export_document
84
+
85
+ path = line.split()[0] if line.strip() else "paper.md"
86
+ print(f"Exported to {export_document(get_session(), path)}")
@@ -0,0 +1,49 @@
1
+ """Notebook-wide state shared by all magics. Plain Python, no IPython import.
2
+
3
+ Owner: Member 4.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass, field
9
+
10
+ from academicflow.cite.bib import Bibliography
11
+
12
+
13
+ @dataclass
14
+ class Session:
15
+ """State of the paper being written in the current notebook."""
16
+
17
+ profile: str = "apa"
18
+ bib: Bibliography | None = None
19
+ bib_path: str | None = None
20
+ sections: dict[str, str] = field(default_factory=dict) # insertion-ordered
21
+ title: str = ""
22
+ authors: list[str] = field(default_factory=list)
23
+ abstract: str = ""
24
+
25
+ def set_section(self, name: str, text: str) -> None:
26
+ """Store a section; re-running a cell replaces it and keeps its position."""
27
+ self.sections[name] = text
28
+
29
+ def full_text(self) -> str:
30
+ """All sections joined in order."""
31
+ return "\n\n".join(self.sections.values())
32
+
33
+
34
+ _SESSION: Session | None = None
35
+
36
+
37
+ def get_session() -> Session:
38
+ """Return the singleton session, creating it on first use."""
39
+ global _SESSION
40
+ if _SESSION is None:
41
+ _SESSION = Session()
42
+ return _SESSION
43
+
44
+
45
+ def reset_session() -> Session:
46
+ """Discard all state and return a fresh session."""
47
+ global _SESSION
48
+ _SESSION = Session()
49
+ return _SESSION
@@ -0,0 +1 @@
1
+ """Bundled venue profiles (YAML). Owner: Member 2."""
@@ -0,0 +1,17 @@
1
+ # APA 7 profile. TODO(member 2): complete section_rules.
2
+ name: apa
3
+ citation_style: apa
4
+ allow_first_person: true
5
+ allow_contractions: false
6
+ max_sentence_words: 40
7
+ abstract_max_words: 250
8
+ preferred_spelling: us
9
+ section_rules:
10
+ abstract:
11
+ max_words: 250
12
+ forbid_citations: true
13
+ methods:
14
+ tense: past
15
+ results:
16
+ tense: past
17
+ disabled_rules: []
@@ -0,0 +1,13 @@
1
+ # IEEE profile. TODO(member 2): complete section_rules.
2
+ name: ieee
3
+ citation_style: ieee
4
+ allow_first_person: true
5
+ allow_contractions: false
6
+ max_sentence_words: 35
7
+ abstract_max_words: 250
8
+ preferred_spelling: us
9
+ section_rules:
10
+ abstract:
11
+ max_words: 250
12
+ forbid_citations: true
13
+ disabled_rules: []
@@ -0,0 +1,13 @@
1
+ # Nature profile. TODO(member 2): complete section_rules.
2
+ name: nature
3
+ citation_style: nature
4
+ allow_first_person: true
5
+ allow_contractions: false
6
+ max_sentence_words: 35
7
+ abstract_max_words: 200
8
+ preferred_spelling: uk
9
+ section_rules:
10
+ abstract:
11
+ max_words: 200
12
+ forbid_citations: true
13
+ disabled_rules: []
@@ -0,0 +1,12 @@
1
+ """Style checker: informal language, repetition, terminology consistency, section rules.
2
+
3
+ Owner: Member 2.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.style.profiles import load_profile
9
+ from academicflow.style.rules import check
10
+ from academicflow.style.terminology import check_document
11
+
12
+ __all__ = ["load_profile", "check", "check_document"]
@@ -0,0 +1,5 @@
1
+ # Informal word or phrase -> formal suggestion. TODO(member 2): extend to ~60 entries.
2
+ "a lot of": "many / much"
3
+ "get": "obtain"
4
+ "big": "large"
5
+ "stuff": "material"
@@ -0,0 +1,52 @@
1
+ """Venue profiles (APA / IEEE / Nature presets) stored as YAML.
2
+
3
+ Owner: Member 2.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from importlib import resources
9
+ from pathlib import Path
10
+
11
+ import yaml
12
+
13
+ BUILTIN_PROFILES = ("apa", "ieee", "nature")
14
+
15
+ DEFAULT_PROFILE: dict = {
16
+ "name": "default",
17
+ "citation_style": "apa",
18
+ "allow_first_person": True,
19
+ "allow_contractions": False,
20
+ "max_sentence_words": 40,
21
+ "abstract_max_words": 250,
22
+ "section_rules": {},
23
+ "preferred_spelling": "us",
24
+ "disabled_rules": [],
25
+ }
26
+
27
+
28
+ def load_profile(name_or_path: str) -> dict:
29
+ """Load a built-in profile by name or a custom profile from a YAML path.
30
+
31
+ Args:
32
+ name_or_path: ``"apa"``, ``"ieee"``, ``"nature"`` or a path to a YAML file.
33
+
34
+ Returns:
35
+ The profile dict merged over :data:`DEFAULT_PROFILE`.
36
+
37
+ Raises:
38
+ ValueError: If the name is unknown and no such file exists.
39
+
40
+ TODO(member 2): validate keys, deep-merge section_rules.
41
+ """
42
+ key = name_or_path.lower()
43
+ if key in BUILTIN_PROFILES:
44
+ raw = resources.files("academicflow.profiles").joinpath(f"{key}.yaml").read_text("utf-8")
45
+ elif Path(name_or_path).is_file():
46
+ raw = Path(name_or_path).read_text("utf-8")
47
+ else:
48
+ raise ValueError(
49
+ f"Unknown profile {name_or_path!r}. Use one of {BUILTIN_PROFILES} or a YAML path."
50
+ )
51
+ data = yaml.safe_load(raw) or {}
52
+ return {**DEFAULT_PROFILE, **data}
@@ -0,0 +1,25 @@
1
+ """Single-text style rules.
2
+
3
+ Owner: Member 2.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.types import Issue
9
+
10
+
11
+ def check(text: str, profile: str = "apa", section: str | None = None) -> list[Issue]:
12
+ """Check one piece of text against a venue profile.
13
+
14
+ Args:
15
+ text: Text to check.
16
+ profile: Profile name or YAML path.
17
+ section: Optional section name, enables section-aware rules.
18
+
19
+ Returns:
20
+ Issues sorted by offset.
21
+
22
+ TODO(member 2): informal-word, contraction, first-person, long-sentence,
23
+ repeated-word, repeated-phrase, hedge words, section rules.
24
+ """
25
+ return []
@@ -0,0 +1,29 @@
1
+ """Cross-section rules: terminology consistency and acronyms.
2
+
3
+ Owner: Member 2.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.style.rules import check
9
+ from academicflow.types import Issue
10
+
11
+
12
+ def check_document(sections: dict[str, str], profile: str = "apa") -> list[Issue]:
13
+ """Check a whole document made of named sections.
14
+
15
+ Args:
16
+ sections: Ordered mapping of section name to text.
17
+ profile: Profile name or YAML path.
18
+
19
+ Returns:
20
+ Issues from every section (with ``Issue.section`` set) plus cross-section issues.
21
+
22
+ TODO(member 2): term-inconsistency, acronym-undefined/redefined/unused.
23
+ """
24
+ issues: list[Issue] = []
25
+ for name, text in sections.items():
26
+ for issue in check(text, profile, section=name):
27
+ issue.section = name
28
+ issues.append(issue)
29
+ return issues
@@ -0,0 +1,10 @@
1
+ """Abstract generator: extractive by default, optional LLM backend.
2
+
3
+ Owner: Member 5.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.summarize.extractive import generate_abstract, summarize
9
+
10
+ __all__ = ["summarize", "generate_abstract"]
@@ -0,0 +1,38 @@
1
+ """Extractive summarisation.
2
+
3
+ Owner: Member 5.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from academicflow.core.text import split_sentences, tokenize
9
+
10
+
11
+ def summarize(text: str, max_words: int = 200, method: str = "extractive", **kwargs) -> str:
12
+ """Summarise ``text`` in at most ``max_words`` words.
13
+
14
+ Args:
15
+ text: Input text.
16
+ max_words: Word limit.
17
+ method: ``"extractive"`` or ``"llm"``.
18
+
19
+ TODO(member 5): TextRank, LLM backend with fallback. Placeholder: leading sentences.
20
+ """
21
+ out: list[str] = []
22
+ count = 0
23
+ for start, end in split_sentences(text):
24
+ sentence = text[start:end]
25
+ n = len(tokenize(sentence))
26
+ if count + n > max_words:
27
+ break
28
+ out.append(sentence)
29
+ count += n
30
+ return " ".join(out)
31
+
32
+
33
+ def generate_abstract(
34
+ sections: dict[str, str], max_words: int = 200, method: str = "extractive"
35
+ ) -> str:
36
+ """Generate an abstract from a document's sections (ignoring any ``abstract`` section)."""
37
+ body = "\n\n".join(t for name, t in sections.items() if name.lower() != "abstract")
38
+ return summarize(body, max_words=max_words, method=method)
@@ -0,0 +1,14 @@
1
+ """Optional LLM backend (OpenAI-compatible, also works with Ollama).
2
+
3
+ Owner: Member 5. Requires ``pip install academicflow[llm]``.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+
9
+ def llm_summarize(text: str, max_words: int = 200, **kwargs) -> str:
10
+ """Summarise with an LLM.
11
+
12
+ TODO(member 5): lazy ``openai`` import, env config, fallback to extractive.
13
+ """
14
+ raise NotImplementedError("LLM backend not implemented yet (member 5)")
academicflow/types.py ADDED
@@ -0,0 +1,51 @@
1
+ """Shared data types used by every academicflow module.
2
+
3
+ Owned by Member 5. Change only through a PR that mentions all affected members.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass, field
9
+
10
+ SEVERITIES = ("info", "warning", "error")
11
+
12
+
13
+ @dataclass
14
+ class Issue:
15
+ """A single problem found in a text.
16
+
17
+ Attributes:
18
+ rule: Machine-readable rule id, e.g. ``"informal-word"`` or ``"cite-missing-key"``.
19
+ message: Human-readable explanation.
20
+ severity: ``"info"``, ``"warning"`` or ``"error"``.
21
+ start: Character offset (inclusive) in the text that was checked.
22
+ end: Character offset (exclusive).
23
+ suggestion: Optional replacement or advice.
24
+ section: Section name, filled when checking a multi-section document.
25
+ """
26
+
27
+ rule: str
28
+ message: str
29
+ severity: str = "warning"
30
+ start: int = 0
31
+ end: int = 0
32
+ suggestion: str | None = None
33
+ section: str | None = None
34
+
35
+ def __post_init__(self) -> None:
36
+ if self.severity not in SEVERITIES:
37
+ raise ValueError(f"severity must be one of {SEVERITIES}, got {self.severity!r}")
38
+
39
+
40
+ @dataclass
41
+ class TextStats:
42
+ """Summary statistics for a text, returned by :func:`academicflow.core.analyze`."""
43
+
44
+ word_count: int = 0
45
+ sentence_count: int = 0
46
+ reading_time_min: float = 0.0 # at 238 words per minute
47
+ flesch_reading_ease: float = 0.0
48
+ flesch_kincaid_grade: float = 0.0
49
+ avg_sentence_length: float = 0.0
50
+ keywords: list[tuple[str, float]] = field(default_factory=list)
51
+ passive_ratio: float = 0.0
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.5
2
+ Name: academicflow
3
+ Version: 0.1.0.dev0
4
+ Summary: An academic-writing pipeline for Jupyter: text analysis, style checks, BibTeX citations (APA/IEEE/Nature), abstract generation, and LaTeX/Word export.
5
+ Project-URL: Homepage, https://github.com/zhannurkali/academicflow
6
+ Project-URL: Documentation, https://zhannurkali.github.io/academicflow/
7
+ Project-URL: Source, https://github.com/zhannurkali/academicflow
8
+ Project-URL: Issues, https://github.com/zhannurkali/academicflow/issues
9
+ Author: Member 1, Member 2, Member 3, Member 4, Member 5
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: academic-writing,bibtex,citations,jupyter,latex,nlp,readability
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Framework :: IPython
15
+ Classifier: Framework :: Jupyter
16
+ Classifier: Intended Audience :: Education
17
+ Classifier: Intended Audience :: Science/Research
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Text Processing :: Linguistic
25
+ Classifier: Topic :: Text Processing :: Markup :: LaTeX
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: ipython>=7.0
28
+ Requires-Dist: nbformat>=5.0
29
+ Requires-Dist: numpy>=1.21
30
+ Requires-Dist: pybtex>=0.24
31
+ Requires-Dist: pypandoc-binary>=1.11
32
+ Requires-Dist: python-docx>=0.8.11
33
+ Requires-Dist: pyyaml>=5.4
34
+ Provides-Extra: all
35
+ Requires-Dist: openai>=1.0; extra == 'all'
36
+ Requires-Dist: spacy>=3.5; extra == 'all'
37
+ Provides-Extra: dev
38
+ Requires-Dist: build>=1.0; extra == 'dev'
39
+ Requires-Dist: mkdocs-material>=9; extra == 'dev'
40
+ Requires-Dist: pytest>=7; extra == 'dev'
41
+ Requires-Dist: ruff>=0.4; extra == 'dev'
42
+ Requires-Dist: twine>=4; extra == 'dev'
43
+ Provides-Extra: llm
44
+ Requires-Dist: openai>=1.0; extra == 'llm'
45
+ Provides-Extra: nlp
46
+ Requires-Dist: spacy>=3.5; extra == 'nlp'
47
+ Description-Content-Type: text/markdown
48
+
49
+ # academicflow
50
+
51
+ [![PyPI](https://img.shields.io/pypi/v/academicflow)](https://pypi.org/project/academicflow/)
52
+ [![Python](https://img.shields.io/pypi/pyversions/academicflow)](https://pypi.org/project/academicflow/)
53
+ [![Tests](https://github.com/zhannurkali/academicflow/actions/workflows/test.yml/badge.svg)](https://github.com/zhannurkali/academicflow/actions/workflows/test.yml)
54
+ [![Docs](https://img.shields.io/badge/docs-online-blue)](https://zhannurkali.github.io/academicflow/)
55
+
56
+ An academic-writing pipeline for Jupyter notebooks: text analysis, section-aware style checks,
57
+ terminology consistency, BibTeX citations in APA / IEEE / Nature style, abstract generation,
58
+ and one-command export to Word or LaTeX.
59
+
60
+ > Status: early development (4-day team project). APIs may change before 1.0.
61
+
62
+ ## Install
63
+
64
+ ```bash
65
+ pip install academicflow
66
+ ```
67
+
68
+ ## Quick start
69
+
70
+ ```python
71
+ %load_ext academicflow
72
+ %acite refs.bib
73
+ ```
74
+
75
+ ```python
76
+ %%academic --style=apa --section=introduction
77
+ Transformers changed natural language processing [@vaswani2017].
78
+ ```
79
+
80
+ ```python
81
+ %astats # word count, reading time, readability, keywords, passive voice
82
+ %acheck # style + terminology + citation integrity across all sections
83
+ %aabstract # generate an abstract
84
+ %aexport paper.docx # or paper.tex
85
+ ```
86
+
87
+ ## Documentation
88
+
89
+ https://zhannurkali.github.io/academicflow/
90
+
91
+ ## Development
92
+
93
+ ```bash
94
+ git clone https://github.com/zhannurkali/academicflow.git
95
+ cd academicflow
96
+ python -m venv .venv && source .venv/bin/activate
97
+ pip install -e ".[dev]"
98
+ ruff check . && pytest
99
+ ```
100
+
101
+ Contributors should read [AGENTS.md](AGENTS.md) for the module ownership, API contract and git workflow.
102
+
103
+ ## License
104
+
105
+ MIT
@@ -0,0 +1,34 @@
1
+ academicflow/__init__.py,sha256=qPHO4P-vxm7VvGeCd41jPQmopw4nn06BLJ8_lV6VpRg,1140
2
+ academicflow/types.py,sha256=rKuFfnbtjHYYl5JWaKs3gnseWBMKsNw62mj3CJ76h3M,1579
3
+ academicflow/cite/__init__.py,sha256=e6g-JsYuqs3P5Dkn8Q7LPt8zLHo7cBlGtKv--7PXIa4,426
4
+ academicflow/cite/bib.py,sha256=VP2zsOS3TupYhiFk1nElTbk4qBvb46bZQDtO2p7YVM0,2048
5
+ academicflow/cite/integrity.py,sha256=0GDHQoAbiwXJ4XrovROjlVSShO4dygXSLZBB-5rtHJo,401
6
+ academicflow/cite/render.py,sha256=Ip3ruovd9muBH_cmxGIm6-tKXugXUt2iTN07bzNABW8,914
7
+ academicflow/cite/styles.py,sha256=EPCgE7jcb-bgxlIeOFITT8W66C8517XpQ9iumnCNvgQ,459
8
+ academicflow/core/__init__.py,sha256=APXAtoqI-yzMs0vaDVhnfOQD4VmVn2BnL-hd8hmU7AQ,591
9
+ academicflow/core/keywords.py,sha256=T0mLpQEliSgig0HVR1HNHNaq3_xPHP8MvFviJMKIGhY,450
10
+ academicflow/core/passive.py,sha256=GZhqxcqufA1Fe9YN957AiExbM34GiZePAqIpbFS7ue4,399
11
+ academicflow/core/readability.py,sha256=WXvmJF22DR45erPg_HxQuOuiCKaiiJzb2PVZi1YoJ-A,1695
12
+ academicflow/core/text.py,sha256=gt4pHq61a5aXkjAsh9yKoX1e3Z3jejIrU-5_nXo4czc,1694
13
+ academicflow/core/data/stopwords.txt,sha256=va7n_k8gOLfYdbNY_t2EYjX3aWb14zOP0Al3bQdf1Rg,153
14
+ academicflow/export/__init__.py,sha256=nm1EXBr5qFPCPmjVoN5UzmXDybf4YIBpiqt5NhY5TQ4,1661
15
+ academicflow/magics/__init__.py,sha256=pgf3msmRyiHE0r0gDnKbMVMUv2WBmJT3MEcl-qj1-Jc,472
16
+ academicflow/magics/display.py,sha256=mLSilEe-AV6tabtQvKrKVZm4-1J8kiNp2FTVmKFGiTw,996
17
+ academicflow/magics/magics.py,sha256=Y4qNG0b4I6DLZMW2LJued3XgtYoRsDunh3jf7--KesY,3554
18
+ academicflow/magics/session.py,sha256=OAfgFD3zVEHeB-gSzJGcVYsAumo3FNgqXHOqlpWfAvY,1279
19
+ academicflow/profiles/__init__.py,sha256=kbs8wnnoRwedNSp0QwL7F6oHovmm-muPxRUtw9coGYQ,54
20
+ academicflow/profiles/apa.yaml,sha256=ZhMH3u7CwaKBxebGa1AzN5dGWbu4uI13EB4-WuG7rJI,354
21
+ academicflow/profiles/ieee.yaml,sha256=_9sBC-Z-q4BzeWSCbkIAvzI7G4nR_sX1TO5DuSNUIiM,301
22
+ academicflow/profiles/nature.yaml,sha256=o5gwdCYx4UQnlbVRki-Lo_AxEeQ8LVQyuR96q1n-wko,307
23
+ academicflow/style/__init__.py,sha256=M1UZ7RBDdRyuSM4egAUfb4xGKqIb3btGgjSmTiYbRYQ,357
24
+ academicflow/style/profiles.py,sha256=1Dw-caYuEA8GmIK-SaNGUWqGoWNGRaigS7CPzUTzNpk,1444
25
+ academicflow/style/rules.py,sha256=XHoI6d4WkfuMz7UWhNpJYStAElZmYi6CI1B3xy1j4FE,633
26
+ academicflow/style/terminology.py,sha256=DBEqNv10-VV9VxiPWj-uwPJrASEfDjfjxaeaV2K-bfc,853
27
+ academicflow/style/data/informal.yaml,sha256=pi2Y5Arv5AUeyXnbVeoix0k2Jo1AJ2yxFMN0MZHd1U8,164
28
+ academicflow/summarize/__init__.py,sha256=BAFTto7q2iohMsSEI1NpZK95BKSVBg2Jv-xVBthzBj4,248
29
+ academicflow/summarize/extractive.py,sha256=AHoHUH_M89ouK_VsGnK1EnenpufZZq4Kdog2ynUbq78,1154
30
+ academicflow/summarize/llm.py,sha256=hwxCu6CKu8fpbqRwteT0H8X4SBVDSxcii3UslB3QC8Q,437
31
+ academicflow-0.1.0.dev0.dist-info/METADATA,sha256=VCG4ewS-Le4n-oWj3Hk-jtFw7Akrvlof64vcz7vVRvE,3711
32
+ academicflow-0.1.0.dev0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
33
+ academicflow-0.1.0.dev0.dist-info/licenses/LICENSE,sha256=Dw3at_97C_-sl9L-gz8c647nyWJcdYXrVj5DSosOW34,1064
34
+ academicflow-0.1.0.dev0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zhannur
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.