Speks

Interactive Functional Analysis Generator — turn pseudo-code and Markdown specifications into a live, testable documentation website.

Why Speks?

Business rules live in code, but stakeholders read documentation. Speks bridges the gap:

• Write business rules as Python pseudo-code with built-in mocking for external services
• Document them in Markdown with special tags that embed live code, contracts, and diagrams
• Generate an interactive website where anyone can read, understand, and test every rule

No more stale specs. No more "the doc says X but the code does Y". Your documentation is the executable specification.

Quick Start

pip install pyspeks
speks init my-project
cd my-project
speks serve

Open http://localhost:8000 to see your interactive documentation.

What You Get

Write business rules as Python pseudo-code:

from speks import service, stub

@service
class CoreBanking:
    """Core Banking API (blackbox)."""

    @stub(mock=1500.0)
    def check_balance(self, client_id: str) -> float:
        ...  # real HTTP/SQL implementation here

def evaluate_credit(client_id: str, amount: float) -> bool:
    balance = CoreBanking().check_balance(client_id)
    return balance > amount

Then document them in Markdown with special tags:

## Credit Evaluation
@[contract](src/rules.py:evaluate_credit)
@[code](src/rules.py:evaluate_credit)
@[playground](src/rules.py:evaluate_credit)
@[sequence](src/rules.py:evaluate_credit)
@[dependencies](src/)
@[mermaid](diagrams/flow.mmd)
@[plantuml](diagrams/sequence.puml)

Speks generates a live website where stakeholders can read, understand, and test every business rule — with auto-generated dependency graphs and sequence diagrams.

Features

• Interactive Playground — Each documented function gets an auto-generated form to test it live in the browser
• Mocking Engine — External services are auto-mocked; users can override mock values and simulate errors
• Custom Markdown Tags — @[code], @[playground], @[contract], @[dependencies], @[sequence], @[mermaid], @[plantuml]
• Auto-generated Diagrams — Dependency graphs and sequence diagrams derived from your code via static analysis
• Test Case Management — Save, replay, and validate test scenarios directly from the documentation
• Standalone Binaries — Distribute as a single executable (Windows, macOS, Linux) — no Python required

Markdown Tags Reference

Project Layout

speks/               # The generator library & CLI
  core/              # Markdown parser, code extractor, dependency & sequence analysis
  engine/            # Mocking system (@service / @stub decorators, error overrides)
  web/               # Site builder, dev server (FastAPI)
  mkdocs_plugins/    # MkDocs plugins for each tag type
  i18n/              # Internationalization (en, fr)
  cli.py             # CLI entry point (init, serve)

User Workspace

After speks init, a workspace is created:

my-project/
  src/               # Python pseudo-code (business rules)
  docs/              # Markdown documentation
  diagrams/          # PlantUML diagrams
  testcases/         # Saved test scenarios (JSON)
  speks.toml         # Project configuration
  mkdocs.yml         # MkDocs configuration

Examples

See the examples/ directory for complete projects across different industries:

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache License 2.0 — see LICENSE for details.