// Projects

What problem does this solve?

Backend systems often need to send notifications, alerts, or reports across multiple delivery channels that fail in different and unpredictable ways.

Typical issues include:

• One provider being temporarily unavailable
• Partial delivery across channels
• Silent failures without clear error signals

broadcastio acts as a single orchestration layer that attempts delivery across providers with explicit failure semantics.

What broadcastio is (and is not)

It is

• A Python orchestration layer for outbound messages
• A way to attempt delivery across one or more providers
• A library with ordered fallback and retry logic
• Designed for alerts, reports, and backend-triggered notifications

It is not

• A chatbot framework
• An inbound message handler
• A WhatsApp automation system by itself

Typical usage flow

1. Register one or more delivery providers
2. Define a message payload
3. Dispatch via the orchestrator
4. Inspect delivery result and failures explicitly

The caller always receives a deterministic result object — even when delivery fails.

Minimal example

from broadcastio.core.orchestrator import Orchestrator
from broadcastio.providers.whatsapp import WhatsAppProvider
from broadcastio.core.message import Message

wa = WhatsAppProvider("http://localhost:3000")
orch = Orchestrator([wa])

result = orch.send(
    Message(
        recipient="6281234567890",
        content="Service is down"
    )
)

print(result.success)

Failure-aware by design

broadcastio distinguishes clearly between:

• Exceptions → configuration or programmer errors
• Delivery results → delivery was attempted but failed

if not result.success:
    print(result.error.code, result.error.message)

This makes failures observable and actionable instead of silent.

When should you use this?

broadcastio is well-suited for:

• Infrastructure alerts
• Scheduled backend reports
• Operational notifications
• Systems that require defensive delivery guarantees

It is intentionally not optimized for conversational flows.

Providers & architecture note

Providers (WhatsApp, Email, etc.) are implemented as adapters.

For example:

• WhatsApp delivery relies on an external Node.js service based on WhatsApp Web
• This service is not bundled with the Python package

The provider layer is intentionally swappable.

Project status

• Status: Alpha
• APIs may evolve before 1.0.0
• Core orchestration logic is tested and stable

Source code and full documentation are available in the case study.

What problem does this solve?

Many applications need map features such as place search or directions, but implementing this logic usually involves:

• complex query parsing
• multiple map APIs
• vendor lock-in and billing requirements

directio allows applications to accept natural-language map requests and turn them into structured, map-ready results without relying on paid or hosted services.

What directio is (and is not)

It is

• A backend API for natural-language place search and routing
• A bridge between user intent and deterministic map execution
• Designed to be consumed by web or mobile applications

It is not

• A frontend map library
• A general-purpose chatbot
• A hosted LLM or map service

Typical usage flow

1. A user sends a natural-language query
2. A local LLM extracts intent and parameters
3. Backend providers execute geocoding or routing
4. The API returns clean JSON for rendering on a map

The LLM is used only for intent extraction. All external calls are handled by deterministic backend logic.

Minimal example

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: directio_xxxxxxxxxxxxx" \
  -d '{"message":"Where can I eat ramen near Sudirman Jakarta?"}'

Example response:

{
  "intent": "find_places",
  "summary": "Ramen places near Sudirman Jakarta",
  "places": [
    {
      "name": "Ramen 38",
      "lat": -6.2275566,
      "lon": 106.809542
    }
  ]
}

Why local LLMs?

directio uses a local LLM (via Ollama) to:

• avoid sending user data to third-party APIs
• keep behavior predictable and inspectable
• ensure the system is fully runnable offline

The LLM never calls map services directly.

When should you use this?

directio is suitable for:

• map-based applications
• location-aware dashboards
• prototypes and demos without billing setup
• systems that value transparency over black-box APIs

It is not intended for high-traffic or latency-sensitive production use.

Project status

directio is under active development, focusing on:

• stable intent extraction
• place search and routing
• clean API contracts
• safe usage limits

Read the full case study for architecture details and trade-offs.