Open source · v0.8.1

Build agentic AI systems that organize themselves.

Turn focused Python functions into a dynamic ecosystem of agents. They discover, communicate, remember, and scale through Praval's message-driven Reef.

Start building Explore the architecture
pip install praval
  • Python 3.9+
  • MIT licensed
Py reef_system.py
ready
@agent("researcher",
  responds_to=["query"])
def research(spore):
  findings = chat(spore.knowledge)
  broadcast({
    "type": "analysis",
    "data": findings})
R Researcherlistens: query
REEF spore bus
A Analystlistens: analysis
W Writerlistens: report
Live trace deterministic preview
  1. reef system ready
  2. query waiting for input

Illustration only. This deterministic browser preview does not execute Praval agents, Python, or LLM calls.

01Decorator firstFunctions become agents
02Knowledge drivenSpores carry structured context
03ComposableAdd specialists without rewiring
04Production shapedTrace, secure, distribute

01 Architecture narrative

From one function to a dynamic system.

Praval keeps the unit of work small while letting the system around it become sophisticated.

01

The function

Start with the smallest useful specialist.

Write focused Python with the libraries you already use. No class hierarchy, workflow DSL, or graph definition is required.

def research(spore): ...
02

The identity

Give the function an agent boundary.

The decorator adds identity, message subscriptions, tools, memory, and optional human approval without burying the business logic.

@agent("researcher", responds_to=["query"])
03

The Reef

Let knowledge route the collaboration.

Agents broadcast typed spores and respond to what matters to them. Pipelines, request-response, fan-out, and emergent coordination share one communication model.

broadcast({"type": "analysis", ...})
04

The production envelope

Add operational depth without changing the idea.

Attach layered memory, tools, flexible storage, OpenTelemetry traces, secure transports, and distributed infrastructure as the Reef grows.

HITLOTelAMQPQdrant

02 Capability system

Small API. Deep runtime.

Four connected layers take Praval from a decorator to a distributed agent platform.

Developer surface

Python remains the language of the system.

Agents, tools, storage, and approval boundaries stay declarative and close to the code they affect.

  • @agent identity and subscriptions
  • @tool reusable external capabilities
  • Human-in-the-loop approve, reject, and resume

Reef runtime

Choreography when you want it. Coordination when you need it.

Spores provide one knowledge-first model for local threads, multi-process systems, and external brokers.

asyncresiliencebackpressure

Memory + storage

Give every specialist the right kind of recall.

Combine working context, episodic history, semantic knowledge, and durable backends through one interface.

PostgreSQLRedisS3Qdrant

Production envelope

Observe, secure, and distribute the same agent system.

Trace agent lifecycles with OpenTelemetry, encrypt spores end to end, and move the Reef onto production transports without rewriting agent logic.

OpenTelemetryPyNaClTLSDocker
Explore every capability in the docs

03 Simplicity, demonstrated

489 lines become 50 lines.

The framework absorbs coordination machinery so your application can express specialists and the knowledge they exchange.

Traditional control plane
representative responsibilities
01Agent lifecycle managerstart · stop · retry
02Routing and subscriptionsqueues · filters
03Provider plumbingclients · models
04Memory coordinationcontext · retrieval
05Failure and completiontimeouts · cleanup
coordination mixed with intent489 LOC
specialist_system.py
application intent 
@agent("researcher", responds_to=["query"])
def research(spore):
    result = chat(f"Research: {spore.knowledge}")
    broadcast({"type": "analysis", "data": result})

@agent("analyst", responds_to=["analysis"])
def analyse(spore):
    return chat(f"Find insights: {spore.knowledge}")

start_agents(research, analyse, initial_data=query)
intent stays visible50 LOC

The 489 → 50 comparison comes from the framework's published reference system. Inspect the source and context

04 Built with Praval

A local research workspace shaped by agents.

Praval Deep Research brings discovery, grounded chat, paper reading, and a knowledge graph into one local-first desktop workspace powered by Praval agents.

9Praval agent roles
4research workspaces
1local data plane
100%local-first
  • Hybrid discovery searches arXiv and the indexed paper library.
  • Grounded chat keeps citations, source papers, and the Knowledge Graph in view.
  • Imports, reindexing, and graph rebuilds run as observable background jobs.
View the project Read the build story
Praval Deep Research / research chat local
Current Praval Deep Research workspace with Knowledge Graph, paper reader, and grounded chat panels

05 Learn by running

Four systems. Four layers of Praval.

Start with two specialists, then add memory, security, and adaptive coordination.

001

Core pattern

Specialist collaboration

Research, analysis, and writing connected by typed spores.

Open example 005

Persistent intelligence

Memory-enabled agents

Give specialists semantic recall across messages and sessions.

Open example 011

Distributed trust

Secure spores

Encrypt, sign, and authenticate knowledge between processes.

Open example 009

Adaptive systems

Emergent intelligence

Observe useful global behaviour emerge from local agent rules.

Open example

06 Quick start

Your first Reef is minutes away.

Choose the depth you need today. Every profile keeps the same agent API, so you can expand without a rewrite.

pip install praval

Core agents plus OpenAI, Anthropic, and Cohere providers.

Read the quickstart View on PyPI
first_reef.py 
from praval import agent, chat, broadcast, start_agents

@agent("researcher", responds_to=["query"])
def research(spore):
    result = chat(f"Research {spore.knowledge['topic']}")
    broadcast({"type": "finding", "data": result})

@agent("writer", responds_to=["finding"])
def write(spore):
    print(chat(f"Summarize {spore.knowledge['data']}"))

start_agents(research, write,
    initial_data={"type": "query", "topic": "agent systems"})
2 agents registered · Reef listening

07 Go deeper

The manual, the source, and the thinking.

Move from a first agent to production patterns with versioned references and real build notes.

DOCv0.8.1

Documentation

Guides, tutorials, examples, and the complete API reference.

Open the manual GITMIT

Source and discussions

Read the runtime, run examples, report issues, or help shape Praval.

Explore GitHub LOGField notes

Architecture journal

Benchmarks, distributed systems lessons, and project deep dives.

Read the journal

Created by Rajesh Sampathkumar

Inspired by corals. Engineered for complex adaptive systems.

Praval grew from two decades of data and AI engineering and a belief that capable systems can emerge from simple, well-defined collaborators.