baresexp 1.0.0__tar.gz

baresexp-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

baresexp-1.0.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: baresexp
+Version: 1.0.0
+Summary: Minimal token S-expression format AI agent instruction language
+Project-URL: Homepage, https://github.com/zayarmoekaung/baresexp#readme
+Project-URL: Repository, https://github.com/zayarmoekaung/BareSexp.git
+Project-URL: Issues, https://github.com/zayarmoekaung/baresexp/issues
+Author-email: Zayar Moe Kaung <zayarmoekaung@gmail.com>
+License-Expression: MIT
+Keywords: agent,ai,llm,prompt-engineering,s-expression
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# baresexp (Python)
+
+Minimal-token S-expression language for AI agent instructions.
+
+## Install
+
+```bash
+pip install baresexp
+```
+
+## Quick start
+
+```python
+from baresexp import builder
+
+result = (
+    builder
+    .task("research-agent", description="Research and summarize a topic")
+    .step("collect", description="Gather sources")
+    .tool("web-search", description="Search the web")
+    .compile()
+)
+
+print(result.baresexp)
+```
+
+## Minimal mode
+
+```python
+from baresexp import builder
+
+result = (
+    builder
+    .minimal()
+    .task("research-agent", description="Research and summarize the latest news")
+    .step("collect", description="Gather sources")
+    .compile(mode="minimal")
+)
+
+print(result.baresexp)       # compact output
+print(result.token_count)    # estimated token count
+print(result.metadata)       # original ↔ shortened mapping
+```
+
+## API
+
+| Function        | Description                          |
+| --------------- | ------------------------------------ |
+| `builder`       | Fluent builder entry point           |
+| `compile_baresexp(task)` | Compile a Task to S-expression |
+| `parse_baresexp(text)`   | Parse S-expression to a Task  |
+| `validate_baresexp(obj)` | Validate a Task structure     |
+| `minimize_description(text)` | Minimize a description string |

baresexp-1.0.0/README.md

@@ -0,0 +1,53 @@
+# baresexp (Python)
+
+Minimal-token S-expression language for AI agent instructions.
+
+## Install
+
+```bash
+pip install baresexp
+```
+
+## Quick start
+
+```python
+from baresexp import builder
+
+result = (
+    builder
+    .task("research-agent", description="Research and summarize a topic")
+    .step("collect", description="Gather sources")
+    .tool("web-search", description="Search the web")
+    .compile()
+)
+
+print(result.baresexp)
+```
+
+## Minimal mode
+
+```python
+from baresexp import builder
+
+result = (
+    builder
+    .minimal()
+    .task("research-agent", description="Research and summarize the latest news")
+    .step("collect", description="Gather sources")
+    .compile(mode="minimal")
+)
+
+print(result.baresexp)       # compact output
+print(result.token_count)    # estimated token count
+print(result.metadata)       # original ↔ shortened mapping
+```
+
+## API
+
+| Function        | Description                          |
+| --------------- | ------------------------------------ |
+| `builder`       | Fluent builder entry point           |
+| `compile_baresexp(task)` | Compile a Task to S-expression |
+| `parse_baresexp(text)`   | Parse S-expression to a Task  |
+| `validate_baresexp(obj)` | Validate a Task structure     |
+| `minimize_description(text)` | Minimize a description string |

baresexp-1.0.0/examples/minimal_research_agent.py

@@ -0,0 +1,38 @@
+"""Example: full vs minimal mode comparison."""
+
+from baresexp import builder
+
+full = (
+    builder
+    .task(
+        "research-agent",
+        description="Research and summarize the latest news about AI agents and tools for this week",
+    )
+    .step("collect-context", description="Gather recent sources and extract user-relevant facts")
+    .compile(mode="full")
+)
+
+minimal = (
+    builder
+    .minimal()
+    .task(
+        "research-agent",
+        description="Research and summarize the latest news about AI agents and tools for this week",
+    )
+    .step("collect-context", description="Gather recent sources and extract user-relevant facts")
+    .compile(mode="minimal")
+)
+
+print("FULL")
+print(full.baresexp)
+print("TOKENS", full.token_count)
+print()
+print("MINIMAL")
+print(minimal.baresexp)
+print("TOKENS", minimal.token_count)
+print()
+print("METADATA")
+for task_id, entries in minimal.metadata.items():
+    print(f"  {task_id}:")
+    for entry in entries:
+        print(f"    {entry.field_path}: {entry.original!r} -> {entry.shortened!r}")

baresexp-1.0.0/examples/research_agent.py

@@ -0,0 +1,14 @@
+"""Example: basic research agent with the builder API."""
+
+from baresexp import builder, compile_baresexp
+
+task = (
+    builder
+    .task("research-agent", description="Research a topic and return a concise summary")
+    .step("collect-context", description="Gather reputable sources and extract key facts")
+    .tool("web-search", description="Search the web for supporting references")
+    .build()
+)
+
+result = compile_baresexp(task)
+print(result.baresexp)

baresexp-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "baresexp"
+version = "1.0.0"
+description = "Minimal token S-expression format AI agent instruction language"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Zayar Moe Kaung", email = "zayarmoekaung@gmail.com" },
+]
+keywords = ["ai", "llm", "agent", "prompt-engineering", "s-expression"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/zayarmoekaung/baresexp#readme"
+Repository = "https://github.com/zayarmoekaung/BareSexp.git"
+Issues = "https://github.com/zayarmoekaung/baresexp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/baresexp"]

baresexp-1.0.0/src/baresexp/__init__.py

@@ -0,0 +1,37 @@
+"""BareSexp — minimal-token S-expression language for AI agent instructions."""
+
+from .builder import BareSexpBuilder, builder
+from .compiler import compile_baresexp
+from .minimizer import minimize_description, minimize_field_name
+from .parser import parse_baresexp
+from .types import (
+    BareSexpResult,
+    CompileOptions,
+    MetadataEntry,
+    Options,
+    OutputSpec,
+    OutputMode,
+    Step,
+    Task,
+    Tool,
+)
+from .validator import validate_baresexp
+
+__all__ = [
+    "BareSexpBuilder",
+    "BareSexpResult",
+    "CompileOptions",
+    "MetadataEntry",
+    "Options",
+    "OutputMode",
+    "OutputSpec",
+    "Step",
+    "Task",
+    "Tool",
+    "builder",
+    "compile_baresexp",
+    "minimize_description",
+    "minimize_field_name",
+    "parse_baresexp",
+    "validate_baresexp",
+]

baresexp-1.0.0/src/baresexp/builder.py

@@ -0,0 +1,171 @@
+"""Builder — fluent API for constructing BareSexp tasks."""
+
+from __future__ import annotations
+
+from .compiler import compile_baresexp
+from .types import (
+    BareSexpResult,
+    MetadataStore,
+    Options,
+    OutputMode,
+    OutputSpec,
+    Step,
+    Task,
+    Tool,
+)
+
+
+# Forward reference for return types
+_OutputMode = OutputMode
+
+
+class _StepBuilder:
+    """Fluent builder for a single step."""
+
+    def __init__(self, task_data: Task, step: Step, mode: OutputMode) -> None:
+        self._task_data = task_data
+        self._step = step
+        self._mode = mode
+
+    def tool(
+        self,
+        name: str = "tool",
+        *,
+        description: str | None = None,
+        input: str | None = None,
+        output: str | None = None,
+    ) -> _StepBuilder:
+        t = Tool(name=name, description=description, input=input, output=output)
+        self._step.tools.append(t)
+        return self
+
+    def step(
+        self,
+        name: str = "step",
+        *,
+        description: str | None = None,
+        input: str | None = None,
+        output: str | None = None,
+    ) -> _StepBuilder:
+        s = Step(name=name, description=description, input=input, output=output)
+        self._task_data.steps.append(s)
+        return _StepBuilder(self._task_data, s, self._mode)
+
+    def build(self) -> Task:
+        return self._task_data
+
+    def compile(
+        self,
+        *,
+        mode: OutputMode | None = None,
+        preserve_metadata: bool = True,
+        condense: bool = False,
+    ) -> BareSexpResult:
+        return compile_baresexp(
+            self._task_data,
+            mode=mode or self._mode,
+            preserve_metadata=preserve_metadata,
+            condense=condense,
+        )
+
+
+class _TaskBuilder:
+    """Fluent builder for a task."""
+
+    def __init__(self, task_data: Task, mode: OutputMode) -> None:
+        self._task_data = task_data
+        self._mode = mode
+
+    def step(
+        self,
+        name: str = "step",
+        *,
+        description: str | None = None,
+        input: str | None = None,
+        output: str | None = None,
+    ) -> _StepBuilder:
+        s = Step(name=name, description=description, input=input, output=output)
+        self._task_data.steps.append(s)
+        return _StepBuilder(self._task_data, s, self._mode)
+
+    def tool(
+        self,
+        name: str = "tool",
+        *,
+        description: str | None = None,
+        input: str | None = None,
+        output: str | None = None,
+    ) -> _TaskBuilder:
+        t = Tool(name=name, description=description, input=input, output=output)
+        self._task_data.tools.append(t)
+        return self
+
+    def output(
+        self,
+        *,
+        format: str | None = None,
+        schema: str | None = None,
+        description: str | None = None,
+    ) -> _TaskBuilder:
+        self._task_data.output = OutputSpec(
+            format=format, schema=schema, description=description
+        )
+        return self
+
+    def options(
+        self,
+        *,
+        strict: bool | None = None,
+        indent: int | None = None,
+        include_metadata: bool | None = None,
+    ) -> _TaskBuilder:
+        self._task_data.options = Options(
+            strict=strict, indent=indent, include_metadata=include_metadata
+        )
+        return self
+
+    def build(self) -> Task:
+        return self._task_data
+
+    def compile(
+        self,
+        *,
+        mode: OutputMode | None = None,
+        preserve_metadata: bool = True,
+        condense: bool = False,
+    ) -> BareSexpResult:
+        return compile_baresexp(
+            self._task_data,
+            mode=mode or self._mode,
+            preserve_metadata=preserve_metadata,
+            condense=condense,
+        )
+
+
+class BareSexpBuilder:
+    """Top-level builder entry point."""
+
+    def __init__(self) -> None:
+        self._mode: OutputMode = "full"
+
+    def minimal(self) -> BareSexpBuilder:
+        """Switch to minimal output mode for all subsequent compiles."""
+        self._mode = "minimal"
+        return self
+
+    def full(self) -> BareSexpBuilder:
+        """Switch to full output mode."""
+        self._mode = "full"
+        return self
+
+    def task(
+        self,
+        name: str = "task",
+        *,
+        description: str | None = None,
+    ) -> _TaskBuilder:
+        t = Task(name=name, description=description)
+        return _TaskBuilder(t, self._mode)
+
+
+builder = BareSexpBuilder()

baresexp-1.0.0/src/baresexp/compiler.py

@@ -0,0 +1,159 @@
+"""Compiler — serializes typed Task objects into BareSexp text."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .minimizer import minimize_description
+from .types import (
+    BareSexpResult,
+    CompileOptions,
+    MetadataEntry,
+    MetadataStore,
+    OutputMode,
+    Step,
+    Task,
+    Tool,
+)
+
+
+def _escape_token(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _format_value(value: Any, mode: OutputMode = "full") -> str:
+    if isinstance(value, str):
+        normalized = value.strip()
+        effective = minimize_description(normalized) if mode == "minimal" else normalized
+        if not effective or re.search(r'[\s()"\']', effective, re.UNICODE):
+            return f'"{_escape_token(effective)}"'
+        return effective
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return "null"
+
+
+def compile_baresexp(
+    task: Task,
+    *,
+    mode: OutputMode = "full",
+    preserve_metadata: bool = True,
+    condense: bool = False,
+) -> BareSexpResult:
+    """Compile a Task into BareSexp text."""
+    metadata: MetadataStore = {}
+    indent = "" if condense else " "
+    lines: list[str] = [f"(task {_format_value(task.name, mode)}"]
+
+    if task.description:
+        _add_metadata(metadata, task.name, "description", task.description, mode, preserve_metadata)
+        lines.append(f"{indent}(description {_format_value(task.description, mode)})")
+
+    if task.steps:
+        lines.append(f"{indent}(steps")
+        for step in task.steps:
+            lines.append(_compile_step(step, condense, 2, mode, metadata, preserve_metadata, task.name))
+        lines.append(f"{indent})")
+
+    if task.tools:
+        lines.append(f"{indent}(tools")
+        for tool in task.tools:
+            lines.append(_compile_tool(tool, condense, 2, mode, metadata, preserve_metadata, task.name))
+        lines.append(f"{indent})")
+
+    lines.append(")")
+
+    baresexp = "".join(lines) if condense else "\n".join(lines)
+    token_count = _estimate_token_count(baresexp)
+    return BareSexpResult(baresexp=baresexp, metadata=metadata, token_count=token_count)
+
+
+def _compile_step(
+    step: Step,
+    condense: bool,
+    indent_level: int,
+    mode: OutputMode,
+    metadata: MetadataStore,
+    preserve_metadata: bool,
+    task_id: str,
+) -> str:
+    indent = "" if condense else "  " * indent_level
+    child_indent = "" if condense else "  " * (indent_level + 1)
+    has_children = bool(step.description or step.tools or step.input or step.output)
+    lines: list[str] = [f"{indent}(step {_format_value(step.name, mode)}"]
+
+    if step.description:
+        _add_metadata(metadata, task_id, f"steps.{step.name}.description", step.description, mode, preserve_metadata)
+        lines.append(f"{child_indent}(description {_format_value(step.description, mode)})")
+
+    if step.tools:
+        lines.append(f"{child_indent}(tools")
+        for tool in step.tools:
+            lines.append(_compile_tool(tool, condense, indent_level + 2, mode, metadata, preserve_metadata, task_id))
+        lines.append(f"{child_indent})")
+
+    if step.input:
+        lines.append(f"{child_indent}(input {_format_value(step.input, mode)})")
+    if step.output:
+        lines.append(f"{child_indent}(output {_format_value(step.output, mode)})")
+
+    if not has_children:
+        return f"{indent}(step {_format_value(step.name, mode)})"
+
+    lines.append(f"{indent})")
+    return "".join(lines) if condense else "\n".join(lines)
+
+
+def _compile_tool(
+    tool: Tool,
+    condense: bool,
+    indent_level: int,
+    mode: OutputMode,
+    metadata: MetadataStore,
+    preserve_metadata: bool,
+    task_id: str,
+) -> str:
+    indent = "" if condense else "  " * indent_level
+    child_indent = "" if condense else "  " * (indent_level + 1)
+    has_children = bool(tool.description or tool.input or tool.output)
+    lines: list[str] = [f"{indent}(tool {_format_value(tool.name, mode)}"]
+
+    if tool.description:
+        _add_metadata(metadata, task_id, f"tools.{tool.name}.description", tool.description, mode, preserve_metadata)
+        lines.append(f"{child_indent}(description {_format_value(tool.description, mode)})")
+
+    if tool.input:
+        lines.append(f"{child_indent}(input {_format_value(tool.input, mode)})")
+    if tool.output:
+        lines.append(f"{child_indent}(output {_format_value(tool.output, mode)})")
+
+    if not has_children:
+        return f"{indent}(tool {_format_value(tool.name, mode)})"
+
+    lines.append(f"{indent})")
+    return "".join(lines) if condense else "\n".join(lines)
+
+
+def _add_metadata(
+    metadata: MetadataStore,
+    task_id: str,
+    field_path: str,
+    original: Any,
+    mode: OutputMode,
+    preserve_metadata: bool,
+) -> MetadataEntry | None:
+    if not preserve_metadata:
+        return None
+    shortened = minimize_description(str(original)) if mode == "minimal" else str(original)
+    entry = MetadataEntry(original=original, field_path=field_path, shortened=shortened)
+    if task_id not in metadata:
+        metadata[task_id] = []
+    metadata[task_id].append(entry)
+    return entry
+
+
+def _estimate_token_count(value: str) -> int:
+    return max(1, int(len(value.split()) * 1.2))

baresexp-1.0.0/src/baresexp/minimizer.py

@@ -0,0 +1,40 @@
+"""Minimizer — reduces descriptions to compact kebab-case tokens."""
+
+import re
+
+_STOP_WORDS = frozenset({
+    "a", "an", "and", "the", "for", "to", "of", "in", "on", "with",
+    "from", "into", "about", "this", "that", "these", "those",
+    "latest", "recent", "new", "very", "your", "our", "their",
+    "its", "is", "are", "be", "been", "being", "will", "can",
+    "could", "should", "would", "use", "using", "used", "or",
+})
+
+
+def minimize_description(text: str) -> str:
+    """Collapse a prose description into a short kebab-case token string."""
+    normalized = re.sub(r"[^a-zA-Z0-9\s-]", " ", text)
+    normalized = re.sub(r"\s+", " ", normalized).strip()
+
+    if not normalized:
+        return "desc"
+
+    words = [
+        w for w in normalized.split(" ")
+        if len(w) > 1 and w.lower() not in _STOP_WORDS
+    ]
+
+    if not words:
+        return _kebab(normalized)[:24]
+
+    core = words[:6]
+    return _kebab(" ".join(w.lower() for w in core))
+
+
+def minimize_field_name(name: str) -> str:
+    """Normalize a field name to kebab-case."""
+    return _kebab(name)
+
+
+def _kebab(value: str) -> str:
+    return re.sub(r"^-+|-+$", "", re.sub(r"[^a-z0-9]+", "-", value.lower()))[:40]

baresexp-1.0.0/src/baresexp/parser.py

@@ -0,0 +1,241 @@
+"""Parser — turns BareSexp text back into typed objects."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .types import OutputSpec, Options, Step, Task, Tool
+
+
+def _tokenize(input_text: str) -> list[str]:
+    tokens: list[str] = []
+    index = 0
+
+    while index < len(input_text):
+        char = input_text[index]
+        if re.match(r"\s", char, re.UNICODE):
+            index += 1
+            continue
+
+        if char in ("(", ")"):
+            tokens.append(char)
+            index += 1
+            continue
+
+        if char == '"':
+            escaped = False
+            value = '"'
+            index += 1
+            while index < len(input_text):
+                current = input_text[index]
+                if escaped:
+                    value += current
+                    escaped = False
+                elif current == "\\":
+                    value += current
+                    escaped = True
+                elif current == '"':
+                    value += current
+                    index += 1
+                    break
+                else:
+                    value += current
+                index += 1
+            tokens.append(value)
+            continue
+
+        value = ""
+        while index < len(input_text) and not re.match(r"[\s()]", input_text[index], re.UNICODE):
+            value += input_text[index]
+            index += 1
+        tokens.append(value)
+
+    return tokens
+
+
+def _parse_expression(tokens: list[str], index: int) -> tuple[Any, int]:
+    if tokens[index] == "(":
+        items: list[Any] = []
+        cursor = index + 1
+        while cursor < len(tokens) and tokens[cursor] != ")":
+            if tokens[cursor] == "(":
+                parsed, cursor = _parse_expression(tokens, cursor)
+                items.append(parsed)
+            else:
+                items.append(tokens[cursor])
+                cursor += 1
+        return items, cursor + 1
+
+    return tokens[index], index + 1
+
+
+def _parse_scalar(value: Any) -> str | int | float | bool | None:
+    if not isinstance(value, str):
+        return value
+
+    trimmed = value.strip()
+    if trimmed.startswith('"') and trimmed.endswith('"'):
+        return trimmed[1:-1]
+
+    if trimmed == "true":
+        return True
+    if trimmed == "false":
+        return False
+    if re.match(r"^-?\d+(\.\d+)?$", trimmed):
+        return float(trimmed) if "." in trimmed else int(trimmed)
+    return trimmed
+
+
+def _parse_task(parts: list[Any]) -> Task:
+    task = Task(
+        name=parts[0] if isinstance(parts[0], str) else "task",
+    )
+
+    for child in parts[1:]:
+        if not isinstance(child, list):
+            continue
+
+        key = child[0] if child else None
+        body = child[1:]
+        if not isinstance(key, str):
+            continue
+
+        if key == "description":
+            task.description = _parse_scalar(body[0]) if body else None
+        elif key == "steps":
+            task.steps = [_parse_step(item) for item in body if isinstance(item, list)]
+        elif key == "tools":
+            task.tools = [_parse_tool(item) for item in body if isinstance(item, list)]
+        elif key == "output":
+            task.output = _parse_output(body)
+        elif key == "options":
+            task.options = _parse_options(body)
+
+    return task
+
+
+def _parse_step(node: Any) -> Step:
+    if not isinstance(node, list):
+        return Step()
+
+    key = node[0] if node else None
+    body = node[1:]
+    if not isinstance(key, str) or key != "step":
+        return Step()
+
+    step = Step(
+        name=body[0] if body and isinstance(body[0], str) else "step",
+    )
+
+    for child in body[1:]:
+        if not isinstance(child, list):
+            continue
+
+        field_name = child[0] if child else None
+        field_body = child[1:]
+        if not isinstance(field_name, str):
+            continue
+
+        if field_name == "description":
+            step.description = _parse_scalar(field_body[0]) if field_body else None
+        elif field_name == "tools":
+            step.tools = [_parse_tool(item) for item in field_body if isinstance(item, list)]
+        elif field_name == "input":
+            step.input = _parse_scalar(field_body[0]) if field_body else None
+        elif field_name == "output":
+            step.output = _parse_scalar(field_body[0]) if field_body else None
+
+    return step
+
+
+def _parse_tool(node: Any) -> Tool:
+    if not isinstance(node, list):
+        return Tool()
+
+    key = node[0] if node else None
+    body = node[1:]
+    if not isinstance(key, str) or key != "tool":
+        return Tool()
+
+    tool = Tool(
+        name=body[0] if body and isinstance(body[0], str) else "tool",
+    )
+
+    for child in body[1:]:
+        if not isinstance(child, list):
+            continue
+
+        field_name = child[0] if child else None
+        field_body = child[1:]
+        if not isinstance(field_name, str):
+            continue
+
+        if field_name == "description":
+            tool.description = _parse_scalar(field_body[0]) if field_body else None
+        elif field_name == "input":
+            tool.input = _parse_scalar(field_body[0]) if field_body else None
+        elif field_name == "output":
+            tool.output = _parse_scalar(field_body[0]) if field_body else None
+
+    return tool
+
+
+def _parse_output(parts: list[Any]) -> OutputSpec:
+    output = OutputSpec()
+    for child in parts:
+        if not isinstance(child, list):
+            continue
+
+        field_name = child[0] if child else None
+        field_body = child[1:]
+        if not isinstance(field_name, str):
+            continue
+
+        if field_name == "format":
+            output.format = _parse_scalar(field_body[0]) if field_body else None
+        elif field_name == "schema":
+            output.schema = _parse_scalar(field_body[0]) if field_body else None
+        elif field_name == "description":
+            output.description = _parse_scalar(field_body[0]) if field_body else None
+
+    return output
+
+
+def _parse_options(parts: list[Any]) -> Options:
+    options = Options()
+    for child in parts:
+        if not isinstance(child, list):
+            continue
+
+        field_name = child[0] if child else None
+        field_body = child[1:]
+        if not isinstance(field_name, str):
+            continue
+
+        if field_name == "strict":
+            val = _parse_scalar(field_body[0]) if field_body else None
+            options.strict = bool(val) if val is not None else None
+        elif field_name == "indent":
+            val = _parse_scalar(field_body[0]) if field_body else None
+            options.indent = int(val) if val is not None else None
+        elif field_name == "includeMetadata":
+            val = _parse_scalar(field_body[0]) if field_body else None
+            options.include_metadata = bool(val) if val is not None else None
+
+    return options
+
+
+def parse_baresexp(input_text: str) -> Task:
+    """Parse BareSexp text into a Task object."""
+    tokens = _tokenize(input_text.strip())
+    if not tokens:
+        return Task()
+
+    parsed, _ = _parse_expression(tokens, 0)
+    if isinstance(parsed, list):
+        head, *body = parsed
+        if head == "task":
+            return _parse_task(body)
+
+    return Task()

baresexp-1.0.0/src/baresexp/types.py

@@ -0,0 +1,94 @@
+"""Type definitions for BareSexp structured objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+OutputMode = Literal["full", "minimal"]
+
+
+@dataclass
+class CompileOptions:
+    """Options for compiling a task to BareSexp."""
+
+    mode: OutputMode = "full"
+    preserve_metadata: bool = True
+    condense: bool = False
+    indent: bool = True
+
+
+@dataclass
+class MetadataEntry:
+    """Stores original and shortened values for a field."""
+
+    original: object
+    field_path: str
+    shortened: str | None = None
+
+
+@dataclass
+class Tool:
+    """A tool available to a step or task."""
+
+    name: str = "tool"
+    description: str | None = None
+    input: str | None = None
+    output: str | None = None
+    metadata: list[MetadataEntry] = field(default_factory=list)
+
+
+@dataclass
+class Step:
+    """A step within a task."""
+
+    name: str = "step"
+    description: str | None = None
+    tools: list[Tool] = field(default_factory=list)
+    input: str | None = None
+    output: str | None = None
+    metadata: list[MetadataEntry] = field(default_factory=list)
+
+
+@dataclass
+class OutputSpec:
+    """Output format specification."""
+
+    format: str | None = None
+    schema: str | None = None
+    description: str | None = None
+    metadata: list[MetadataEntry] = field(default_factory=list)
+
+
+@dataclass
+class Options:
+    """Task-level options."""
+
+    strict: bool | None = None
+    indent: int | None = None
+    include_metadata: bool | None = None
+
+
+@dataclass
+class Task:
+    """Top-level BareSexp task document."""
+
+    name: str = "task"
+    description: str | None = None
+    steps: list[Step] = field(default_factory=list)
+    tools: list[Tool] = field(default_factory=list)
+    output: OutputSpec | None = None
+    options: Options | None = None
+    metadata: list[MetadataEntry] = field(default_factory=list)
+
+
+@dataclass
+class BareSexpResult:
+    """Result of compiling a task to BareSexp text."""
+
+    baresexp: str
+    metadata: dict[str, list[MetadataEntry]]
+    token_count: int = 0
+
+
+MetadataStore = dict[str, list[MetadataEntry]]

baresexp-1.0.0/src/baresexp/validator.py

@@ -0,0 +1,42 @@
+"""Validator — checks structural correctness of BareSexp objects."""
+
+from .types import Step, Task, Tool
+
+
+def validate_baresexp(value: object) -> bool:
+    """Return True if value is a structurally valid Task."""
+    if not isinstance(value, Task):
+        return False
+
+    if not value.name or not value.name.strip():
+        return False
+
+    if value.steps is not None:
+        for step in value.steps:
+            if not _is_valid_step(step):
+                return False
+
+    if value.tools is not None:
+        for tool in value.tools:
+            if not _is_valid_tool(tool):
+                return False
+
+    return True
+
+
+def _is_valid_step(value: object) -> bool:
+    if not isinstance(value, Step):
+        return False
+    if not value.name or not value.name.strip():
+        return False
+    if value.tools is not None:
+        for tool in value.tools:
+            if not _is_valid_tool(tool):
+                return False
+    return True
+
+
+def _is_valid_tool(value: object) -> bool:
+    if not isinstance(value, Tool):
+        return False
+    return bool(value.name and value.name.strip())

baresexp-1.0.0/tests/test_minimal.py

@@ -0,0 +1,59 @@
+"""Minimal mode tests."""
+
+import pytest
+
+from baresexp import builder
+
+
+def test_minimal_mode_shortens_output_and_stores_metadata():
+    result = (
+        builder
+        .minimal()
+        .task(
+            "research-agent",
+            description="Research and summarize the latest news about AI agents and tools for this week",
+        )
+        .step("collect-context", description="Gather recent sources and extract user-relevant facts")
+        .compile(mode="minimal")
+    )
+
+    assert len(result.baresexp) < 220
+    assert result.token_count > 0
+    assert "research-agent" in result.metadata
+    assert result.metadata["research-agent"][0].original == (
+        "Research and summarize the latest news about AI agents and tools for this week"
+    )
+
+
+def test_minimal_vs_full_token_count():
+    full = (
+        builder
+        .task(
+            "florida-man-news",
+            description="Summarize recent Florida Man news stories into a concise briefing",
+        )
+        .compile(mode="full")
+    )
+
+    minimal = (
+        builder
+        .minimal()
+        .task(
+            "florida-man-news",
+            description="Summarize recent Florida Man news stories into a concise briefing",
+        )
+        .compile(mode="minimal")
+    )
+
+    assert minimal.token_count < full.token_count
+
+
+def test_condense_removes_whitespace():
+    result = (
+        builder
+        .task("compact-task", description="A task with condense enabled")
+        .compile(condense=True)
+    )
+
+    assert "\n" not in result.baresexp
+    assert "  " not in result.baresexp

baresexp-1.0.0/tests/test_roundtrip.py

@@ -0,0 +1,68 @@
+"""Round-trip tests: compile -> parse -> validate."""
+
+import pytest
+
+from baresexp import builder, compile_baresexp, parse_baresexp, validate_baresexp
+
+
+def test_builder_compiles_and_round_trips():
+    task = (
+        builder
+        .task("research-agent", description="Research, summarize, and report")
+        .step("collect-context", description="Gather relevant sources")
+        .tool("web-search", description="Search the web for references")
+        .build()
+    )
+
+    bare = compile_baresexp(task)
+    parsed = parse_baresexp(bare.baresexp)
+
+    assert validate_baresexp(parsed) is True
+    assert parsed.name == "research-agent"
+    assert parsed.steps[0].name == "collect-context"
+    assert parsed.steps[0].tools[0].name == "web-search"
+
+
+def test_parse_preserves_description():
+    task = (
+        builder
+        .task("news-summary", description="Summarize today's top stories")
+        .build()
+    )
+
+    bare = compile_baresexp(task)
+    parsed = parse_baresexp(bare.baresexp)
+
+    assert parsed.description == "Summarize today's top stories"
+
+
+def test_parse_task_with_tools():
+    task = (
+        builder
+        .task("multi-tool-task")
+        .tool("search", description="Search the web")
+        .tool("read", description="Read a URL")
+        .build()
+    )
+
+    bare = compile_baresexp(task)
+    parsed = parse_baresexp(bare.baresexp)
+
+    assert len(parsed.tools) == 2
+    assert parsed.tools[0].name == "search"
+    assert parsed.tools[1].name == "read"
+
+
+def test_step_with_input_output():
+    task = (
+        builder
+        .task("pipeline")
+        .step("fetch", description="Fetch data", input="url", output="raw_data")
+        .build()
+    )
+
+    bare = compile_baresexp(task)
+    parsed = parse_baresexp(bare.baresexp)
+
+    assert parsed.steps[0].input == "url"
+    assert parsed.steps[0].output == "raw_data"