intenttext 1.0.0__py3-none-any.whl

intenttext/__init__.py

@@ -0,0 +1,39 @@
+from .merge import merge_data, parse_and_merge
+from .parser import parse, parse_safe
+from .query import query
+from .renderer import render_html, render_markdown, render_print
+from .source import to_source
+from .types import (
+    InlineSegment,
+    IntentBlock,
+    IntentDocument,
+    IntentMetadata,
+    ParseResult,
+    ParseWarning,
+    ValidationIssue,
+    ValidationResult,
+)
+from .validate import validate
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "parse",
+    "parse_safe",
+    "render_html",
+    "render_print",
+    "render_markdown",
+    "merge_data",
+    "parse_and_merge",
+    "validate",
+    "query",
+    "to_source",
+    "IntentDocument",
+    "IntentBlock",
+    "IntentMetadata",
+    "InlineSegment",
+    "ParseResult",
+    "ParseWarning",
+    "ValidationResult",
+    "ValidationIssue",
+]

intenttext/merge.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import re
+from copy import deepcopy
+from datetime import datetime
+from typing import Any
+
+from .parser import parse
+from .types import IntentDocument
+
+
+def merge_data(template: IntentDocument, data: dict[str, Any]) -> IntentDocument:
+    doc = deepcopy(template)
+    now = datetime.now()
+    system_vars = {
+        "timestamp": now.isoformat(),
+        "date": now.strftime("%d %B %Y"),
+        "year": str(now.year),
+    }
+    merged_data = {**system_vars, **data}
+
+    for block in doc.blocks:
+        block.content = _resolve_string(block.content, merged_data)
+        block.original_content = _resolve_string(block.original_content, merged_data)
+        block.properties = {
+            k: _resolve_string(v, merged_data) if isinstance(v, str) else v
+            for k, v in block.properties.items()
+        }
+
+    _refresh_metadata(doc)
+
+    return doc
+
+
+def parse_and_merge(template_source: str, data: dict[str, Any]) -> IntentDocument:
+    template = parse(template_source)
+    return merge_data(template, data)
+
+
+def _resolve_string(text: str, data: dict[str, Any]) -> str:
+    def replacer(match: re.Match[str]) -> str:
+        path = match.group(1).strip()
+        if path in ("page", "pages"):
+            return match.group(0)
+        value = _get_by_path(data, path)
+        return str(value) if value is not None else match.group(0)
+
+    return re.sub(r"\{\{([^}]+)\}\}", replacer, text)
+
+
+def _get_by_path(obj: Any, path: str) -> Any:
+    parts = path.split(".")
+    current = obj
+
+    for part in parts:
+        if current is None:
+            return None
+
+        if isinstance(current, list):
+            try:
+                current = current[int(part)]
+            except (ValueError, IndexError):
+                return None
+        elif isinstance(current, dict):
+            current = current.get(part)
+        else:
+            return None
+
+    return current
+
+
+def _refresh_metadata(doc: IntentDocument) -> None:
+    for block in doc.blocks:
+        if block.type == "title":
+            doc.metadata.title = block.content
+        elif block.type == "summary":
+            doc.metadata.summary = block.content
+        elif block.type == "agent":
+            doc.metadata.agent = block.content
+            if "model" in block.properties:
+                doc.metadata.model = str(block.properties["model"])
+        elif block.type == "context":
+            doc.metadata.context.update(
+                {k: str(v) for k, v in block.properties.items()}
+            )

intenttext/parser.py

@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from .types import (
+    InlineSegment,
+    IntentBlock,
+    IntentDocument,
+    IntentMetadata,
+    ParseResult,
+    ParseWarning,
+)
+
+DOCUMENT_HEADER_KEYWORDS = {
+    "agent",
+    "context",
+    "font",
+    "page",
+}
+
+STRUCTURE_KEYWORDS = {
+    "title",
+    "summary",
+    "section",
+    "sub",
+    "note",
+    "toc",
+    "break",
+}
+
+CONTENT_KEYWORDS = {
+    "task",
+    "done",
+    "ask",
+    "quote",
+    "info",
+    "warning",
+    "tip",
+    "success",
+    "link",
+    "image",
+    "code",
+    "ref",
+}
+
+WRITER_KEYWORDS = {
+    "byline",
+    "epigraph",
+    "caption",
+    "footnote",
+    "dedication",
+}
+
+AGENTIC_KEYWORDS = {
+    "step",
+    "decision",
+    "parallel",
+    "loop",
+    "call",
+    "gate",
+    "wait",
+    "retry",
+    "error",
+    "trigger",
+    "checkpoint",
+    "handoff",
+    "audit",
+    "emit",
+    "result",
+    "progress",
+    "import",
+    "export",
+}
+
+ALL_KEYWORDS = (
+    DOCUMENT_HEADER_KEYWORDS
+    | STRUCTURE_KEYWORDS
+    | CONTENT_KEYWORDS
+    | WRITER_KEYWORDS
+    | AGENTIC_KEYWORDS
+)
+
+_ID_COUNTER = 0
+
+
+def parse(source: str) -> IntentDocument:
+    result = parse_safe(source)
+    if result.errors:
+        raise ValueError(f"Parse errors: {result.errors[0].message}")
+    return result.document
+
+
+def parse_safe(
+    source: str,
+    unknown_keyword: str = "note",
+    max_blocks: int = 10000,
+    max_line_length: int = 50000,
+) -> ParseResult:
+    warnings: list[ParseWarning] = []
+    errors: list[ParseWarning] = []
+    blocks: list[IntentBlock] = []
+    metadata = IntentMetadata()
+    in_code_fence = False
+    fence_lines: list[str] = []
+
+    lines = source.splitlines()
+
+    for line_num, raw_line in enumerate(lines, 1):
+        original = raw_line
+        if len(raw_line) > max_line_length:
+            raw_line = raw_line[:max_line_length]
+            warnings.append(
+                ParseWarning(
+                    line=line_num,
+                    message=f"Line truncated at {max_line_length} characters",
+                    code="LINE_TRUNCATED",
+                    original=original[:100] + "...",
+                )
+            )
+
+        line = raw_line.strip()
+
+        if line.startswith("```"):
+            if in_code_fence:
+                blocks.append(
+                    IntentBlock(
+                        id=_generate_id(),
+                        type="code",
+                        content="\n".join(fence_lines),
+                        original_content="\n".join(fence_lines),
+                    )
+                )
+                in_code_fence = False
+                fence_lines = []
+            else:
+                in_code_fence = True
+            continue
+
+        if in_code_fence:
+            fence_lines.append(raw_line)
+            continue
+
+        if not line:
+            continue
+
+        if line.startswith("//"):
+            continue
+
+        if line == "---":
+            blocks.append(
+                IntentBlock(
+                    id=_generate_id(),
+                    type="divider",
+                    content="",
+                    original_content="---",
+                )
+            )
+            continue
+
+        if line.startswith("|") and line.endswith("|"):
+            cells = [c.strip() for c in line[1:-1].split("|")]
+            if all(re.match(r"^[-:]+$", c.strip()) for c in cells if c.strip()):
+                continue
+            if blocks and blocks[-1].type == "table":
+                rows = blocks[-1].properties.get("rows", [])
+                rows.append(cells)
+                blocks[-1].properties["rows"] = rows
+            else:
+                blocks.append(
+                    IntentBlock(
+                        id=_generate_id(),
+                        type="table",
+                        content="",
+                        original_content=line,
+                        properties={"rows": [cells]},
+                    )
+                )
+            continue
+
+        if len(blocks) >= max_blocks:
+            warnings.append(
+                ParseWarning(
+                    line=line_num,
+                    message=f"Max blocks ({max_blocks}) reached, stopping parse",
+                    code="MAX_BLOCKS_REACHED",
+                    original=line,
+                )
+            )
+            break
+
+        block = _parse_keyword_line(
+            line=line,
+            line_num=line_num,
+            unknown_keyword=unknown_keyword,
+            warnings=warnings,
+            errors=errors,
+        )
+        if block is not None:
+            blocks.append(block)
+            _update_metadata(metadata, block)
+
+    if in_code_fence:
+        warnings.append(
+            ParseWarning(
+                line=len(lines),
+                message="Unclosed code fence, auto-closed at end of file",
+                code="UNCLOSED_CODE_FENCE",
+                original="```",
+            )
+        )
+        blocks.append(
+            IntentBlock(
+                id=_generate_id(),
+                type="code",
+                content="\n".join(fence_lines),
+                original_content="\n".join(fence_lines),
+            )
+        )
+
+    document = IntentDocument(version="2.0", blocks=blocks, metadata=metadata)
+    return ParseResult(document=document, warnings=warnings, errors=errors)
+
+
+def _parse_keyword_line(
+    line: str,
+    line_num: int,
+    unknown_keyword: str,
+    warnings: list[ParseWarning],
+    errors: list[ParseWarning],
+) -> Optional[IntentBlock]:
+    match = re.match(r"^(\w+):\s*(.*)$", line)
+    if not match:
+        return None
+
+    keyword = match.group(1).lower()
+    rest = match.group(2)
+
+    if keyword not in ALL_KEYWORDS:
+        if unknown_keyword == "skip":
+            warnings.append(
+                ParseWarning(
+                    line=line_num,
+                    message=f"Unknown keyword '{keyword}' skipped",
+                    code="UNKNOWN_KEYWORD",
+                    original=line,
+                )
+            )
+            return None
+        if unknown_keyword == "throw":
+            errors.append(
+                ParseWarning(
+                    line=line_num,
+                    message=f"Unknown keyword '{keyword}'",
+                    code="UNKNOWN_KEYWORD",
+                    original=line,
+                )
+            )
+            return None
+
+        warnings.append(
+            ParseWarning(
+                line=line_num,
+                message=f"Unknown keyword '{keyword}' treated as note",
+                code="UNKNOWN_KEYWORD",
+                original=line,
+            )
+        )
+        keyword = "note"
+
+    content, properties = _parse_content_and_properties(rest)
+
+    if keyword == "done":
+        keyword = "task"
+        properties["status"] = "done"
+
+    block_id = str(properties.pop("id", _generate_id()))
+
+    return IntentBlock(
+        id=block_id,
+        type=keyword,
+        content=_strip_inline(content),
+        original_content=content,
+        inline=_parse_inline(content),
+        properties=properties,
+    )
+
+
+def _parse_content_and_properties(rest: str) -> tuple[str, dict[str, Any]]:
+    parts = [p.strip() for p in rest.split("|")]
+    content = parts[0].strip() if parts else ""
+    properties: dict[str, Any] = {}
+
+    for part in parts[1:]:
+        kv_match = re.match(r"^(\w[\w-]*):\s*(.*)$", part.strip())
+        if not kv_match:
+            continue
+        key = kv_match.group(1)
+        value: Any = kv_match.group(2).strip()
+
+        if value.lower() in ("true", "false"):
+            value = value.lower() == "true"
+        elif key in ("max", "delay", "leading", "depth", "columns"):
+            try:
+                value = int(value) if "." not in value else float(value)
+            except ValueError:
+                pass
+
+        properties[key] = value
+
+    return content, properties
+
+
+def _parse_inline(text: str) -> list[InlineSegment]:
+    segments: list[InlineSegment] = []
+    pattern = re.compile(
+        r"\*([^*]+)\*"
+        r"|_([^_]+)_"
+        r"|~([^~]+)~"
+        r"|\^([^^]+)\^"
+        r"|`([^`]+)`"
+        r"|\[([^\]]+)\]\(([^)]+)\)"
+        r"|\[\^(\d+)\]"
+        r"|@(\w+)"
+        r"|#(\w+)"
+    )
+
+    last_end = 0
+    for match in pattern.finditer(text):
+        if match.start() > last_end:
+            segments.append(InlineSegment(type="text", value=text[last_end : match.start()]))
+
+        if match.group(1):
+            segments.append(InlineSegment(type="bold", value=match.group(1)))
+        elif match.group(2):
+            segments.append(InlineSegment(type="italic", value=match.group(2)))
+        elif match.group(3):
+            segments.append(InlineSegment(type="strikethrough", value=match.group(3)))
+        elif match.group(4):
+            segments.append(InlineSegment(type="highlight", value=match.group(4)))
+        elif match.group(5):
+            segments.append(InlineSegment(type="code", value=match.group(5)))
+        elif match.group(6):
+            segments.append(
+                InlineSegment(type="link", value=match.group(6), href=match.group(7))
+            )
+        elif match.group(8):
+            segments.append(InlineSegment(type="footnote-ref", value=match.group(8)))
+        elif match.group(9):
+            segments.append(InlineSegment(type="mention", value=match.group(9)))
+        elif match.group(10):
+            segments.append(InlineSegment(type="tag", value=match.group(10)))
+
+        last_end = match.end()
+
+    if last_end < len(text):
+        segments.append(InlineSegment(type="text", value=text[last_end:]))
+
+    return segments
+
+
+def _strip_inline(text: str) -> str:
+    text = re.sub(r"\*([^*]+)\*", r"\1", text)
+    text = re.sub(r"_([^_]+)_", r"\1", text)
+    text = re.sub(r"~([^~]+)~", r"\1", text)
+    text = re.sub(r"\^([^^]+)\^", r"\1", text)
+    text = re.sub(r"`([^`]+)`", r"\1", text)
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+    text = re.sub(r"\[\^(\d+)\]", r"[\1]", text)
+    return text
+
+
+def _generate_id() -> str:
+    global _ID_COUNTER
+    _ID_COUNTER += 1
+    return f"b{_ID_COUNTER:04d}"
+
+
+def _update_metadata(metadata: IntentMetadata, block: IntentBlock) -> None:
+    if block.type == "title":
+        metadata.title = block.content
+    elif block.type == "summary":
+        metadata.summary = block.content
+    elif block.type == "agent":
+        metadata.agent = block.content
+        if "model" in block.properties:
+            metadata.model = str(block.properties["model"])
+    elif block.type == "context":
+        metadata.context.update({k: str(v) for k, v in block.properties.items()})

intenttext/query.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .types import IntentBlock, IntentDocument
+
+
+def query(
+    doc: IntentDocument,
+    type: Optional[str | list[str]] = None,
+    section: Optional[str] = None,
+    properties: Optional[dict[str, Any]] = None,
+    text: Optional[str] = None,
+    limit: Optional[int] = None,
+) -> list[IntentBlock]:
+    results: list[IntentBlock] = []
+    current_section = ""
+
+    for block in doc.blocks:
+        if block.type == "section":
+            current_section = block.content
+
+        if type is not None:
+            if isinstance(type, str) and block.type != type:
+                continue
+            if isinstance(type, list) and block.type not in type:
+                continue
+
+        if section is not None and current_section != section:
+            continue
+
+        if text is not None and text.lower() not in block.content.lower():
+            continue
+
+        if properties:
+            matches = True
+            for key, expected in properties.items():
+                actual = block.properties.get(key)
+                if callable(getattr(expected, "search", None)):
+                    if actual is None or expected.search(str(actual)) is None:
+                        matches = False
+                        break
+                else:
+                    if str(actual) != str(expected):
+                        matches = False
+                        break
+            if not matches:
+                continue
+
+        results.append(block)
+
+        if limit is not None and len(results) >= limit:
+            break
+
+    return results

intenttext/renderer.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import html
+
+from .types import IntentBlock, IntentDocument
+
+
+BASE_CSS = """
+.it-document { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; line-height: 1.6; color: #222; }
+.it-block { margin: 0.6rem 0; }
+.it-section { margin-top: 1.4rem; }
+.it-sub { margin-top: 1rem; }
+.it-callout { padding: 0.75rem 1rem; border-radius: 6px; border-left: 4px solid; }
+.it-callout.info { background: #eef6ff; border-color: #1d70b8; }
+.it-callout.warning { background: #fff7e6; border-color: #b26a00; }
+.it-callout.tip { background: #eefbf2; border-color: #1f7a3d; }
+.it-callout.success { background: #eefbf2; border-color: #1f7a3d; }
+.it-task { display: flex; gap: 0.5rem; }
+.it-task.done { color: #666; text-decoration: line-through; }
+.it-table { width: 100%; border-collapse: collapse; }
+.it-table th, .it-table td { border: 1px solid #ddd; padding: 0.5rem; text-align: left; }
+.it-table th { background: #f5f5f5; }
+.it-divider { border: 0; border-top: 1px solid #ddd; margin: 1rem 0; }
+""".strip()
+
+
+def render_html(doc: IntentDocument, include_css: bool = True) -> str:
+    parts: list[str] = []
+    if include_css:
+        parts.append(f"<style>{BASE_CSS}</style>")
+
+    parts.append('<div class="it-document">')
+    for block in doc.blocks:
+        parts.append(_render_block_html(block))
+    parts.append("</div>")
+
+    return "\n".join(p for p in parts if p)
+
+
+def render_print(doc: IntentDocument) -> str:
+    css = (
+        BASE_CSS
+        + "\n@media print { .it-document { font-family: Georgia, serif; } .it-block { break-inside: avoid; } }"
+    )
+    body = render_html(doc, include_css=False)
+    return (
+        "<!doctype html><html><head><meta charset=\"utf-8\"/>"
+        f"<style>{css}</style></head><body>{body}</body></html>"
+    )
+
+
+def render_markdown(doc: IntentDocument) -> str:
+    lines: list[str] = []
+
+    for block in doc.blocks:
+        t = block.type
+        content = block.original_content or block.content
+
+        if t == "title":
+            lines.append(f"# {content}")
+        elif t == "section":
+            lines.append(f"## {content}")
+        elif t == "sub":
+            lines.append(f"### {content}")
+        elif t == "note":
+            lines.append(content)
+        elif t == "task":
+            checked = str(block.properties.get("status", "")).lower() == "done"
+            lines.append(f"- [{'x' if checked else ' '}] {content}")
+        elif t == "quote":
+            author = block.properties.get("by")
+            lines.append(f"> {content}")
+            if author:
+                lines.append(f"> - {author}")
+        elif t in {"info", "warning", "tip"}:
+            lines.append(f"> **{t.upper()}:** {content}")
+        elif t == "table":
+            rows = block.properties.get("rows", [])
+            if rows:
+                header = rows[0]
+                lines.append("| " + " | ".join(str(v) for v in header) + " |")
+                lines.append("| " + " | ".join("---" for _ in header) + " |")
+                for row in rows[1:]:
+                    lines.append("| " + " | ".join(str(v) for v in row) + " |")
+        elif t == "divider":
+            lines.append("---")
+        else:
+            lines.append(f"{content}")
+
+        if lines and lines[-1] != "":
+            lines.append("")
+
+    return "\n".join(lines).strip() + "\n"
+
+
+def _render_block_html(block: IntentBlock) -> str:
+    t = block.type
+    content = html.escape(block.content)
+
+    if t == "title":
+        return f'<h1 class="it-block it-title">{content}</h1>'
+    if t == "summary":
+        return f'<p class="it-block it-summary">{content}</p>'
+    if t == "section":
+        return f'<h2 class="it-block it-section">{content}</h2>'
+    if t == "sub":
+        return f'<h3 class="it-block it-sub">{content}</h3>'
+    if t == "quote":
+        by = block.properties.get("by")
+        footer = f"<cite>{html.escape(str(by))}</cite>" if by else ""
+        return f'<blockquote class="it-block it-quote"><p>{content}</p>{footer}</blockquote>'
+    if t in {"note", "info", "warning", "tip", "success"}:
+        extra = "it-callout " + (t if t != "note" else "info")
+        return f'<div class="it-block {extra}"><span class="it-keyword">{t}:</span> {content}</div>'
+    if t == "task":
+        done = str(block.properties.get("status", "")).lower() == "done"
+        mark = "[x]" if done else "[ ]"
+        done_cls = " done" if done else ""
+        return f'<div class="it-block it-task{done_cls}"><span>{mark}</span><span>{content}</span></div>'
+    if t == "image":
+        src = html.escape(str(block.properties.get("src", "")))
+        alt = html.escape(str(block.properties.get("alt", block.content)))
+        return f'<figure class="it-block it-image"><img src="{src}" alt="{alt}"/></figure>'
+    if t == "link":
+        href = html.escape(str(block.properties.get("href", "#")))
+        return f'<p class="it-block it-link"><a href="{href}">{content}</a></p>'
+    if t == "code":
+        return f'<pre class="it-block it-code"><code>{content}</code></pre>'
+    if t == "table":
+        rows = block.properties.get("rows", [])
+        if not rows:
+            return ""
+        header = rows[0]
+        body_rows = rows[1:]
+        thead = "".join(f"<th>{html.escape(str(c))}</th>" for c in header)
+        tbody = "".join(
+            "<tr>" + "".join(f"<td>{html.escape(str(c))}</td>" for c in row) + "</tr>"
+            for row in body_rows
+        )
+        return f'<table class="it-block it-table"><thead><tr>{thead}</tr></thead><tbody>{tbody}</tbody></table>'
+    if t == "divider":
+        return '<hr class="it-block it-divider"/>'
+
+    return f'<p class="it-block it-{html.escape(t)}">{content}</p>'

intenttext/source.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from .types import IntentDocument
+
+
+def to_source(doc: IntentDocument) -> str:
+    lines: list[str] = []
+
+    for block in doc.blocks:
+        if block.type == "divider":
+            lines.append("---")
+            continue
+
+        if block.type == "table":
+            for row in block.properties.get("rows", []):
+                lines.append("| " + " | ".join(str(c) for c in row) + " |")
+            continue
+
+        keyword = block.type
+        props = dict(block.properties)
+
+        if block.type == "task" and str(props.get("status", "")).lower() == "done":
+            keyword = "done"
+            props.pop("status", None)
+
+        parts = [f"{keyword}: {block.original_content or block.content}".rstrip()]
+        for key, value in props.items():
+            parts.append(f"{key}: {value}")
+
+        lines.append(" | ".join(parts))
+
+    return "\n".join(lines)

intenttext/types.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class InlineSegment:
+    type: str
+    value: str
+    href: Optional[str] = None
+
+
+@dataclass
+class IntentBlock:
+    id: str
+    type: str
+    content: str
+    original_content: str
+    inline: list[InlineSegment] = field(default_factory=list)
+    properties: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class IntentMetadata:
+    title: Optional[str] = None
+    summary: Optional[str] = None
+    agent: Optional[str] = None
+    model: Optional[str] = None
+    language: str = "ltr"
+    context: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class IntentDocument:
+    version: str
+    blocks: list[IntentBlock]
+    metadata: IntentMetadata = field(default_factory=IntentMetadata)
+
+
+@dataclass
+class ParseWarning:
+    line: int
+    message: str
+    code: str
+    original: str
+
+
+@dataclass
+class ParseResult:
+    document: IntentDocument
+    warnings: list[ParseWarning] = field(default_factory=list)
+    errors: list[ParseWarning] = field(default_factory=list)
+
+
+@dataclass
+class ValidationIssue:
+    block_id: str
+    block_type: str
+    type: str
+    code: str
+    message: str
+
+
+@dataclass
+class ValidationResult:
+    valid: bool
+    issues: list[ValidationIssue] = field(default_factory=list)

intenttext/validate.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+from .types import IntentDocument, ValidationIssue, ValidationResult
+
+
+def validate(doc: IntentDocument) -> ValidationResult:
+    issues: list[ValidationIssue] = []
+
+    step_ids = {
+        block.id
+        for block in doc.blocks
+        if block.type in {"step", "decision", "parallel", "gate", "call", "result"}
+    }
+    all_ids = [block.id for block in doc.blocks]
+
+    # Duplicate block IDs
+    seen: set[str] = set()
+    for block_id in all_ids:
+        if block_id in seen:
+            issues.append(
+                ValidationIssue(
+                    block_id=block_id,
+                    block_type="document",
+                    type="error",
+                    code="DUPLICATE_ID",
+                    message=f"Duplicate block id '{block_id}'",
+                )
+            )
+        seen.add(block_id)
+
+    context_vars = set(doc.metadata.context.keys())
+    produced_vars = {
+        str(block.properties.get("output"))
+        for block in doc.blocks
+        if "output" in block.properties and str(block.properties.get("output"))
+    }
+
+    for block in doc.blocks:
+        if block.type == "gate" and not block.properties.get("approver"):
+            issues.append(
+                ValidationIssue(
+                    block_id=block.id,
+                    block_type=block.type,
+                    type="error",
+                    code="GATE_APPROVER_REQUIRED",
+                    message="gate: block requires approver property",
+                )
+            )
+
+        depends = block.properties.get("depends")
+        if isinstance(depends, str) and depends and depends not in step_ids:
+            issues.append(
+                ValidationIssue(
+                    block_id=block.id,
+                    block_type=block.type,
+                    type="error",
+                    code="STEP_REF_MISSING",
+                    message=f"depends references missing step '{depends}'",
+                )
+            )
+
+        if block.type == "decision":
+            for key in ("then", "else"):
+                ref = block.properties.get(key)
+                if isinstance(ref, str) and ref and ref not in step_ids:
+                    issues.append(
+                        ValidationIssue(
+                            block_id=block.id,
+                            block_type=block.type,
+                            type="error",
+                            code="STEP_REF_MISSING",
+                            message=f"decision {key} references missing step '{ref}'",
+                        )
+                    )
+
+        if block.type == "parallel":
+            steps = block.properties.get("steps")
+            if isinstance(steps, str):
+                for ref in [s.strip() for s in steps.split(",") if s.strip()]:
+                    if ref not in step_ids:
+                        issues.append(
+                            ValidationIssue(
+                                block_id=block.id,
+                                block_type=block.type,
+                                type="error",
+                                code="STEP_REF_MISSING",
+                                message=f"parallel steps references missing step '{ref}'",
+                            )
+                        )
+
+        for var in _extract_vars(block):
+            # runtime placeholders are intentionally unresolved
+            if var in {"page", "pages"}:
+                continue
+            top = var.split(".")[0]
+            if top not in context_vars and top not in produced_vars:
+                issues.append(
+                    ValidationIssue(
+                        block_id=block.id,
+                        block_type=block.type,
+                        type="warning",
+                        code="VARIABLE_UNRESOLVED",
+                        message=f"Variable '{{{{{var}}}}}' is not declared in context: or step output",
+                    )
+                )
+
+    has_errors = any(issue.type == "error" for issue in issues)
+    return ValidationResult(valid=not has_errors, issues=issues)
+
+
+def _extract_vars(block) -> Iterable[str]:
+    pattern = re.compile(r"\{\{([^}]+)\}\}")
+    values = [block.content, block.original_content]
+    values.extend(str(v) for v in block.properties.values() if isinstance(v, str))
+
+    for value in values:
+        for match in pattern.finditer(value):
+            yield match.group(1).strip()

intenttext-1.0.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: intenttext
+Version: 1.0.0
+Summary: IntentText - the semantic document format that is natively JSON
+Project-URL: Homepage, https://github.com/intenttext/IntentText
+Project-URL: Repository, https://github.com/intenttext/intenttext-python
+Project-URL: Documentation, https://github.com/intenttext/IntentText/blob/main/docs/SPEC.md
+License: MIT
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# IntentText Python
+
+Python implementation of the IntentText parser and renderer.
+
+Independent implementation (not a Node.js wrapper), designed for Python workflows and AI stacks.
+
+## Install
+
+```bash
+pip install intenttext
+```
+
+## Quick Start
+
+```python
+from intenttext import parse, render_html, merge_data, validate, query
+
+# Parse a document
+source = """
+title: Sprint Planning
+section: Tasks
+task: Write tests | owner: Ahmed | due: Friday
+task: Deploy to staging | owner: Sarah | due: Monday
+gate: Final approval | approver: Lead | timeout: 24h
+""".strip()
+
+doc = parse(source)
+
+# Query for tasks
+tasks = query(doc, type="task")
+for task in tasks:
+    print(f"{task.content} -> {task.properties.get('owner', 'unassigned')}")
+
+# Validate workflow semantics
+result = validate(doc)
+if not result.valid:
+    for issue in result.issues:
+        print(f"[{issue.type.upper()}] {issue.message}")
+
+# Render to HTML
+html = render_html(doc)
+```
+
+## API
+
+- `parse(source: str) -> IntentDocument`
+- `parse_safe(source: str, ...) -> ParseResult`
+- `render_html(doc: IntentDocument, include_css: bool = True) -> str`
+- `render_print(doc: IntentDocument) -> str`
+- `render_markdown(doc: IntentDocument) -> str`
+- `merge_data(template: IntentDocument, data: dict) -> IntentDocument`
+- `parse_and_merge(template_source: str, data: dict) -> IntentDocument`
+- `validate(doc: IntentDocument) -> ValidationResult`
+- `query(doc: IntentDocument, ...) -> list[IntentBlock]`
+- `to_source(doc: IntentDocument) -> str`
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## Release (PyPI)
+
+```bash
+# 1) Ensure tests pass
+python3 -m pytest -q
+
+# 2) Build source + wheel
+python3 -m pip install -U hatch twine
+hatch build
+
+# 3) Validate package metadata and long description
+twine check dist/*
+
+# 4) Upload (interactive)
+twine upload dist/*
+```
+
+Tag-based release flow:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+GitHub Action publish workflow uses `PYPI_API_TOKEN` for automated release on `v*` tags.
+
+## License
+
+MIT

intenttext-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+intenttext/__init__.py,sha256=2aztUfxzJzY631dzrU4J3Ra-8U-Ayn5qnGub5lJ5c5Y,801
+intenttext/merge.py,sha256=_yO0LXaoXPKQ5nEAoCBYggMaPwuZYCM724IMVGogkAw,2525
+intenttext/parser.py,sha256=1wGxeHcXSk6F66H7k5_vW3rGua__3l89W3qwnKSovKA,10592
+intenttext/query.py,sha256=LpyuaT6mMBGj1iNLYay8AMTsdrqTCjB9aLZLC_E4K4Q,1624
+intenttext/renderer.py,sha256=E8gYJeSBXDdarb_nbKccFtiG4Gpk05ZvRMj_NqBHSuw,5704
+intenttext/source.py,sha256=wkhaEhfHPSYwSLPvIqWmz9TRoNyIgXivt9HEdSoMN8A,909
+intenttext/types.py,sha256=okWFdR-hdTPG8i3owMUn8fWXxKmQ6C9H4LTmjUXh-bY,1345
+intenttext/validate.py,sha256=RJ2DfUpO-Tzl-dPfN8X8AqP-LGNprxAq59GTKXmtD10,4459
+intenttext-1.0.0.dist-info/METADATA,sha256=5IDUqVHA5S_vozjHejSPhvSd261jzSWuK0BFWp8XX9o,2544
+intenttext-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+intenttext-1.0.0.dist-info/RECORD,,

intenttext-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any