modulith 0.1.0

No project description provided

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

pip install modulith

🚀 Quick Start

Everything runs locally. No network. No infra.

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

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

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.

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

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.

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.