Metadata-Version: 2.4
Name: pyspeks
Version: 0.1.1
Summary: Interactive Functional Analysis Generator
Author: Speks Team
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: markdown>=3.5
Requires-Dist: tomli>=2.0; python_version < "3.12"
Requires-Dist: uvicorn>=0.24
Requires-Dist: fastapi>=0.104
Requires-Dist: watchfiles>=0.21
Requires-Dist: mkdocs>=1.5
Requires-Dist: mkdocs<2.0
Requires-Dist: mkdocs-material>=9.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: mypy>=1.7; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == "build"
Dynamic: license-file

<p align="center">
  <img src="logo.svg" alt="Speks logo" width="200">
</p>

# Speks

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

[![PyPI](https://img.shields.io/pypi/v/pyspeks.svg)](https://pypi.org/project/pyspeks/)
[![CI](https://github.com/Angeall/speks/actions/workflows/ci.yml/badge.svg)](https://github.com/Angeall/speks/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](LICENSE)
[![Website](https://img.shields.io/badge/Website-Speks-orange)](https://speks.cloud)

## 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

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

Open [http://localhost:8000](http://localhost:8000) to see your interactive documentation.

## What You Get

Write business rules as Python pseudo-code:

```python
from speks import ExternalService, MockResponse

class CheckClientBalance(ExternalService):
    def execute(self, client_id: str) -> float:
        pass  # real HTTP call in production

    def mock(self, client_id: str) -> MockResponse:
        return MockResponse(data=1500.0)

def evaluate_credit(client_id: str, amount: float) -> bool:
    balance = CheckClientBalance().call(client_id)
    return balance > amount
```

Then document them in Markdown with special tags:

```markdown
## 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

| 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 |

## Project Layout

```
speks/               # The generator library & CLI
  core/              # Markdown parser, code extractor, dependency & sequence analysis
  engine/            # Mocking system, external service base classes
  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/`](examples/) directory for complete projects across different industries:

| Example | Domain | Demonstrates |
|---------|--------|-------------|
| [Credit Evaluation](examples/credit-evaluation/) | Banking | Core features, mocking, error handling, sequence diagrams |
| [Order Processing](examples/order-processing/) | E-commerce | Multi-step workflows, pricing rules, inventory checks |
| [Patient Eligibility](examples/patient-eligibility/) | Healthcare | Compliance rules, multi-service orchestration |
| [Shipping Calculator](examples/shipping-calculator/) | Logistics | Decision trees, zone-based calculations |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.
