Praval: Multi-Agent AI Framework

Praval is a Python framework for building decentralized agent systems that use provider-neutral model execution, structured tool orchestration, memory, storage, observability, and Reef/Spore communication.

The current documentation is organized around the APIs users should build on now. The legacy string-returning APIs still work, but new code should prefer the structured model runtime APIs where provider capabilities, streaming events, structured outputs, multimodal input, and local LLM behavior are explicit.

The model runtime is the execution boundary inside agents. It does not replace Praval’s collaboration architecture: specialized agents coordinate through Reef messages and structured Spore payloads. Applications may define their own message schemas when stronger domain contracts are required.

Install

pip install praval

# Optional feature groups
pip install praval[memory]
pip install praval[storage]
pip install praval[mcp]  # Python 3.10+
pip install praval[all]

Two Supported Entry Paths

Use Agent for direct provider-neutral model execution:

from praval import Agent

agent = Agent(
    "assistant",
    provider="openai",
    model="gpt-5.4-mini",
    config={"system_message": "Be concise."},
)

response = agent.generate(
    "Summarize why capability validation matters.",
    response_schema={
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
    },
)

print(response.content)

Use decorated agents, Reef, and Spores for message-driven collaboration:

from praval import agent, broadcast, get_reef, start_agents

@agent("researcher", provider="ollama", responds_to=["request"])
def researcher(spore):
    broadcast({"type": "finding", "text": spore.knowledge["topic"]})

@agent("editor", provider="ollama", responds_to=["finding"])
def editor(spore):
    print(spore.knowledge["text"])

start_agents(
    researcher,
    editor,
    initial_data={"type": "request", "topic": "agent systems"},
)
reef = get_reef()
reef.wait_for_completion(timeout=30)
reef.shutdown()

What To Read

User Guide

Tutorials

Architecture

Examples

API Reference

Project

Documentation Policy

Sphinx source under docs/sphinx is the canonical documentation surface. Generated HTML, generated API pages, and generated PDFs are build artifacts. Older long-form manuals live under docs/archive and should be treated as legacy background unless their content has been ported into the current Sphinx guide.