Use WeaveMark directly inside Python apps.

Install

Install WeaveMark as a normal Python package. The same installation provides the weavemark CLI and the importable weavemark library.

pip install weavemark

For local development from the repository root:

pip install -e ".[dev]"

Overview

The public API is async because WeaveMark can use an AI-backed semantic compilation path. Structural work such as variables, imports, branching, emitted files, and diagnostics is handled before that path whenever possible.

from weavemark import (
    bundled_promplet,
    compile_text,
    compile_file,
    execute_text,
    execute_file,
    read_bundled_promplet,
)

Read the built-in promplet library

The canonical corpus remains prominent at the repository root under promplets/. Wheel builds map that same tree into weavemark/promplets, so installed applications can read it without a repository checkout or a duplicate maintained copy.

from weavemark import bundled_promplet, iter_bundled_promplets, read_bundled_promplet

paths = list(iter_bundled_promplets())
resource = bundled_promplet("catalog/standalone/investment-brief.weavemark.md")
source = read_bundled_promplet(
    "stdlib/fragments/reasoning/chain-of-thought.weavemark.md"
)

Resources implement importlib.resources.abc.Traversable. Use bundled_promplet_path() as a context manager when an external tool requires a filesystem path.

from weavemark import bundled_promplet_path

with bundled_promplet_path(
    "catalog/standalone/investment-brief.weavemark.md"
) as path:
    print(path)

Compile promplet files

Use compile_file when prompts are stored as .weavemark.md files in your app or project. The file parent becomes base_dir, so relative references, module lookup, and project-level weavemark.json behave like the WeaveMark Processor.

import asyncio
from weavemark import compile_file


async def main() -> None:
    result = await compile_file(
        "promplets/support-agent.weavemark.md",
        variables={
            "product": "WeaveMark",
            "audience": "new users",
        },
    )
    if result.errors:
        raise RuntimeError(result.errors)

    print(result.composed_prompt)
    print(result.prompts)
    print(result.emits)
    print(result.tools)
    print(result.bindings)


asyncio.run(main())

Compile text

Use compile_text when WeaveMark source lives in a package resource, database, notebook, web editor, or generated document.

from pathlib import Path
from weavemark import compile_text

source = """
@promplet version: 0.7 surface: markdown

# Support answer

Reply to @{question} in a concise, kind voice.
"""

result = await compile_text(
    source,
    {"question": "How do modules work?"},
    base_dir=Path("prompts"),
)

Compilation options

CompileOptions controls the model path for semantic compilation while preserving structural processing and diagnostics.

from weavemark import CompileOptions, compile_file

compiled = await compile_file(
    "promplets/brief.weavemark.md",
    {"topic": "battery recycling"},
    options=CompileOptions(
        model="gpt-5.5",
        max_iterations=12,
        use_structural_helpers=True,
    ),
)

Advanced integrations can pass a custom async LLM client through the client parameter when they need their own provider, tracing, retry, or policy layer.

Output formatting

Most apps should consume the structured result directly. Use format_compiled_output when you need CLI-style primary output.

from weavemark import compile_file, format_compiled_output

compiled = await compile_file("promplets/review.weavemark.md")

markdown = format_compiled_output(compiled)
data_json = format_compiled_output(compiled, "json")
raw_response = format_compiled_output(compiled, "xml")

If your project defines custom formats or aliases in weavemark.json, pass base_dir or a loaded settings object so the formatter uses the same registry.

Execution

execute_file compiles first, then runs the compiled prompts through an engine. It raises WeaveMarkCompilationError when compilation has errors, so execution never proceeds with invalid prompt artifacts.

from weavemark import RuntimeConfig, execute_file

run = await execute_file(
    "promplets/tree-solver.weavemark.md",
    variables={"problem": "Design a retention strategy"},
    runtime_config=RuntimeConfig(
        model="gpt-5.5",
        allowed_models=("gpt-5.5",),
    ),
)

print(run.output)
print(run.engine)
print(run.compiled.prompts)
print(run.execution.steps)

Runtime config may be a RuntimeConfig object, a mapping, or a path to a JSON/YAML config file. Pass promplet inputs through variables; runtime config is reserved for optional host and deployment overrides.

Custom engines and callbacks

Pass a built-in engine name or any object implementing the Engine protocol.

from weavemark import execute_file
from weavemark.engines import ExecutionResult


class MyEngine:
    async def execute(self, result, config=None, on_step=None):
        return ExecutionResult(output=result.composed_prompt.upper())


run = await execute_file(
    "promplets/support-agent.weavemark.md",
    {"question": "What changed?"},
    engine=MyEngine(),
)

Use on_event for compilation events and on_step for execution-engine traces.

Diagnostics and errors

Compilation returns diagnostics in the result so applications can display warnings, errors, and suggestions in their own UI.

compiled = await compile_file("promplets/agent.weavemark.md")

for diagnostic in compiled.diagnostics:
    print(diagnostic["type"], diagnostic["message"])

During execution, catch WeaveMarkCompilationError and inspect exc.result to display the failed compile output.