meminqu 1.0.0__py3-none-any.whl

meminqu/__init__.py

@@ -0,0 +1,40 @@
+"""meminqu — guided capture interviews for a memory store.
+
+Walks each memory domain, asks questions in deliberately different
+registers (direct, reflective, structural, irreverent, sparse,
+temporal, contrastive), and captures the answers verbatim into the
+domain's raw.md through memdate's pure CAPTURE rules. No
+synthesis, no interpretation, no analysis.
+
+Front-facing conversion of the ``meminqu-memory-interrogation`` skill
+(Ryan's skill-suite, MIT). The domain list is inherited from the
+memdate config — this package declares none of its own.
+"""
+
+from .entry import ENTRY_MARKER, Response, answers_preserved_verbatim, format_entry
+from .registers import (
+    REGISTERS,
+    Register,
+    RegisterError,
+    get_register,
+    plan_cycle,
+    validate_register_set,
+)
+from .session import InterviewSession, SessionError
+
+__all__ = [
+    "InterviewSession",
+    "SessionError",
+    "Response",
+    "Register",
+    "RegisterError",
+    "REGISTERS",
+    "get_register",
+    "plan_cycle",
+    "validate_register_set",
+    "format_entry",
+    "answers_preserved_verbatim",
+    "ENTRY_MARKER",
+]
+
+__version__ = "1.0.0"

meminqu/entry.py

@@ -0,0 +1,63 @@
+"""Entry formatting: the inquiry-capture record.
+
+The contract: answers are preserved verbatim — byte-identical. The
+function adds structure around them (the inquiry marker, the register
+list, question text) but never touches the answer text itself. If an
+answer is empty (skipped question), the skip is recorded as a skip —
+still capture, not silence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .registers import get_register
+
+
+@dataclass(frozen=True)
+class Response:
+    """One question asked, and its answer (possibly skipped)."""
+
+    register: str
+    question: str
+    answer: str | None = None
+
+
+ENTRY_MARKER = "### Inquiry capture"
+
+
+def format_entry(domain: str, responses: list[Response]) -> str:
+    """Build the capture entry body for one domain.
+
+    Raises ValueError on an empty response list or unknown register
+    names. Answers are embedded verbatim — this function performs no
+    normalization, trimming, or interpretation on them.
+    """
+    if not responses:
+        raise ValueError("Cannot format an entry with no responses.")
+    registers_used: list[str] = []
+    for resp in responses:
+        reg = get_register(resp.register)
+        if reg.name not in registers_used:
+            registers_used.append(reg.name)
+
+    lines = [f"{ENTRY_MARKER} — {domain} (registers: {', '.join(registers_used)})", ""]
+    for resp in responses:
+        reg = get_register(resp.register)
+        lines.append(f"**[{reg.label}]** {resp.question.strip()}")
+        if resp.answer is None or not resp.answer.strip():
+            lines.append("_[no answer]_")
+        else:
+            # Verbatim: the answer text is appended exactly as given.
+            lines.append(resp.answer)
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def answers_preserved_verbatim(body: str, responses: list[Response]) -> bool:
+    """Check that every non-empty answer appears byte-identical in the body."""
+    for resp in responses:
+        if resp.answer and resp.answer.strip():
+            if resp.answer not in body:
+                return False
+    return True

meminqu/registers.py

@@ -0,0 +1,177 @@
+"""The seven registers: deliberately different question stances.
+
+This is the actual mechanism of the interview. Each register is a
+distinct way of approaching the same domain — direct, reflective,
+structural, irreverent, sparse, temporal, contrastive — so the answers
+don't all come from the same angle. The registers are data: a caller
+can supply their own set, but the shipped seven are the skill's
+complete, unmodified set.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class RegisterError(ValueError):
+    """Raised for unknown register names or bad register sets."""
+
+
+@dataclass(frozen=True)
+class Register:
+    """One question stance."""
+
+    name: str
+    label: str
+    description: str
+    example_stems: tuple[str, ...]
+
+
+REGISTERS: tuple[Register, ...] = (
+    Register(
+        name="direct",
+        label="Direct / forensic",
+        description=(
+            "No framing, no softening. Ask for the facts as they are, "
+            "the way a deposition would."
+        ),
+        example_stems=(
+            "State the single most important fact in this domain right now, with no qualifiers.",
+            "What happened here that you would swear to under oath?",
+        ),
+    ),
+    Register(
+        name="reflective",
+        label="Reflective / interior",
+        description=(
+            "How it feels from the inside. Subjective material the "
+            "forensic register can't reach."
+        ),
+        example_stems=(
+            "What does this domain feel like from the inside this week?",
+            "What has been sitting in the back of your mind about it?",
+        ),
+    ),
+    Register(
+        name="structural",
+        label="Structural / systems",
+        description=(
+            "The machinery underneath: routines, dependencies, "
+            "load-bearing parts, failure points."
+        ),
+        example_stems=(
+            "What system or routine governs this domain? Which parts are load-bearing?",
+            "If this domain were a machine, which part is under the most strain?",
+        ),
+    ),
+    Register(
+        name="irreverent",
+        label="Irreverent / cutting",
+        description=(
+            "Deliberately disrespectful of the domain's official story. "
+            "Politeness is a filter; this register removes it."
+        ),
+        example_stems=(
+            "Cut the diplomacy: what is actually going on here?",
+            "What is the most embarrassing truth about this domain you would rather not admit?",
+        ),
+    ),
+    Register(
+        name="sparse",
+        label="Sparse / minimal",
+        description=(
+            "Compression as a forcing function. What survives when "
+            "there is almost no room says what matters."
+        ),
+        example_stems=(
+            "This domain in one sentence.",
+            "Three words. No more.",
+        ),
+    ),
+    Register(
+        name="temporal",
+        label="Temporal / what's alive now",
+        description=(
+            "Time-indexed. What is true *now*, what changed, what is "
+            "moving — not the domain's permanent self-image."
+        ),
+        example_stems=(
+            "What is alive in this domain right now, today?",
+            "What changed here since the last time you looked at it?",
+        ),
+    ),
+    Register(
+        name="contrastive",
+        label="Contrastive / what is not true",
+        description=(
+            "Approach by negation. False appearances and near-misses "
+            "define the edges of what is real here."
+        ),
+        example_stems=(
+            "What is *not* true about this domain, though it might look that way?",
+            "What would surprise someone who only saw the surface?",
+        ),
+    ),
+)
+
+_REGISTER_INDEX = {r.name: r for r in REGISTERS}
+
+
+def get_register(name: str) -> Register:
+    """Return the register with this name, or raise RegisterError."""
+    key = name.strip().lower()
+    if key not in _REGISTER_INDEX:
+        raise RegisterError(
+            f"Unknown register {name!r}. Known registers: "
+            f"{', '.join(r.name for r in REGISTERS)}."
+        )
+    return _REGISTER_INDEX[key]
+
+
+def validate_register_set(registers: tuple[Register, ...]) -> tuple[Register, ...]:
+    """Check a caller-supplied register set: unique names, usable stems."""
+    if len(registers) < 2:
+        raise RegisterError("A register set needs at least two registers.")
+    seen: set[str] = set()
+    for r in registers:
+        key = r.name.strip().lower()
+        if not key:
+            raise RegisterError("Register names must not be blank.")
+        if key in seen:
+            raise RegisterError(f"Duplicate register: {r.name!r}.")
+        seen.add(key)
+        if not r.example_stems:
+            raise RegisterError(f"Register {r.name!r} has no example stems.")
+    return registers
+
+
+def plan_cycle(
+    domains: tuple[str, ...] | list[str],
+    per_domain: int = 3,
+    registers: tuple[Register, ...] = REGISTERS,
+) -> dict[str, list[str]]:
+    """Assign registers to each domain for one interview cycle.
+
+    Rotation rule: consecutive domains never share the same register
+    set, and the offset advances each domain so every register gets
+    used across a full cycle. Deterministic — the same inputs always
+    produce the same plan.
+    """
+    registers = validate_register_set(tuple(registers))
+    domains = tuple(domains)
+    if not domains:
+        raise RegisterError("Need at least one domain to plan a cycle.")
+    if per_domain < 1:
+        raise RegisterError("per_domain must be at least 1.")
+    if per_domain > len(registers):
+        raise RegisterError(
+            f"per_domain ({per_domain}) exceeds the register count "
+            f"({len(registers)})."
+        )
+    names = [r.name for r in registers]
+    n = len(names)
+    plan: dict[str, list[str]] = {}
+    for i, domain in enumerate(domains):
+        start = (i * per_domain) % n
+        plan[domain] = [names[(start + j) % n] for j in range(per_domain)]
+    return plan

meminqu/session.py

@@ -0,0 +1,162 @@
+"""The interview session: domain walk, capture calls, completion report.
+
+The session is the record-keeping side of the interview. The actual
+questions and answers happen outside it (an operator or a model runs
+the conversation); this class tracks state — which domain is active,
+which registers were suggested, what got captured, what got skipped —
+formats entries, and makes the capture calls into memdate.
+
+The domain list is inherited from the memdate config. This
+package declares no domains of its own: single source of truth.
+"""
+
+from __future__ import annotations
+
+try:
+    from memdate import (
+        CaptureResult,
+        InterpretationError,
+        MemoryConfig,
+        StorageAdapter,
+        capture,
+    )
+except ImportError as exc:  # pragma: no cover - dependency wiring
+    raise ImportError(
+        "meminqu requires the memdate package "
+        "(the memdate module). Install it first, e.g.: "
+        "pip install -e ../memdate   # from this staging tree"
+    ) from exc
+
+from .entry import Response, format_entry
+from .registers import REGISTERS, Register, plan_cycle
+
+
+class SessionError(ValueError):
+    """Raised for bad session operations (unknown domain, bad order, ...)."""
+
+
+class InterviewSession:
+    """One guided-capture interview cycle over a memory store's domains."""
+
+    SOURCE_TAG = "meminqu"
+
+    def __init__(
+        self,
+        config: MemoryConfig,
+        *,
+        adapter: StorageAdapter | None = None,
+        per_domain: int = 3,
+        registers: tuple[Register, ...] = REGISTERS,
+        domains: tuple[str, ...] | list[str] | None = None,
+    ) -> None:
+        self.config = config
+        self.adapter = adapter
+        # Domains come from the config unless the caller narrows the
+        # cycle to a subset (which must still be config-known domains).
+        chosen = tuple(domains) if domains is not None else config.domains
+        for d in chosen:
+            config.require_domain(d)
+        self.domains: tuple[str, ...] = chosen
+        self.register_plan = plan_cycle(self.domains, per_domain, registers)
+        self._captured: dict[str, CaptureResult] = {}
+        self._skipped: list[str] = []
+        self._started: list[str] = []
+
+    # -- interview flow -------------------------------------------------
+
+    def start_domain(self, domain: str) -> list[str]:
+        """Announce a domain; return its suggested registers."""
+        name = self.config.require_domain(domain)
+        if name not in self.domains:
+            raise SessionError(f"Domain {domain!r} is not in this cycle.")
+        if name not in self._started:
+            self._started.append(name)
+        return list(self.register_plan[name])
+
+    def submit_answers(
+        self,
+        domain: str,
+        responses: list[Response],
+        *,
+        capture_domain: str | None = None,
+    ) -> CaptureResult:
+        """Format the answers and capture them via memdate.
+
+        Captures under the announced domain unless ``capture_domain``
+        is given — the explicit reassignment the skill requires before
+        material may land in a different domain's raw.md.
+
+        Answers are captured under memdate's pure CAPTURE rules:
+        if an answer trips an interpretation marker, capture() raises
+        InterpretationError rather than silently synthesizing. That is
+        enforcement, not a bug — rewrite the answer as raw record, or
+        pass force through the lower-level capture() yourself.
+        """
+        name = self.config.require_domain(domain)
+        target = (
+            self.config.require_domain(capture_domain)
+            if capture_domain is not None
+            else name
+        )
+        body = format_entry(name, responses)
+        result = capture(
+            self.config,
+            target,
+            body,
+            source=self.SOURCE_TAG,
+            adapter=self.adapter,
+        )
+        self._captured[name] = result
+        return result
+
+    def skip_domain(self, domain: str) -> None:
+        """Record a skipped domain. No capture is written."""
+        name = self.config.require_domain(domain)
+        if name not in self.domains:
+            raise SessionError(f"Domain {domain!r} is not in this cycle.")
+        if name not in self._skipped:
+            self._skipped.append(name)
+
+    # -- completion -----------------------------------------------------
+
+    def completion_report(self) -> dict:
+        """Structured report: what was captured, where, what was skipped."""
+        return {
+            "domains_captured": sorted(self._captured),
+            "paths": {d: r.path for d, r in sorted(self._captured.items())},
+            "domains_skipped": list(self._skipped),
+            "domains_untouched": [
+                d for d in self.domains
+                if d not in self._captured and d not in self._skipped
+            ],
+            "next_actions": ["continue", "deepen a domain", "distill", "exit"],
+        }
+
+    def render_report(self) -> str:
+        """Human-readable completion report."""
+        report = self.completion_report()
+        lines = ["Interview complete.", ""]
+        if report["domains_captured"]:
+            lines.append("Captured:")
+            for d in report["domains_captured"]:
+                lines.append(f"  - {d}: {report['paths'][d]}")
+        else:
+            lines.append("Nothing captured.")
+        if report["domains_skipped"]:
+            lines.append("Skipped: " + ", ".join(report["domains_skipped"]))
+        if report["domains_untouched"]:
+            lines.append("Untouched: " + ", ".join(report["domains_untouched"]))
+        lines.append("")
+        lines.append(
+            "Next: " + " / ".join(report["next_actions"]) + "."
+        )
+        return "\n".join(lines) + "\n"
+
+
+__all__ = [
+    "InterviewSession",
+    "SessionError",
+    "InterpretationError",
+    "CaptureResult",
+    "MemoryConfig",
+]

meminqu-1.0.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: meminqu
+Version: 1.0.0
+Summary: Guided capture interviews for a memory store: seven question registers, rotating across domains, answers captured verbatim through memdate's pure CAPTURE rules
+Author: Ryan Wesley Hitchcock
+License: MIT
+Project-URL: Homepage, https://github.com/ohpersonperson/frontface
+Keywords: memory,interview,capture,knowledge-management,journaling
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: memdate
+Dynamic: license-file
+
+# meminqu — guided capture interviews for a memory store
+
+Seven questions, asked seven different ways, written down exactly as
+answered. That is the whole product.
+
+An interview cycle walks each memory domain in order. For each domain,
+the interviewer poses 2–4 questions in deliberately different
+*registers* — direct, reflective, structural, irreverent, sparse,
+temporal, contrastive — receives the answers, and captures them
+**verbatim** into that domain's `raw.md`. No synthesis, no
+interpretation, no analysis. The registers rotate across the cycle so
+no two domains get interrogated from the same angle twice in a row.
+
+No prerequisites. You don't need to know anything about the project's
+history. The mechanism is the whole product.
+
+*(Lineage: front-facing conversion of the `meminqu-memory-interrogation`
+skill from Ryan's skill-suite, MIT. What changed is documented in
+CHANGELOG.md — the decoupling record.)*
+
+## What it does
+
+- **Seven registers** (`registers.py`) — the question stances, kept
+  exactly as the skill defined them, each with a description and
+  example stems. They are data, so a caller can supply their own set;
+  the shipped seven are the complete original set.
+- **Cycle planning** (`plan_cycle`) — assigns registers per domain
+  deterministically: consecutive domains never share a register set,
+  and a full cycle uses every register. No fixed order, no repetition
+  rut.
+- **Verbatim entry format** (`entry.py`) — one `### Inquiry capture —
+  <domain> (registers: …)` record per domain, questions paired with
+  answers, answers embedded byte-identical. Skipped questions are
+  recorded as skips, not silently dropped.
+- **Session runner** (`session.py`) — the record-keeping side of the
+  interview: domain walk, skip, explicit reassignment (material that
+  belongs elsewhere is captured under the announced domain *unless*
+  the operator explicitly reassigns it), and a completion report
+  listing which domains got entries and where they landed.
+
+## Why it works
+
+Most "tell me about your week" systems fail in one of two places: they
+ask every question the same way (so every answer comes from the same
+angle), or they quietly rewrite what you said on the way in (so the
+record is the interviewer's summary, not your words). This package
+fixes both in code:
+
+- **Register rotation** — `plan_cycle` guarantees angular variety. A
+  test asserts consecutive domains differ and a full cycle covers all
+  seven registers.
+- **Verbatim preservation** — `format_entry` adds structure *around*
+  answers but never touches them. The load-bearing test feeds answers
+  with contradictions, typos, and markdown through formatting and
+  asserts byte-identical survival.
+- **Capture purity** — answers go through memdate's `capture()`,
+  which raises `InterpretationError` if the text looks like synthesis
+  ("in summary…") instead of a raw record. The refusal is the feature:
+  it keeps capture and interpretation from mixing in the same motion.
+
+## Installation
+
+`meminqu` is a thin runner over `memdate` — it does
+not reimplement capture, config, or storage. Install the dependency
+first:
+
+```bash
+# from the staging tree
+pip install -e ../memdate
+pip install -e .
+```
+
+or for a quick offline run, put both `src` trees on the path:
+
+```bash
+PYTHONPATH=../memdate/src:src python3 -m unittest discover -s tests
+PYTHONPATH=../memdate/src:src python3 examples/demo_interview.py
+```
+
+`pyproject.toml` declares `memdate` as a dependency honestly —
+this package cannot function without it.
+
+## Quickstart
+
+```python
+from meminqu import InterviewSession, Response
+from memdate import MemoryConfig
+
+config = MemoryConfig(root="./my-memory")  # domains from config, not from here
+session = InterviewSession(config)
+
+for domain in session.domains:
+    registers = session.start_domain(domain)   # announce; get suggested registers
+    # ... the operator/model asks questions, collects answers ...
+    session.submit_answers(domain, [
+        Response("direct", "What is the key fact?", "The server migration finished Tuesday."),
+        Response("sparse", "This domain in one sentence.", "Quiet, for once."),
+    ])
+    # session.skip_domain(domain)              # or skip it — nothing is written
+
+print(session.render_report())
+```
+
+## Where the formats meet
+
+The original skill specified captures under a `## YYYY-MM-DD`
+day-heading. The converted memdate writes a `## YYYY-MM-DD
+HH:MM TZ` heading per entry instead. This package defers to the
+library's heading — one source of truth for the capture format — and
+the `### Inquiry capture — <domain> (registers: …)` marker rides
+inside the entry body, where the register list stays attached to the
+answers it describes.
+
+## Evidence taxonomy
+
+This package tags no evidence itself; its artifacts are `raw.md`
+entries. memdate's README maps those onto the shared ten-tier
+taxonomy (`raw.md` entries sit at OBSERVATION / CLAIM). No third
+taxonomy was invented.
+
+## Worked example
+
+- `examples/example-1-full-cycle.md` — one full annotated cycle on
+  neutral domains, register rotation shown.
+- `examples/demo_interview.py` — scripted end-to-end run against a
+  temp store; no model, no network.

meminqu-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+meminqu/__init__.py,sha256=Ti6ND01wzcKXhUlPOBLOKOentScKLbBi-rDT_-hzcYQ,1123
+meminqu/entry.py,sha256=Td_OHMJqnv6MhV5D7Z_ZW74K4QEB8jE7JRPkchzKZKI,2127
+meminqu/registers.py,sha256=gVC7xavcHz7cK7zU8asPqrEoMESgQjWwhOn9Yum6b6A,6046
+meminqu/session.py,sha256=mvuJyB1712q4lP7vd0gEDLgnFYoAOHy7x2qSuxJPpG4,5894
+meminqu-1.0.0.dist-info/licenses/LICENSE,sha256=Zx_XafyZDq7qBexUb7tER9kYlBZ0rCVaAwKuqMCfxLE,1078
+meminqu-1.0.0.dist-info/METADATA,sha256=zRHnJKoI_M7eSGIlG6khNc9Z3TqXsB4OPzP_ctZdMdM,5882
+meminqu-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+meminqu-1.0.0.dist-info/top_level.txt,sha256=neG-q5IDmgCRjizwVApWa3wY669pJO_Hz-MColjVyZ4,8
+meminqu-1.0.0.dist-info/RECORD,,

meminqu-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

meminqu-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Wesley Hitchcock
+
+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.

meminqu-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+meminqu