Metadata-Version: 2.4
Name: modulith
Version: 0.1.1
Author-email: Panuthep Tasawong <panutheptasawong@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/modulith-labs/modulith
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: requests
Requires-Dist: pydantic
Requires-Dist: keyring
Requires-Dist: typer
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: tqdm; extra == "dev"
Dynamic: license-file

# Modulith  
> Build once. Scale everywhere. Share effortlessly.

**Modulith** is a framework for building systems as **composable, shareable modules**.

Start simple.  
Structure as modules.  
Scale by distributing them, without rewriting your code.

## 🚀 What You Get

- 🧱 **Scalable by design** — move from local → distributed seamlessly  
- 🔗 **Composable architecture** — build systems by combining modules  
- 🌐 **Shareable modules** — publish and reuse across projects  
- 🔌 **Unified interface** — local and remote calls look identical  
- 🔐 **Built-in access control** — safely expose your modules  

## 📦 Install
```bash
pip install modulith
```

## 🚀 Quick Start
Everything runs locally. No network. No infra.
```python
# calculator.py
from modulith import Modulith

module = Modulith("calculator")

@module.capability("add")
def add(a: float, b: float) -> float:
    return a + b

result = module("add", kwargs={"a": 1, "b": 2})
# → 3
```
- Fast
- No latency
- Easy to debug

## 🌐 Share
Turn any module into a **shareable, remote module** in seconds.

```bash
# Serve the module on your machine
modulith serve calculator.module \ 
--public \                  # Accessible by anyone
--rate-limit 100 \          # 100 requests per minute (public users)
--burst-limit 20            # Allow short bursts up to 20 requests
```

```
🔑 Your authentication token: ...

🌐 Module 'calculator' is live:
- Repository: user3bef3/calculator
- Public URL: https://6ebm5g.instatunnel.my
- Local URL: http://localhost:8000

⚙️ Capabilities:
- add(a: float, b: float) → float

⚡ Public access limits:
- Rate limit: 100 requests/minute
- Burst limit: 20 requests

🛑 Press Ctrl+C to stop
```

## 🔌 Use Anywhere
Connect to your module from any environment:

```python
calculator = Modulith.remote(
    "user3bef3/calculator", 
    access_token="..."
)

result = calculator("add", kwargs={"a": 1, "b": 2})
# → 3 (executed remotely)
```
> Same interface. Local or remote, no difference.

## ⚖️ Effortless Scaling
Scale horizontally by running multiple instances of the same module.

```bash
# On another machine
modulith serve calculator.module \ 
--public \                      
--rate-limit 100 \              
--burst-limit 20 \
--auth-token ...            # Use the same token above to join the same module pool
```
#### What happens automatically:
- Instances join the same module pool
- Requests are load-balanced across instances
- If one instance goes down, others continue serving requests

## 🔗 Compose Modules
Build new modules by calling existing modules, local or remote.
```python
new_module = Modulith()
calculator = Modulith.remote("user3bef3/calculator", access_token="...")

@new_module.capability("double_sum")
def double_sum(a: float, b: float) -> float:
    return calculator("add", kwargs={"a": a, "b": b}) + calculator("add", kwargs={"a": a, "b": b})  # calls remote calculator module

result = new_module("double_sum", kwargs={"a": 1, "b": 2})
#  → 6
```
Execution flow
```
inputs → double_sum(1, 2)
       → add(1, 2)   (remote)
       → 3           (return)
       → add(1, 2)   (remote)
       → 3           (cache hit, return)
       → 3 + 3       (local)
       → 6
```

## ⚡ Design Philosophy
```
function → capability → module → composition → system
```
- Functions become capabilities
- Capabilities form modules
- Modules compose into systems

## 👤 Optional: Create Account
Avoid manual owner token management by linking modules to your account.

```bash
modulith signup # Create an account (if you don't have one)
modulith login
modulith serve calculator.module
```

```
🌐 Module 'calculator' is live:
- Repository: <your_username>/calculator
...
```
> Your module is now automatically registered and managed under your account.
