modulith 0.1.2

No project description provided

Modulith

Build once. Use everywhere. Scale 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

Build and run locally. Fast, no latency, easy to debug.

# calculator/module.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

🌐 Use Anywhere

Serve your module on any machine and use it from anywhere.

# Serve the module with public access and rate limits
modulith run \
--module-source 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

Connect to your module from any machine:

calculator = Modulith.remote(
    "user3bef3/calculator",
    access_token="..."  # Use the same token displayed in the console when you ran the module
)
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 across machines. Each instance joins a shared pool and serves requests automatically.

# Serve the module on serverless instances (i.e., AWS Fargate)
modulith serve \
--module-source calculator.module \
--instances 5 \                 # Run 5 instances
--num-cores 2 \                 # Each instance uses 2 CPU cores
--memory 1GB \                  # Each instance has 1GB of RAM
--public \                      # Accessible by anyone
--rate-limit 100 \              # 100 requests per minute (public users)
--burst-limit 20 \              # Allow short bursts up to 20 requests
--auth-token <your-auth-token>  # Use the same token to group instances

Tip: Use the same --auth-token across all instances to group them into the same pool. Instances using different tokens will run different pools.

🔗 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

👤 Optional: Create Account

Avoid manual auth/access tokens management by linking modules to your account.

modulith signup # Create an account (if you don't have one)
modulith login

🌐 Module 'calculator' is live:
- Repository: <your_username>/calculator
...

Your module is now automatically registered and managed under your account.