reflection-analyser 0.1.0__tar.gz

reflection_analyser-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.DS_Store

reflection_analyser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Borck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reflection_analyser-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: reflection-analyser
+Version: 0.1.0
+Summary: Reflective-writing analysis — metacognition, criticality, depth (Moon-style bands)
+Project-URL: Homepage, https://github.com/michael-borck/reflection-analyser
+Project-URL: Repository, https://github.com/michael-borck/reflection-analyser
+Project-URL: Issues, https://github.com/michael-borck/reflection-analyser/issues
+Author-email: Michael Borck <michael.borck@curtin.edu.au>
+License: MIT
+License-File: LICENSE
+Keywords: assessment,education,lens,metacognition,reflection,udl,writing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: lens-contract>=0.2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: rich>=13.7.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: documents
+Requires-Dist: document-analyser>=0.6.0; extra == 'documents'
+Description-Content-Type: text/markdown
+
+# reflection-analyser
+
+**Reflective-writing analysis** — the [lens-family](https://github.com/michael-borck/lens-analysers)
+member that reads a learning journal / reflection / portfolio entry as **reflection**, not just
+as prose.
+
+> `document-analyser` reads readability; this reads *reflective depth*. Different signals from
+> the same words. **Explicit-only** (`auto_routable: false`) — same pattern as
+> `conversation-analyser`: text and prose extensions auto-route to `document-analyser`; invoke
+> `reflection-analyser` deliberately when you want the reflective-depth interpretation.
+
+Built around the markers commonly used in reflective-writing rubrics
+([Moon's depth scale](https://www.tandfonline.com/doi/abs/10.1080/0307507990240207),
+Gibbs' reflective cycle, the SOLO taxonomy): metacognition, criticality, evidence linkage,
+affect language, and forward-looking action.
+
+## Install
+
+```bash
+pip install reflection-analyser
+```
+
+Optional: read `.pdf` / `.docx` / `.pptx` journals (otherwise plain-text / `.md` only):
+
+```bash
+pip install 'reflection-analyser[documents]'
+```
+
+## Use
+
+**Python:**
+
+```python
+from reflection_analyser import ReflectionAnalyser
+
+# From text directly
+result = ReflectionAnalyser().analyse_text("Looking back, I realised that…")
+
+# From a file (composes on document-analyser for binary docs when [documents] is installed)
+result = ReflectionAnalyser().analyse("journal.md")
+result = ReflectionAnalyser().analyse("journal.docx")  # requires [documents]
+
+print(result.depth_band)               # "dialogic"
+print(result.composite_depth_score)    # 0.62
+print(result.metacognition.count)      # 7
+print(result.criticality.count)        # 3
+```
+
+**CLI:**
+
+```bash
+reflection-analyser journal.md
+reflection-analyser journal.txt --json
+reflection-analyser journal.docx                 # needs [documents] extra
+echo "Looking back…" | reflection-analyser -
+reflection-analyser serve
+reflection-analyser manifest
+```
+
+**HTTP** (`reflection-analyser serve` on port 8015):
+
+```bash
+curl -F file=@journal.md http://localhost:8015/analyse
+```
+
+## Signals
+
+For a piece of reflective writing:
+
+- **Metacognition** — first-person + cognitive verbs (`I realised`, `I noticed`, `looking back`,
+  `on reflection`). Surface depth indicator.
+- **Criticality** — contrast/qualification phrases (`however`, `in contrast`, `that said`,
+  `on the other hand`). Marker of dialogic vs descriptive reflection.
+- **Evidence** — references to specific moments, sources, dates, quotes — proper-noun and
+  citation density. Concrete vs abstract.
+- **Affect** — emotion words (`frustrated`, `surprised`, `confident`, `uncertain`). Too few =
+  clinical; presence indicates engagement.
+- **Action / forward-looking** — `next time`, `going forward`, `I will`, future-tense intent.
+  Marker of transformative reflection.
+
+**Composite depth score** (0–1) combines per-marker coverages; mapped to a Moon-style band:
+
+| Band | Score | Description |
+|---|---|---|
+| descriptive | 0.0–0.25 | "What happened" only — events recounted, little interpretation |
+| dialogic | 0.25–0.5 | Some self-questioning + critical thought |
+| critical | 0.5–0.75 | Multiple perspectives, evidence linkage, qualification |
+| transformative | 0.75–1.0 | Forward-looking insight, evidence-linked, change-oriented |
+
+The score is a **signal, not a grade** — it's meant to inform human judgement, not replace it.
+
+## The family
+
+| What you want | Use |
+|---|---|
+| Document text + readability | **document-analyser** |
+| Reflective depth on that text | **reflection-analyser** (this) |
+| Human-AI conversation analysis | **conversation-analyser** |
+| Any file → right engine | **auto-analyser** |
+
+## Limits
+
+- Lexicon-based v1 — fast, transparent, but catches phrasing not meaning. A reflective sentence
+  without our trigger words underscores; a non-reflective sentence with `I realised` overscores.
+- English-only for v1.
+- Calibrated against generic reflective-writing rubrics; tune the band thresholds in
+  `_BAND_THRESHOLDS` for your unit's specific rubric if needed.
+- Vision/LLM-augmented depth scoring is a possible follow-on; not in v1.
+
+## License
+
+MIT

reflection_analyser-0.1.0/README.md

@@ -0,0 +1,112 @@
+# reflection-analyser
+
+**Reflective-writing analysis** — the [lens-family](https://github.com/michael-borck/lens-analysers)
+member that reads a learning journal / reflection / portfolio entry as **reflection**, not just
+as prose.
+
+> `document-analyser` reads readability; this reads *reflective depth*. Different signals from
+> the same words. **Explicit-only** (`auto_routable: false`) — same pattern as
+> `conversation-analyser`: text and prose extensions auto-route to `document-analyser`; invoke
+> `reflection-analyser` deliberately when you want the reflective-depth interpretation.
+
+Built around the markers commonly used in reflective-writing rubrics
+([Moon's depth scale](https://www.tandfonline.com/doi/abs/10.1080/0307507990240207),
+Gibbs' reflective cycle, the SOLO taxonomy): metacognition, criticality, evidence linkage,
+affect language, and forward-looking action.
+
+## Install
+
+```bash
+pip install reflection-analyser
+```
+
+Optional: read `.pdf` / `.docx` / `.pptx` journals (otherwise plain-text / `.md` only):
+
+```bash
+pip install 'reflection-analyser[documents]'
+```
+
+## Use
+
+**Python:**
+
+```python
+from reflection_analyser import ReflectionAnalyser
+
+# From text directly
+result = ReflectionAnalyser().analyse_text("Looking back, I realised that…")
+
+# From a file (composes on document-analyser for binary docs when [documents] is installed)
+result = ReflectionAnalyser().analyse("journal.md")
+result = ReflectionAnalyser().analyse("journal.docx")  # requires [documents]
+
+print(result.depth_band)               # "dialogic"
+print(result.composite_depth_score)    # 0.62
+print(result.metacognition.count)      # 7
+print(result.criticality.count)        # 3
+```
+
+**CLI:**
+
+```bash
+reflection-analyser journal.md
+reflection-analyser journal.txt --json
+reflection-analyser journal.docx                 # needs [documents] extra
+echo "Looking back…" | reflection-analyser -
+reflection-analyser serve
+reflection-analyser manifest
+```
+
+**HTTP** (`reflection-analyser serve` on port 8015):
+
+```bash
+curl -F file=@journal.md http://localhost:8015/analyse
+```
+
+## Signals
+
+For a piece of reflective writing:
+
+- **Metacognition** — first-person + cognitive verbs (`I realised`, `I noticed`, `looking back`,
+  `on reflection`). Surface depth indicator.
+- **Criticality** — contrast/qualification phrases (`however`, `in contrast`, `that said`,
+  `on the other hand`). Marker of dialogic vs descriptive reflection.
+- **Evidence** — references to specific moments, sources, dates, quotes — proper-noun and
+  citation density. Concrete vs abstract.
+- **Affect** — emotion words (`frustrated`, `surprised`, `confident`, `uncertain`). Too few =
+  clinical; presence indicates engagement.
+- **Action / forward-looking** — `next time`, `going forward`, `I will`, future-tense intent.
+  Marker of transformative reflection.
+
+**Composite depth score** (0–1) combines per-marker coverages; mapped to a Moon-style band:
+
+| Band | Score | Description |
+|---|---|---|
+| descriptive | 0.0–0.25 | "What happened" only — events recounted, little interpretation |
+| dialogic | 0.25–0.5 | Some self-questioning + critical thought |
+| critical | 0.5–0.75 | Multiple perspectives, evidence linkage, qualification |
+| transformative | 0.75–1.0 | Forward-looking insight, evidence-linked, change-oriented |
+
+The score is a **signal, not a grade** — it's meant to inform human judgement, not replace it.
+
+## The family
+
+| What you want | Use |
+|---|---|
+| Document text + readability | **document-analyser** |
+| Reflective depth on that text | **reflection-analyser** (this) |
+| Human-AI conversation analysis | **conversation-analyser** |
+| Any file → right engine | **auto-analyser** |
+
+## Limits
+
+- Lexicon-based v1 — fast, transparent, but catches phrasing not meaning. A reflective sentence
+  without our trigger words underscores; a non-reflective sentence with `I realised` overscores.
+- English-only for v1.
+- Calibrated against generic reflective-writing rubrics; tune the band thresholds in
+  `_BAND_THRESHOLDS` for your unit's specific rubric if needed.
+- Vision/LLM-augmented depth scoring is a possible follow-on; not in v1.
+
+## License
+
+MIT

reflection_analyser-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reflection-analyser"
+version = "0.1.0"
+description = "Reflective-writing analysis — metacognition, criticality, depth (Moon-style bands)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Michael Borck", email = "michael.borck@curtin.edu.au" }]
+keywords = ["reflection", "writing", "metacognition", "education", "assessment", "udl", "lens"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "lens-contract>=0.2.0",
+    "fastapi>=0.109.0",
+    "uvicorn[standard]>=0.27.0",
+    "python-multipart>=0.0.9",
+    "rich>=13.7.0",
+]
+
+[project.optional-dependencies]
+# document-analyser brings pdfplumber + markitdown for the binary-document path.
+# Without this extra, reflection-analyser still works on plain-text / markdown.
+documents = [
+    "document-analyser>=0.6.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "httpx>=0.27.0",
+]
+
+[tool.uv.sources]
+lens-contract = { path = "../lens-contract", editable = true }
+
+[project.scripts]
+reflection-analyser = "reflection_analyser.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/michael-borck/reflection-analyser"
+Repository = "https://github.com/michael-borck/reflection-analyser"
+Issues = "https://github.com/michael-borck/reflection-analyser/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reflection_analyser"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

reflection_analyser-0.1.0/src/reflection_analyser/__init__.py

@@ -0,0 +1,14 @@
+"""reflection-analyser — reflective-writing depth analysis for the lens family."""
+from .analyser import ReflectionAnalyser
+from .exceptions import ReflectionAnalyserError
+from .schemas import (
+    MarkerSignal,
+    ReflectionAnalysis,
+)
+
+__all__ = [
+    "ReflectionAnalyser",
+    "ReflectionAnalyserError",
+    "ReflectionAnalysis",
+    "MarkerSignal",
+]

reflection_analyser-0.1.0/src/reflection_analyser/analyser.py

@@ -0,0 +1,123 @@
+"""Core reflection analyser — text → markers → composite depth → Moon-style band."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .exceptions import ReflectionAnalyserError
+from .lexicon import lexicons
+from .schemas import MarkerSignal, ReflectionAnalysis
+
+# Weighting per marker family in the composite depth score. Tuned so that
+# metacognition + criticality + evidence dominate, with affect and forward-
+# looking acting as supporting indicators. Sums to 1.0.
+_WEIGHTS = {
+    "metacognition": 0.30,
+    "criticality":   0.25,
+    "evidence":      0.20,
+    "affect":        0.10,
+    "forward":       0.15,
+}
+
+# A marker reaches its weight-cap when its coverage hits this many hits per
+# 100 words. Avoids a wordy passage with 30 'however's saturating the score.
+_COVERAGE_CAP_PER_100W = 2.0
+
+# Moon-style band thresholds. Tuneable per rubric.
+_BAND_THRESHOLDS = [
+    (0.75, "transformative"),
+    (0.50, "critical"),
+    (0.25, "dialogic"),
+    (0.00, "descriptive"),
+]
+
+_SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+")
+_WORD_SPLIT = re.compile(r"\b\w+\b")
+
+_TEXT_SUFFIXES = {".txt", ".md", ".markdown", ".text", ".rst", ".qmd", ""}
+
+
+class ReflectionAnalyser:
+    """Score the reflective depth of a piece of writing."""
+
+    def analyse_text(self, text: str, *, source_kind: str = "text") -> ReflectionAnalysis:
+        if not text or not text.strip():
+            raise ReflectionAnalyserError("Empty input — nothing to analyse")
+
+        words = _WORD_SPLIT.findall(text)
+        word_count = len(words)
+        sentences = [s for s in _SENTENCE_SPLIT.split(text) if s.strip()]
+
+        lex = lexicons()
+        signals: dict[str, MarkerSignal] = {}
+        for name, compiled in lex.items():
+            count, samples = compiled.find_hits(text, sentences)
+            coverage = (count / word_count * 100) if word_count else 0.0
+            signals[name] = MarkerSignal(
+                count=count,
+                coverage_per_100_words=round(coverage, 4),
+                examples=samples,
+            )
+
+        composite = _compute_depth(signals)
+        band = _band_for(composite)
+
+        return ReflectionAnalysis(
+            word_count=word_count,
+            sentence_count=len(sentences),
+            metacognition=signals["metacognition"],
+            criticality=signals["criticality"],
+            evidence=signals["evidence"],
+            affect=signals["affect"],
+            forward_looking=signals["forward"],
+            composite_depth_score=round(composite, 4),
+            depth_band=band,
+            source_kind=source_kind,
+        )
+
+    def analyse(self, path: str | Path) -> ReflectionAnalysis:
+        """Read a file (text directly, binary via document-analyser if [documents] extra is installed)."""
+        p = Path(path)
+        if not p.exists():
+            raise ReflectionAnalyserError(f"File not found: {p}")
+
+        suffix = p.suffix.lower()
+        if suffix in _TEXT_SUFFIXES:
+            text = p.read_text(encoding="utf-8", errors="replace")
+            return self.analyse_text(text, source_kind=f"file:{suffix.lstrip('.') or 'text'}")
+
+        # Binary path → compose with document-analyser if available.
+        try:
+            from document_analyser.extraction import extract_text
+        except ImportError as e:
+            raise ReflectionAnalyserError(
+                f"Reading {suffix} requires the [documents] extra "
+                f"(pip install 'reflection-analyser[documents]'): {e}"
+            ) from e
+
+        try:
+            text = extract_text(p)
+        except Exception as e:
+            raise ReflectionAnalyserError(f"document-analyser could not extract text from {p}: {e}") from e
+
+        return self.analyse_text(text, source_kind=f"file:{suffix.lstrip('.')}")
+
+
+def _compute_depth(signals: dict[str, MarkerSignal]) -> float:
+    """Weighted composite of capped per-marker coverages, normalised to 0–1."""
+    score = 0.0
+    for name, weight in _WEIGHTS.items():
+        sig = signals.get(name)
+        if sig is None:
+            continue
+        # Normalise coverage to [0, 1] by capping at _COVERAGE_CAP_PER_100W.
+        normalised = min(sig.coverage_per_100_words / _COVERAGE_CAP_PER_100W, 1.0)
+        score += weight * normalised
+    return max(0.0, min(score, 1.0))
+
+
+def _band_for(composite: float) -> str:
+    for threshold, name in _BAND_THRESHOLDS:
+        if composite >= threshold:
+            return name
+    return "descriptive"

reflection_analyser-0.1.0/src/reflection_analyser/api.py

@@ -0,0 +1,64 @@
+"""FastAPI service — reflection-analyser."""
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from lens_contract import add_contract_routes, add_cors, upload_tempfile
+
+from .analyser import ReflectionAnalyser
+from .exceptions import ReflectionAnalyserError
+from .manifest import MANIFEST
+from .schemas import ReflectionAnalysis
+
+_lens = ReflectionAnalyser()
+
+app = FastAPI(
+    title="reflection-analyser",
+    description="Reflective-writing analysis — metacognition, criticality, depth (Moon-style bands)",
+    version=MANIFEST["version"],
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+add_contract_routes(app, MANIFEST)
+add_cors(app, env_prefix="REFLECTION_ANALYSER")
+
+
+@app.get("/")
+async def root() -> dict[str, Any]:
+    return {
+        "service": "reflection-analyser",
+        "version": MANIFEST["version"],
+        "status": "running",
+        "endpoints": {"health": "/health", "manifest": "/manifest", "analyse": "/analyse"},
+    }
+
+
+@app.post("/analyse", response_model=ReflectionAnalysis)
+async def analyse(
+    file: UploadFile | None = File(None, description="Reflection file (.txt/.md or .pdf/.docx with [documents])"),
+    text: str | None = Form(None, description="Raw reflection text — use instead of file upload"),
+) -> ReflectionAnalysis:
+    if file is None and not text:
+        raise HTTPException(status_code=422, detail="Supply either a 'file' upload or a 'text' form field")
+    if file is not None and text:
+        raise HTTPException(status_code=422, detail="Supply only one of 'file' or 'text', not both")
+
+    if text:
+        try:
+            return _lens.analyse_text(text, source_kind="text")
+        except ReflectionAnalyserError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+    # file branch
+    content = await file.read()  # type: ignore[union-attr]
+    if not content:
+        raise HTTPException(status_code=422, detail="Empty file")
+    with upload_tempfile(content, file.filename) as tmp_path:  # type: ignore[union-attr]
+        try:
+            return _lens.analyse(tmp_path)
+        except ReflectionAnalyserError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e))

reflection_analyser-0.1.0/src/reflection_analyser/cli.py

@@ -0,0 +1,88 @@
+"""CLI entry point for reflection-analyser."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    from lens_contract import run_contract_subcommands
+
+    from .manifest import MANIFEST
+
+    if run_contract_subcommands(
+        MANIFEST,
+        app_path="reflection_analyser.api:app",
+        default_port=8015,
+        env_prefix="REFLECTION_ANALYSER",
+    ):
+        return
+
+    parser = argparse.ArgumentParser(
+        prog="reflection-analyser",
+        description="Reflective-writing analysis — metacognition, criticality, depth (Moon-style bands)",
+        epilog="subcommands: `serve` (HTTP API on port 8015), `manifest` (capability manifest)",
+    )
+    parser.add_argument("file", help="File path; or '-' to read text from stdin")
+    parser.add_argument("--json", action="store_true", dest="as_json", help="Output raw JSON")
+    args = parser.parse_args()
+
+    _run(args)
+
+
+def _run(args) -> None:
+    from .analyser import ReflectionAnalyser
+    from .exceptions import ReflectionAnalyserError
+
+    try:
+        if args.file == "-":
+            text = sys.stdin.read()
+            result = ReflectionAnalyser().analyse_text(text, source_kind="stdin")
+        else:
+            result = ReflectionAnalyser().analyse(Path(args.file))
+    except ReflectionAnalyserError as e:
+        if args.as_json:
+            print(json.dumps({"error": str(e)}), file=sys.stderr)
+        else:
+            print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.as_json:
+        print(result.model_dump_json(indent=2))
+        return
+
+    _print_summary(result)
+
+
+def _print_summary(result) -> None:
+    print(f"Words:       {result.word_count:,}  Sentences: {result.sentence_count}")
+    print(f"Depth band:  {result.depth_band}  (composite score: {result.composite_depth_score:.2f})")
+    print()
+    print("Markers (count · per-100-words):")
+    for name, sig in (
+        ("metacognition",   result.metacognition),
+        ("criticality",     result.criticality),
+        ("evidence",        result.evidence),
+        ("affect",          result.affect),
+        ("forward-looking", result.forward_looking),
+    ):
+        print(f"  {name:<16} {sig.count:>3}  ·  {sig.coverage_per_100_words:.2f}/100w")
+    # Show one example sentence for the strongest marker.
+    strongest = max(
+        [("metacognition", result.metacognition), ("criticality", result.criticality),
+         ("evidence", result.evidence), ("affect", result.affect),
+         ("forward-looking", result.forward_looking)],
+        key=lambda kv: kv[1].count,
+    )
+    if strongest[1].examples:
+        print()
+        print(f"Strongest signal: {strongest[0]}")
+        for ex in strongest[1].examples[:2]:
+            short = ex[:160] + ("…" if len(ex) > 160 else "")
+            print(f"  · {short}")
+
+
+if __name__ == "__main__":
+    main()

reflection_analyser-0.1.0/src/reflection_analyser/exceptions.py

@@ -0,0 +1,2 @@
+class ReflectionAnalyserError(Exception):
+    """Domain error from reflection-analyser (empty input, unreadable doc, missing extra)."""

reflection_analyser-0.1.0/src/reflection_analyser/lexicon.py

@@ -0,0 +1,165 @@
+"""Marker lexicons + matcher.
+
+Conservative phrase-level lexicons covering the five marker families. Each
+entry is a regex (compiled lazily on first use) so word-boundary handling
+stays consistent. Keep entries phrase-level: matching `realised` as a bare
+word over-fires (`he realised it was wrong` is a narrative phrase, not
+reflection); `I realised` is the reflective form.
+
+Adjust the lexicons — not the analyser logic — to tune the signal.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Patterns are case-insensitive at compile time. The lexicons below are
+# *fragments*; we wrap them in word boundaries when compiling.
+
+
+_METACOGNITION_PHRASES = [
+    r"I (?:realised|realized|came to (?:see|realise|realize|understand)|recognised|recognized)",
+    r"(?:looking|reflecting) back",
+    r"on reflection",
+    r"I (?:noticed|noted)",
+    r"I (?:learnt|learned) (?:that|how)",
+    r"I (?:think|thought|believe|believed)",
+    r"in hindsight",
+    r"I came to (?:think|believe)",
+    r"I (?:understand|understood) (?:now|that)",
+]
+
+
+_CRITICALITY_PHRASES = [
+    r"however",
+    r"on the other hand",
+    r"in contrast",
+    r"that said",
+    r"although",
+    r"despite",
+    r"nevertheless",
+    r"nonetheless",
+    r"alternatively",
+    r"by contrast",
+    r"this (?:contradicts|conflicts with|challenges)",
+    r"one (?:view|perspective) is .{0,80}? another",
+]
+
+
+# Evidence: explicit reference to a specific source / quote / date / number.
+# Note: we deliberately don't include bare 4-digit years — "I started uni in 2018"
+# is a temporal reference, not evidence. The APA pattern below catches the
+# evidence-shaped use ("(Smith, 2020)").
+_EVIDENCE_PHRASES = [
+    r"according to \w+",
+    r"as (\w+\s){0,3}(?:argues|argued|writes|wrote|notes|notes that|points out)",
+    r"\([A-Z]\w+,? \d{4}\)",                # in-text APA
+    r"\[[0-9]+\]",                          # numeric citation
+    r"\"[^\"]{8,}\"",                       # a quoted span ≥ 8 chars
+    r"\bp\.\s?\d+\b",                       # page reference
+]
+
+
+# Affect: feelings + first-person. Wrapped with "I (was|felt) X" to avoid
+# scoring narratives like "the customer was frustrated".
+_AFFECT_PHRASES = [
+    r"I (?:was|felt|feel|am|have been) (?:frustrated|surprised|confused|uncertain|confident|nervous|anxious|excited|proud|disappointed|overwhelmed|relieved|grateful)",
+    r"I (?:struggled|enjoyed|hated|loved|disliked|appreciated)",
+    r"(?:it|this) was (?:frustrating|surprising|exciting|disappointing|overwhelming|rewarding)",
+    r"a sense of (?:relief|achievement|frustration|confusion|pride)",
+]
+
+
+# Forward-looking action / intent.
+_FORWARD_PHRASES = [
+    r"next time",
+    r"going forward",
+    r"in (?:the )?future",
+    r"I will",
+    r"I plan to",
+    r"I intend to",
+    r"I (?:hope|want) to",
+    r"my next step",
+    r"from now on",
+]
+
+
+@dataclass
+class CompiledLexicon:
+    name: str
+    patterns: list[re.Pattern]
+
+    def find_hits(self, text: str, sentences: list[str], *, sample_cap: int = 5) -> tuple[int, list[str]]:
+        """Count hits across the text; return (count, sample sentences with hits)."""
+        count = 0
+        sample: list[str] = []
+        sample_seen: set[str] = set()
+        for p in self.patterns:
+            for m in p.finditer(text):
+                count += 1
+                # Find the sentence containing this hit (linear scan; sentences are typically <300).
+                pos = m.start()
+                acc = 0
+                hit_sentence = ""
+                for s in sentences:
+                    acc += len(s)
+                    if acc >= pos:
+                        hit_sentence = s.strip()
+                        break
+                if hit_sentence and hit_sentence not in sample_seen and len(sample) < sample_cap:
+                    sample.append(hit_sentence)
+                    sample_seen.add(hit_sentence)
+        return count, sample
+
+
+def _compile(name: str, phrases: list[str]) -> CompiledLexicon:
+    """Compile each phrase, wrapping with word boundaries *only* where the phrase
+    starts/ends with a word character. Patterns that already use punctuation
+    anchors (`(Author, 2020)`, `"quoted span"`, `[42]`) need no boundary —
+    `\\b` next to non-word chars over-restricts (fails the inner-quote case).
+    """
+    compiled: list[re.Pattern] = []
+    for phrase in phrases:
+        prefix = r"\b" if _first_real_char_is_word(phrase) else ""
+        suffix = r"\b" if _last_real_char_is_word(phrase) else ""
+        compiled.append(re.compile(prefix + phrase + suffix, re.IGNORECASE))
+    return CompiledLexicon(name=name, patterns=compiled)
+
+
+_WORD_RE = re.compile(r"\w")
+
+
+def _first_real_char_is_word(phrase: str) -> bool:
+    """Skip leading regex meta-chars to find the first 'real' character."""
+    skip = set(r"(?:\\")
+    for c in phrase:
+        if c in skip:
+            continue
+        return bool(_WORD_RE.match(c))
+    return False
+
+
+def _last_real_char_is_word(phrase: str) -> bool:
+    skip = set(r")?:")
+    for c in reversed(phrase):
+        if c in skip:
+            continue
+        return bool(_WORD_RE.match(c))
+    return False
+
+
+# Lazily-built singletons — compile on first use.
+_LEXICONS: dict[str, CompiledLexicon] | None = None
+
+
+def lexicons() -> dict[str, CompiledLexicon]:
+    global _LEXICONS
+    if _LEXICONS is None:
+        _LEXICONS = {
+            "metacognition": _compile("metacognition", _METACOGNITION_PHRASES),
+            "criticality":   _compile("criticality",   _CRITICALITY_PHRASES),
+            "evidence":      _compile("evidence",      _EVIDENCE_PHRASES),
+            "affect":        _compile("affect",        _AFFECT_PHRASES),
+            "forward":       _compile("forward",       _FORWARD_PHRASES),
+        }
+    return _LEXICONS

reflection_analyser-0.1.0/src/reflection_analyser/manifest.py

@@ -0,0 +1,15 @@
+"""Capability manifest for the lens family (consumed by auto-analyser)."""
+from __future__ import annotations
+
+from lens_contract import make_manifest
+
+# Explicit-only — same pattern as conversation-analyser. Prose extensions already
+# auto-route to document-analyser; reflection is a different interpretation of
+# the same words (depth/metacognition rather than readability).
+MANIFEST = make_manifest(
+    name="reflection-analyser",
+    accepts=["reflection", "journal", "metacognition"],
+    extensions=[],  # explicit-only — invoke deliberately
+    auto_routable=False,
+    produces="ReflectionAnalysis",
+)

reflection_analyser-0.1.0/src/reflection_analyser/schemas.py

@@ -0,0 +1,50 @@
+"""Pydantic schemas for reflection-analyser output."""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class MarkerSignal(BaseModel):
+    """Counts + sample for one reflection-marker family."""
+
+    count: int = 0
+    coverage_per_100_words: float = Field(
+        0.0,
+        description="Hits per 100 words — a length-normalised proxy for marker density.",
+    )
+    examples: list[str] = Field(
+        default_factory=list,
+        description="First few sentences where the marker fired (capped, for transparency).",
+    )
+
+
+class ReflectionAnalysis(BaseModel):
+    """Top-level result returned by ReflectionAnalyser.analyse* methods."""
+
+    word_count: int = 0
+    sentence_count: int = 0
+
+    # Per-marker signals
+    metacognition: MarkerSignal
+    criticality: MarkerSignal
+    evidence: MarkerSignal
+    affect: MarkerSignal
+    forward_looking: MarkerSignal
+
+    # Composite scoring
+    composite_depth_score: float = Field(
+        0.0,
+        description="0–1; weighted blend of per-marker coverages (see analyser._compute_depth).",
+        ge=0.0,
+        le=1.0,
+    )
+    depth_band: str = Field(
+        "descriptive",
+        description="descriptive | dialogic | critical | transformative",
+    )
+
+    # Provenance / source-of-input
+    source_kind: str = Field(
+        "text",
+        description="'text' | 'file:txt' | 'file:md' | 'file:pdf' | 'file:docx' | …",
+    )

reflection_analyser-0.1.0/tests/test_analyser.py

@@ -0,0 +1,130 @@
+"""End-to-end tests for ReflectionAnalyser composite scoring and depth bands."""
+from pathlib import Path
+
+import pytest
+
+from reflection_analyser import (
+    ReflectionAnalyser,
+    ReflectionAnalyserError,
+    ReflectionAnalysis,
+)
+
+
+# ── synthetic samples spanning the four depth bands ──────────────────────
+
+
+DESCRIPTIVE_SAMPLE = (
+    "Today I went to the workshop. The instructor explained the procedure. "
+    "Then we tried the exercise. After that we had lunch. We continued in the afternoon."
+)
+
+DIALOGIC_SAMPLE = (
+    "Today I went to the workshop. I realised that I had been doing it wrong. "
+    "Looking back, the instructor's point about variables made sense. "
+    "However, I'm still not sure about the loop syntax."
+)
+
+CRITICAL_SAMPLE = (
+    "I realised the approach I had been using was flawed. According to Smith (2020), "
+    "this pattern is common. Looking back, I felt frustrated. "
+    "However, on the other hand, the alternative was risky. "
+    "Although the instructor's example seemed simple, in practice it was harder. "
+    "On reflection I understand now why."
+)
+
+TRANSFORMATIVE_SAMPLE = (
+    "I realised that the approach I had been using was flawed. "
+    "According to Smith (2020), the recommended pattern is different. "
+    "Looking back, I felt frustrated by my earlier choice. "
+    "However, in contrast to my initial view, the evidence is clear. "
+    "Although there are trade-offs, on the other hand the long-term benefit is real. "
+    "I will revise my approach. Next time I will plan more carefully. "
+    "Going forward, I plan to apply this lesson to the next assignment."
+)
+
+
+class TestBands:
+    def test_descriptive(self):
+        r = ReflectionAnalyser().analyse_text(DESCRIPTIVE_SAMPLE)
+        assert isinstance(r, ReflectionAnalysis)
+        assert r.depth_band == "descriptive"
+        assert r.composite_depth_score < 0.25
+
+    def test_dialogic(self):
+        r = ReflectionAnalyser().analyse_text(DIALOGIC_SAMPLE)
+        # Has 'I realised', 'looking back', 'however' — should land dialogic or higher.
+        assert r.depth_band in ("dialogic", "critical")
+        assert r.composite_depth_score >= 0.25
+
+    def test_critical_or_better(self):
+        r = ReflectionAnalyser().analyse_text(CRITICAL_SAMPLE)
+        assert r.depth_band in ("critical", "transformative")
+        assert r.composite_depth_score >= 0.40
+
+    def test_transformative(self):
+        r = ReflectionAnalyser().analyse_text(TRANSFORMATIVE_SAMPLE)
+        assert r.depth_band in ("critical", "transformative")
+        assert r.composite_depth_score >= 0.45
+
+
+class TestSignals:
+    def test_metacognition_count_matches(self):
+        r = ReflectionAnalyser().analyse_text(DIALOGIC_SAMPLE)
+        # "I realised" + "Looking back" → 2 metacognition hits.
+        assert r.metacognition.count >= 2
+
+    def test_examples_captured(self):
+        r = ReflectionAnalyser().analyse_text(DIALOGIC_SAMPLE)
+        assert len(r.metacognition.examples) >= 1
+
+    def test_word_count(self):
+        r = ReflectionAnalyser().analyse_text("Hello world.")
+        assert r.word_count == 2
+        assert r.sentence_count == 1
+
+
+class TestErrors:
+    def test_empty_raises(self):
+        with pytest.raises(ReflectionAnalyserError, match="Empty"):
+            ReflectionAnalyser().analyse_text("")
+
+    def test_whitespace_raises(self):
+        with pytest.raises(ReflectionAnalyserError, match="Empty"):
+            ReflectionAnalyser().analyse_text("   \n\n  ")
+
+    def test_missing_file_raises(self, tmp_path: Path):
+        with pytest.raises(ReflectionAnalyserError, match="not found"):
+            ReflectionAnalyser().analyse(tmp_path / "nope.md")
+
+
+class TestFileInputs:
+    def test_md_file(self, tmp_path: Path):
+        p = tmp_path / "journal.md"
+        p.write_text(DIALOGIC_SAMPLE)
+        r = ReflectionAnalyser().analyse(p)
+        assert r.source_kind == "file:md"
+        assert r.metacognition.count >= 2
+
+    def test_txt_file(self, tmp_path: Path):
+        p = tmp_path / "journal.txt"
+        p.write_text(CRITICAL_SAMPLE)
+        r = ReflectionAnalyser().analyse(p)
+        assert r.source_kind == "file:txt"
+
+    def test_binary_without_extra_raises_helpful_error(self, tmp_path: Path):
+        # .pdf path without document-analyser installed should error explicitly.
+        p = tmp_path / "x.pdf"
+        p.write_bytes(b"%PDF-1.4\n%%EOF\n")
+        try:
+            import document_analyser  # noqa: F401
+        except ImportError:
+            with pytest.raises(ReflectionAnalyserError, match="documents.*extra"):
+                ReflectionAnalyser().analyse(p)
+        else:
+            # If document-analyser IS installed (sibling editable), the path
+            # works — that's the documents-extra-is-effective branch. Either
+            # extraction succeeds or it errors with a doc-extraction reason.
+            try:
+                ReflectionAnalyser().analyse(p)
+            except ReflectionAnalyserError:
+                pass  # extraction failure on a bogus PDF is fine for this test

reflection_analyser-0.1.0/tests/test_api.py

@@ -0,0 +1,54 @@
+"""HTTP smoke tests — the family contract surface."""
+from fastapi.testclient import TestClient
+
+from reflection_analyser.api import app
+from reflection_analyser.manifest import MANIFEST
+
+
+client = TestClient(app)
+
+
+def test_health():
+    r = client.get("/health")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["status"] == "ok"
+    assert body["version"] == MANIFEST["version"]
+
+
+def test_manifest():
+    r = client.get("/manifest")
+    assert r.status_code == 200
+    m = r.json()
+    assert m["name"] == "reflection-analyser"
+    assert m["auto_routable"] is False
+    assert m["extensions"] == []
+
+
+def test_analyse_text_form_field():
+    sample = "I realised today, looking back, however that I will plan better next time."
+    r = client.post("/analyse", data={"text": sample})
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["word_count"] > 0
+    assert body["depth_band"] in {"descriptive", "dialogic", "critical", "transformative"}
+
+
+def test_analyse_file_upload():
+    text = "I realised something. Looking back, however, I noticed it. I will change."
+    r = client.post("/analyse", files={"file": ("journal.md", text.encode(), "text/markdown")})
+    assert r.status_code == 200, r.text
+
+
+def test_analyse_no_input_returns_422():
+    r = client.post("/analyse")
+    assert r.status_code == 422
+
+
+def test_analyse_both_inputs_returns_422():
+    r = client.post(
+        "/analyse",
+        data={"text": "x"},
+        files={"file": ("a.md", b"y", "text/markdown")},
+    )
+    assert r.status_code == 422

reflection_analyser-0.1.0/tests/test_cli.py

@@ -0,0 +1,45 @@
+"""CLI smoke tests."""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _run(*args, stdin: str | None = None) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, "-m", "reflection_analyser.cli", *map(str, args)],
+        capture_output=True,
+        text=True,
+        input=stdin,
+    )
+
+
+def test_file(tmp_path: Path):
+    p = tmp_path / "journal.md"
+    p.write_text("I realised today, looking back, however that I will plan better next time.")
+    r = _run(p)
+    assert r.returncode == 0, r.stderr
+    assert "Depth band:" in r.stdout
+    assert "Markers" in r.stdout
+
+
+def test_json(tmp_path: Path):
+    p = tmp_path / "journal.md"
+    p.write_text("I realised something significant.")
+    r = _run(p, "--json")
+    assert r.returncode == 0, r.stderr
+    data = json.loads(r.stdout)
+    assert "depth_band" in data
+
+
+def test_stdin():
+    r = _run("-", stdin="I realised, looking back, that I will change.")
+    assert r.returncode == 0, r.stderr
+    assert "Depth band:" in r.stdout
+
+
+def test_manifest_subcommand():
+    r = _run("manifest")
+    assert r.returncode == 0, r.stderr
+    data = json.loads(r.stdout)
+    assert data["name"] == "reflection-analyser"

reflection_analyser-0.1.0/tests/test_lexicon.py

@@ -0,0 +1,64 @@
+"""Unit tests for the marker lexicons."""
+from reflection_analyser.lexicon import lexicons
+
+
+def _hits(name: str, text: str) -> int:
+    """Pure count for the named marker family in `text`."""
+    sentences = [s for s in text.split(". ") if s]
+    count, _ = lexicons()[name].find_hits(text, sentences)
+    return count
+
+
+class TestMetacognition:
+    def test_first_person_realised(self):
+        assert _hits("metacognition", "I realised that I had been wrong.") == 1
+
+    def test_looking_back(self):
+        assert _hits("metacognition", "Looking back, the choice was clear.") == 1
+
+    def test_he_realised_does_not_fire(self):
+        # "he realised" is narrative, not reflection — must NOT match.
+        assert _hits("metacognition", "He realised it was Tuesday.") == 0
+
+    def test_phrases_with_us_and_uk_spelling(self):
+        # Lexicon includes both `realised` and `realized`.
+        assert _hits("metacognition", "I realized something new.") == 1
+
+
+class TestCriticality:
+    def test_however(self):
+        assert _hits("criticality", "It was hard. However, I learned a lot.") == 1
+
+    def test_on_the_other_hand(self):
+        assert _hits("criticality", "On the other hand, the data was clear.") == 1
+
+    def test_no_false_positive(self):
+        assert _hits("criticality", "Today I went to class.") == 0
+
+
+class TestEvidence:
+    def test_apa_in_text(self):
+        assert _hits("evidence", "As noted (Smith, 2020), the trend is clear.") == 1
+
+    def test_quoted_span(self):
+        assert _hits("evidence", 'The author wrote "this is a quotation".') == 1
+
+    def test_page_reference(self):
+        assert _hits("evidence", "See p. 42 for details.") == 1
+
+
+class TestAffect:
+    def test_i_felt_frustrated(self):
+        assert _hits("affect", "I felt frustrated by the result.") == 1
+
+    def test_third_person_frustrated_does_not_fire(self):
+        # "the customer was frustrated" should NOT count.
+        assert _hits("affect", "The customer was frustrated.") == 0
+
+
+class TestForward:
+    def test_next_time(self):
+        assert _hits("forward", "Next time I will plan more carefully.") >= 1  # 'next time' + 'I will'
+
+    def test_going_forward(self):
+        assert _hits("forward", "Going forward, I'll keep notes.") == 1