genesis-pantheon

The framework has five layers:

User / CLI
    |
Collective           -- top-level orchestrator; owns the Arena and Nexus
    |
Arena                -- message broker; routes Signals; runs all Personas concurrently per round
    |
Personas             -- autonomous agents with observe -> think -> act loop
    |
Directives           -- discrete LLM tasks; call Oracle to produce output
    |
Oracles              -- provider adapters (OpenAI, Anthropic, Gemini, Azure, Ollama, Human)

Shared state is held by the Nexus (a dependency-injection container): the Blueprint config, the Oracle instance (lazily created), and the BudgetLedger. Every persona and directive reads from the same Nexus.

Signal flow:

1. collective.launch_mission(text) publishes a UserDirective Signal to the Arena.
2. The Arena delivers each Signal to every Persona whose subscription set includes that signal's cause_by type.
3. Personas observe buffered Signals, choose a Directive to run, and publish a new Signal containing the Directive's output.
4. The loop continues round by round until all Personas are idle, the round limit is reached, or the budget cap is hit.

Built-in personas

CLI reference

genesispan [COMMAND] [OPTIONS]

launch

Run a software development mission.

genesispan launch MISSION [OPTIONS]

init-config

Create ~/.genesis_pantheon/blueprint.yaml with defaults. Does not overwrite an existing file.

genesispan init-config

list-oracles

Print available LLM provider types.

genesispan list-oracles

version

Print the installed framework version.

genesispan version

Library API

Collective

from genesis_pantheon import Collective, Nexus

ctx = Nexus()
collective = Collective(context=ctx)

Persona (base class)

from genesis_pantheon.personas.persona import Persona, PersonaReactMode

Directive (base class)

from genesis_pantheon.directives.base import Directive, DirectiveOutput

Signal

from genesis_pantheon import Signal

Nexus

from genesis_pantheon import Nexus

ctx = Nexus()
ctx.config.llm.model = "gpt-4o"
ctx.config.llm.api_key = "sk-..."
ctx.budget.max_budget = 10.0
oracle = ctx.oracle()   # lazily instantiated; cached

Custom persona example

from genesis_pantheon.personas.persona import Persona, PersonaReactMode
from genesis_pantheon.directives.base import Directive, DirectiveOutput

class SummarizeDirective(Directive):
    async def run(self, signal) -> DirectiveOutput:
        response = await self._ask(
            f"Summarize the following in one sentence:\n\n{signal.content}"
        )
        return DirectiveOutput(content=response)

class SummarizerPersona(Persona):
    name: str = "Summarizer"
    profile: str = "Expert summarizer"
    goal: str = "Produce concise summaries"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_actions([SummarizeDirective])
        self.subscribe_to(["UserDirective"])

Configuration

Run genesispan init-config to create ~/.genesis_pantheon/blueprint.yaml. Environment variables override YAML values.

LLM settings

llm:
  api_type: openai           # openai | azure | anthropic | gemini | ollama | human
  model: gpt-4o
  api_key: ""                # or set via env var (see below)
  base_url: ""               # required for azure and ollama
  temperature: 0.0           # 0.0 to 2.0
  max_tokens: 4096
  stream: true
  timeout: 300               # seconds
  max_retries: 3

Workspace settings

workspace:
  path: ~/.genesis_pantheon/workspace
  auto_archive: true         # clear signal history after run
  use_git: true              # init a git repo in the workspace
  project_name: ""           # subdirectory name

Per-persona oracle override

Assign a different LLM to a specific persona by name:

role_oracles:
  VisionDirector:
    api_type