Interactive Functional Analysis Generator — turn pseudo-code and Markdown specifications into a live, testable documentation website.
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.
pip install pyspeks
speks init my-project
cd my-project
speks serveOpen http://localhost:8000 to see your interactive documentation.
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 > amountThen 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.
- 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
| Tag | Description |
|---|---|
@[code](src/file.py:func) |
Embed function source code with syntax highlighting |
@[playground](src/file.py:func) |
Interactive form to test the function live |
@[contract](src/file.py:func) |
Function signature as a readable table |
@[dependencies](src/) |
Auto-generated dependency graph (Mermaid) |
@[sequence](src/file.py:func) |
Auto-generated sequence diagram |
@[mermaid](diagrams/flow.mmd) |
Embed a Mermaid diagram from file |
@[plantuml](diagrams/file.puml) |
Embed a PlantUML diagram |
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)
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
See the examples/ directory for complete projects across different industries:
| Example | Domain | Demonstrates |
|---|---|---|
| Credit Evaluation | Banking | Core features, mocking, error handling, sequence diagrams |
| Order Processing | E-commerce | Multi-step workflows, pricing rules, inventory checks |
| Patient Eligibility | Healthcare | Compliance rules, multi-service orchestration |
| Shipping Calculator | Logistics | Decision trees, zone-based calculations |
See CONTRIBUTING.md for development setup and guidelines.
Apache License 2.0 — see LICENSE for details.