Build Your Own Module

If the built-in modules don’t fit your data, you can build your own forge module. A module extends the base pipeline with domain-specific scanners, templates, and review criteria.

Module interface

from reasonsforge import ForgeModule, Pipeline

class MyForge(ForgeModule):
    name = "my-domain"

    def scan(self, config):
        """Pull data from your domain sources."""
        ...

    def templates(self):
        """Belief templates for this domain."""
        ...

    def review_criteria(self):
        """What makes a belief valid in this domain."""
        ...

Register your module, and the standard pipeline handles derive, review, repair, and export.

What each method does

scan(config)

Pulls raw data from your domain sources. Receives the CLI config (paths, URLs, credentials). Returns documents that the extract stage will process.

Examples:

• Read files from a directory
• Pull records from an API
• Query a database
• Scrape a website

templates()

Returns belief templates — structured formats for the kinds of knowledge your domain produces. Templates help the extract stage produce consistent, well-structured beliefs.

review_criteria()

Returns domain-specific criteria for the review stage. What makes a belief valid in your domain? What should the reviewer look for?

Examples:

• “Claims must cite a specific version number”
• “Measurements must include units and conditions”
• “Recommendations must reference at least one observed failure”

Example: API docs forge

from reasonsforge import ForgeModule

class ApiDocsForge(ForgeModule):
    name = "api-docs"

    def scan(self, config):
        """Read OpenAPI specs and markdown docs."""
        specs = glob(config["input"] + "/**/*.yaml")
        docs = glob(config["input"] + "/**/*.md")
        return specs + docs

    def templates(self):
        return {
            "endpoint": "API endpoint {method} {path} — {description}",
            "parameter": "Parameter {name} ({type}) for {endpoint} — {description}",
            "error": "Error {code} from {endpoint} — {cause}",
        }

    def review_criteria(self):
        return [
            "Endpoint beliefs must specify HTTP method and path",
            "Parameter types must match the OpenAPI spec",
            "Error causes must reference observed behavior, not speculation",
        ]

Running your module

# If installed as a package
reasonsforge my-domain --input ./data --output reasons.db

# If running from source
python -m reasonsforge my-domain --input ./data --output reasons.db

Note

The module API shown here is aspirational. The actual interface will be defined during Phase 2 of the Reasons Forge implementation plan. The core concepts — scan, templates, review criteria — will be present, but method signatures may change.