Implement memory/schema.py — XML logbook + gap log schema

[Copilot]

Replaces the TODO placeholder in memory/schema.py with the full single-source-of-truth schema for JALB's XML logbook and gap log. Uses only the Python standard library (xml.etree.ElementTree, datetime); no classes, no third-party imports.

Constants

• Tag names for all logbook and gap log XML elements
• Confidence levels: high, medium, low, flagged
• Source types: research, observation, consolidated
• Gap priorities: high, medium, low

Functions

Function	Returns
create_blank_logbook(subject_name)	<logbook> root with default <subject name="General Subject">
create_blank_gap_log()	Empty <gap_log> root
validate_logbook_xml(root)	list[str] of human-readable errors (empty = valid)
create_item_element(name, content, keywords, confidence, source)	Fully-formed <item> with auto-UTC timestamp
create_gap_entry_element(query, reason, priority)	Fully-formed <gap> with auto-UTC timestamp
iso8601_utc_now()	Current UTC time as 2026-04-03T14:38:50Z

Example

from memory.schema import create_blank_logbook, create_item_element, validate_logbook_xml

logbook = create_blank_logbook()
item = create_item_element("JALB init", "Bot started successfully", ["startup"], "high", "observation")
logbook[0].append(item)

errors = validate_logbook_xml(logbook)  # []

validate_logbook_xml checks root tag, required name attributes on subjects/items, required child elements (<content>, <keywords>, <confidence>, <source>, <timestamp>), valid confidence/source enum values, and disallows unexpected children at every level.

Original prompt

Create a pull request in Pro42good/Jalb to merge the memory/schema.py implementation for JALB's XML logbook + gap log schema.

Context:

• The repository is Pro42good/Jalb.
• Base branch is main.
• memory/schema.py currently exists (was previously a TODO placeholder) and needs to contain the full implementation described below.

Requirements for memory/schema.py:

• Use only Python standard library; specifically xml.etree.ElementTree for XML.
• No third-party imports.
• No classes. Plain constants and functions only.
• Start the file with:
  • # memory/schema.py
  • # Single source of truth for logbook and gap log XML structure.
• Define constants for:
  • Tag names used in the logbook and gap log XML.
  • Confidence levels: high, medium, low, flagged.
  • Source types: research, observation, consolidated.
  • Gap log priority levels: high, medium, low.
• Provide full docstrings on every function.
• Provide simple, readable functions:
  1. create_blank_logbook() returns a <logbook> root (include a default top-level <subject name="General Subject"> child).
  2. create_blank_gap_log() returns a <gap_log> root.
  3. validate_logbook_xml(root) validates an existing logbook ElementTree root and returns a list of human-readable error strings.
  4. create_item_element(name, content, keywords, confidence, source) returns a populated <item> element including auto-generated ISO 8601 UTC timestamp.
  5. create_gap_entry_element(query, reason, priority) returns a populated <gap> element including auto-generated ISO 8601 UTC timestamp.
• Include a small helper iso8601_utc_now() for timestamps.
• Keep comments only where non-obvious.

XML shape to conform to:

• <logbook> contains nested <subject name="..."> elements and <item name="..."> elements.
• <item> contains: <content>, <keywords><keyword>..</keyword></keywords>, <confidence>, <source>, <timestamp>, and optional/empty <related_paths><path>..</path></related_paths>.
• <gap_log> contains <gap> entries: <query>, <reason>, <priority>, <timestamp>.

Deliverable:

• Open a PR against main that includes the complete memory/schema.py implementation.
• Ensure the PR has a clear title and description summarizing the change.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Did you finish?

Assistant: No — the file in your message is truncated at the end (ts_el =). Here is the complete finished memory/schema.py:

# memory/schema.py
# Single source of truth for logbook and gap log XML structure.

"""
JALB (Just a Lil Bot) XML schema helpers for:
- knowledge logbook (<logbook>) and nested subjects/items
- gap log (<gap_log>) with missing-knowledge entries

This module is intentionally minimal:
- Python standard library only
- xml.etree.ElementTree as the sole XML implementation
- constants + plain functions (no classes)
"""

from __future__ import annotations

import datetime as _dt
from typing import List, Optional
import xml.etree.ElementTree as ET


# =========================
# Tag name constants
# =========================

TAG_LOGBOOK = "logbook"
TAG_SUBJECT = "subject"
TAG_ITEM = "item"
TAG_CONTENT = "content"
TAG_KEYWORDS = "keywords"
TAG_KEYWORD = "keyword"
TAG_CONFIDENCE = "confidence"
TAG_SOURCE = "source"
TAG_TIMESTAMP = "timestamp"
TAG_RELATED_PATHS = "related_paths"
TAG_PATH = "path"

TAG_GAP_LOG = "gap_log"
TAG_GAP = "gap"
TAG_QUERY = "query"
TAG_REASON = "reason"
TAG_PRIORITY = "priority"


# =========================
# Attribute name constants
# =========================

ATTR_NAME = "name"


# =========================
# Enumerations (string constants)
# =========================

# Confidence levels
CONFIDENCE_HIGH = "high"
CONFIDENCE_MEDIUM = "medium"
CONFIDENCE_LOW = "low"
CONFIDENCE_FLAGGED = "flagged"
CONFIDENCE_LEVELS = {
    CONFIDENCE_HIGH,
    CONFIDENCE_MEDIUM,
    CONFIDENCE_LOW,
    CONFIDENCE_FLAGGED,
}

# Source types
SOURCE_RESEARCH = "research"
SOURCE_OBSERVATION = "observation"
SOURCE_CONSOLIDATED = "consolidated"
SOURCE_TYPES = {
    SOURCE_RESEARCH,
    SOURCE_OBSERVATION,
    SOURCE_CONSOLIDATED,
}

# Gap log priority levels
PRIORITY_HIGH = "high"
PRIORITY_MEDIUM = "medium"
PRIORITY_LOW = "low"
GAP_PRIORITIES = {
    PRIORITY_HIGH,
    PRIORITY_MEDIUM,
    PRIORITY_LOW,
}


# =========================
# Helpers
# =========================

def iso8601_utc_now() -> str:
    """
    Return the current timestamp in ISO 8601 format (UTC), with a trailing 'Z'.

    Uses second-level precision to keep logs readable and stable across runs.
    """
    # Using UTC and an explicit "Z" avoids locale/timezone ambiguity.
    return _dt.datetime.now(tz=_dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")


def _safe_text(value: Optional[str]) -> str:
    """Return a safe string for XML text nodes (None becomes empty string)."""
    return "" if value is None el...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.