fractal package

Subpackages

• fractal.cli package
  • Subpackages
    • fractal.cli.cmd package
      • Submodules
      • fractal.cli.cmd.channel module
      • fractal.cli.cmd.config module
      • fractal.cli.cmd.cost module
      • fractal.cli.cmd.db module
      • fractal.cli.cmd.event module
      • fractal.cli.cmd.fractal module
      • fractal.cli.cmd.node module
      • fractal.cli.cmd.plan module
      • fractal.cli.cmd.radio module
      • fractal.cli.cmd.time module
      • Module contents
  • Submodules
  • fractal.cli.main module
    • cli()
  • fractal.cli.utils module
    • command()
    • require_non_negative()
    • parse_reserve_budget()
    • StreamRenderer
      • StreamRenderer.close()
    • print_rows()
    • print_json()
    • init_node()
    • resolve_init_target()
    • resolve_node()
    • resolve_user_node()
    • resolve_target()
    • resolve_ledger_target()
  • Module contents
• fractal.core package
  • Submodules
  • fractal.core.agent module
    • command_base()
    • resolve()
    • register()
    • supported()
    • Invocation
      • Invocation.agent
      • Invocation.argv
      • Invocation.cwd
      • Invocation.env
      • Invocation.session
    • StreamEvent
      • StreamEvent.kind
      • StreamEvent.text
      • StreamEvent.tool
      • StreamEvent.session
      • StreamEvent.model
      • StreamEvent.cost
      • StreamEvent.final
      • StreamEvent.duration
      • StreamEvent.turns
      • StreamEvent.budget_stopped
      • StreamEvent.failed
      • StreamEvent.message
    • StreamResult
      • StreamResult.session
      • StreamResult.model
      • StreamResult.cost
      • StreamResult.budget_stopped
    • StreamParser
      • StreamParser.session
      • StreamParser.cost
      • StreamParser.final
      • StreamParser.budget_stopped
      • StreamParser.errors
      • StreamParser.feed()
    • Agent
      • Agent.name
      • Agent.config_file
      • Agent.can_fork
      • Agent.mints_session
      • Agent.needs_pricing
      • Agent.cost_scope
      • Agent.enforces_budget
      • Agent.results_per_step
      • Agent.providers
      • Agent.parts
      • Agent.config_dir
      • Agent.err_path
      • Agent.provider
      • Agent.logger
      • Agent.log()
      • Agent.invocation()
      • Agent.spawn()
      • Agent.parser()
      • Agent.stream()
      • Agent.record_session()
      • Agent.record_cost()
      • Agent.tracks_cost()
      • Agent.config_model()
      • Agent.transcript()
      • Agent.preflight()
      • Agent.seed()
      • Agent.on_call()
      • Agent.on_call_success()
      • Agent.on_call_failure()
      • Agent.on_spawn()
      • Agent.on_action()
      • Agent.on_session()
      • Agent.on_record_session()
      • Agent.on_record_cost()
      • Agent.on_budget()
      • Agent.on_error()
      • Agent.on_preflight()
    • seed_agents()
    • AgentCallEvent
      • AgentCallEvent.session
      • AgentCallEvent.model
    • AgentCallSuccessEvent
    • AgentCallFailureEvent
    • AgentSpawnEvent
      • AgentSpawnEvent.invocation
    • AgentActionEvent
      • AgentActionEvent.tool
    • AgentSessionEvent
      • AgentSessionEvent.session
      • AgentSessionEvent.model
    • AgentCostEvent
      • AgentCostEvent.cost
      • AgentCostEvent.final
    • AgentBudgetEvent
    • AgentErrorEvent
      • AgentErrorEvent.error
    • AgentPreflightEvent
  • fractal.core.commit module
    • commit()
    • commit_user_init()
  • fractal.core.config module
    • Config
      • Config.node
      • Config.path
      • Config.load()
      • Config.get()
      • Config.set()
      • Config.validate()
      • Config.reconcile()
  • fractal.core.cost module
    • Cost
      • Cost.node
      • Cost.db
      • Cost.remaining()
      • Cost.spent()
      • Cost.untracked()
      • Cost.unpriced()
      • Cost.breakdown()
      • Cost.rows()
    • run_spend()
    • subtree_spent()
  • fractal.core.db module
    • Database
      • Database.path
      • Database.init()
      • Database.checkpoint()
      • Database.connect()
      • Database.transaction()
      • Database.read()
      • Database.write()
      • Database.update()
      • Database.merge()
      • Database.delete()
      • Database.exists()
      • Database.count()
  • fractal.core.event module
    • Event
      • Event.info
      • Event.name
      • Event.description
    • InitialEvent
    • TerminalEvent
      • TerminalEvent.initial_event
    • FailureEvent
      • FailureEvent.error
  • fractal.core.files module
    • Files
      • Files.node
      • Files.db
      • Files.worktree
      • Files.list()
      • Files.read()
      • Files.path()
      • Files.write()
      • Files.commit()
      • Files.archive()
      • Files.history()
  • fractal.core.loop module
    • Step
      • Step.load()
      • Step.name
      • Step.requires_approval
      • Step.agent
      • Step.provider
      • Step.model
      • Step.effort
      • Step.timeout
      • Step.detached_raw
    • StepResult
      • StepResult.status
      • StepResult.exit_code
      • StepResult.reason
      • StepResult.session
      • StepResult.cost
      • StepResult.budget_stopped
    • Loop
      • Loop.logger
      • Loop.log()
      • Loop.run()
      • Loop.on_iteration()
      • Loop.on_iteration_success()
      • Loop.on_iteration_failure()
      • Loop.on_step()
      • Loop.on_step_success()
      • Loop.on_step_failure()
    • LoopIterationEvent
      • LoopIterationEvent.iteration
      • LoopIterationEvent.run_id
      • LoopIterationEvent.iter_id
    • LoopIterationSuccessEvent
      • LoopIterationSuccessEvent.outcome
    • LoopIterationFailureEvent
    • LoopStepEvent
      • LoopStepEvent.step
    • LoopStepSuccessEvent
      • LoopStepSuccessEvent.result
    • LoopStepFailureEvent
      • LoopStepFailureEvent.result
  • fractal.core.node module
    • Node
      • Node.is_user
      • Node.db
      • Node.radio
      • Node.config
      • Node.cost
      • Node.files
      • Node.plans
      • Node.record
      • Node.sessions
      • Node.time
      • Node.logger
      • Node.log()
      • Node.branch
      • Node.worktree
      • Node.repo_dir
      • Node.node_dir
      • Node.project_path
      • Node.parent
      • Node.tmux_session
      • Node.resolve_caller()
      • Node.resolve_user()
      • Node.exists()
      • Node.init()
      • Node.start()
      • Node.attach()
      • Node.finish()
      • Node.finish_cancel()
      • Node.stop()
      • Node.kill()
      • Node.pause()
      • Node.resume()
      • Node.pause_latched()
      • Node.merge()
      • Node.delete()
      • Node.deregister()
      • Node.reconcile()
      • Node.retire()
      • Node.unretire()
      • Node.destroy()
      • Node.reset()
      • Node.status()
      • Node.status_display()
      • Node.status_set()
      • Node.title_set()
      • Node.list()
      • Node.child_add()
      • Node.child_update()
      • Node.child_retune()
      • Node.child_list()
      • Node.child_approve()
      • Node.child_pending()
      • Node.commit()
      • Node.agent()
      • Node.chat()
      • Node.chat_command()
      • Node.render_template()
      • Node.build_prompt()
      • Node.agent_effective()
      • Node.provider_effective()
    • node_dir()
    • tmux_session_name()
  • fractal.core.plan module
    • Plans
      • Plans.node
      • Plans.init()
      • Plans.list()
  • fractal.core.pricing module
    • update()
    • has_model()
    • rates()
  • fractal.core.radio module
    • Radio
      • Radio.node
      • Radio.db
      • Radio.init()
      • Radio.send()
      • Radio.unsend()
      • Radio.messages()
      • Radio.sent()
      • Radio.feed()
      • Radio.read()
      • Radio.thread()
      • Radio.reply()
      • Radio.react()
      • Radio.save()
      • Radio.unsave()
      • Radio.saved()
      • Radio.channel()
      • Radio.channel_delete()
      • Radio.channels()
      • Radio.subscribe()
      • Radio.unsubscribe()
      • Radio.subs()
  • fractal.core.record module
    • Record
      • Record.node
      • Record.db
      • Record.resolve_context()
      • Record.close_open()
      • Record.run_start()
      • Record.run_end()
      • Record.run_open()
      • Record.run_latest()
      • Record.run_branches()
      • Record.iter_start()
      • Record.iter_end()
      • Record.step_start()
      • Record.step_cost()
      • Record.step_session()
      • Record.step_end()
      • Record.step_pending()
      • Record.step_approve()
      • Record.step_approved()
      • Record.event_start()
      • Record.event_end()
      • Record.signal_get()
      • Record.signal_set()
      • Record.signal_clear()
      • Record.runs()
      • Record.iters()
      • Record.steps()
      • Record.events()
      • Record.signals()
      • Record.activity()
  • fractal.core.render module
    • render()
    • variables()
    • prompt()
    • chat_seed()
    • strip_frontmatter()
  • fractal.core.session module
    • Sessions
      • Sessions.node
      • Sessions.get()
      • Sessions.set()
      • Sessions.clear()
      • Sessions.transcript()
  • fractal.core.time module
    • Time
      • Time.node
      • Time.db
      • Time.remaining()
      • Time.limit()
  • fractal.core.worktree module
    • lock()
    • validate_name()
    • derive_project_name()
    • ensure_git_repo()
    • project_path()
    • set_project_path()
    • exclude_update()
    • exclude_tracks()
    • exclude_strip()
    • ensure_project_wiki()
    • verify_hook_formatters()
    • run_script()
    • cleanup_failed_worktree()
    • prune_branch()
  • Module contents
• fractal.impl package
  • Submodules
  • fractal.impl.claude module
    • ClaudeParser
      • ClaudeParser.feed()
    • ClaudeAgent
      • ClaudeAgent.name
      • ClaudeAgent.config_file
      • ClaudeAgent.can_fork
      • ClaudeAgent.mints_session
      • ClaudeAgent.needs_pricing
      • ClaudeAgent.cost_scope
      • ClaudeAgent.enforces_budget
      • ClaudeAgent.providers
      • ClaudeAgent.parser()
      • ClaudeAgent.tracks_cost()
  • fractal.impl.codex module
    • CodexParser
      • CodexParser.feed()
    • CodexAgent
      • CodexAgent.name
      • CodexAgent.config_file
      • CodexAgent.can_fork
      • CodexAgent.mints_session
      • CodexAgent.needs_pricing
      • CodexAgent.cost_scope
      • CodexAgent.enforces_budget
      • CodexAgent.providers
  • fractal.impl.grok module
    • GrokParser
      • GrokParser.feed()
    • GrokAgent
      • GrokAgent.name
      • GrokAgent.config_file
      • GrokAgent.can_fork
      • GrokAgent.mints_session
      • GrokAgent.needs_pricing
      • GrokAgent.cost_scope
      • GrokAgent.enforces_budget
      • GrokAgent.providers
  • fractal.impl.omp module
    • OmpParser
      • OmpParser.feed()
    • OmpAgent
      • OmpAgent.name
      • OmpAgent.config_file
      • OmpAgent.can_fork
      • OmpAgent.mints_session
      • OmpAgent.needs_pricing
      • OmpAgent.cost_scope
      • OmpAgent.enforces_budget
      • OmpAgent.providers
  • fractal.impl.opencode module
    • OpencodeParser
      • OpencodeParser.feed()
    • OpencodeAgent
      • OpencodeAgent.name
      • OpencodeAgent.config_file
      • OpencodeAgent.can_fork
      • OpencodeAgent.mints_session
      • OpencodeAgent.needs_pricing
      • OpencodeAgent.cost_scope
      • OpencodeAgent.enforces_budget
      • OpencodeAgent.results_per_step
      • OpencodeAgent.providers
  • Module contents
• fractal.util package
  • Submodules
  • fractal.util.duration module
    • parse_duration_seconds()
    • format_age()
  • fractal.util.filesystem module
    • write_atomic()
  • fractal.util.git module
    • run()
    • run_bytes()
    • toplevel()
    • common_dir()
    • branch()
    • worktree_map()
    • find_worktree()
    • prunable()
  • fractal.util.system module
    • bin_dir()
    • console_script()
    • prepend_bin_path()
  • fractal.util.time module
    • utc_now()
    • elapsed()
  • fractal.util.title module
    • name_to_title()
  • fractal.util.tmux module
    • probe()
    • sessions()
  • Module contents

Submodules

fractal.constants module

Constants for fractal.

fractal.constants.FRACTAL_FOLDER = '.fractal'

fractal data directory at the repo root

fractal.constants.WORKTREES_FOLDER = '.worktrees'

directory holding the per-node git worktrees

fractal.constants.PROJECT_FOLDER = '.project'

immutable project-layout cache under the worktrees directory

fractal.constants.CONFIG_FILE = 'config.json'

per-node configuration file in the node’s data directory

fractal.constants.DB_FILE = '.db'

central SQLite database file in the root node’s data directory

fractal.constants.LOCK_FILE = '.lock'

lock filename, standalone or as a suffix, serializing concurrent access

fractal.constants.PAUSE_ABORT_FILE = '.pause_abort'

marker signaling the running loop to abort into a pause

fractal.constants.PAUSED_FILE = '.paused'

tree-wide pause marker beside the central database

fractal.constants.PGID_FILE = '.pgid'

process group id of the running loop

fractal.constants.SESSION_FILE = '.session'

agent session records for the node

fractal.constants.SOCKET_FILE = '.socket'

tmux server socket path of the session running the loop

fractal.constants.STATUS_FILE = '.status'

the node’s current lifecycle status

fractal.constants.STEP_PGID_FILE = '.step_pgid'

process group id of the running step

fractal.constants.STATUSES = ('active', 'paused', 'idle', 'completed', 'stopped', 'exited', 'killed', 'failed', 'retired')

lifecycle status set shared by the node status file and the record rows

fractal.constants.EVENTS = ('init', 'spawn', 'commit', 'approve', 'merge', 'delete', 'orphan', 'start', 'finish', 'finish_cancel', 'stop', 'kill', 'pause', 'resume', 'retire', 'unretire')

point-in-time event kinds recorded on the node record

fractal.constants.PRIORITY_MIN = 0

lowest radio message priority

fractal.constants.PRIORITY_MAX = 10

highest radio message priority

fractal.exceptions module

Exceptions for fractal.

exception fractal.exceptions.AbstractMethodError(class_or_instance, /, methodtype='method')

Bases: NotImplementedError

Subclass of NotImplementedError for abstract methods.

To be used when not using the abc module. (adapted from pandas.errors).

Parameters:

• self (AbstractMethodError)

• class_or_instance (type | object)

• methodtype (str)

Initialize AbstractMethodError, validating methodtype.

Parameters:

• self (AbstractMethodError)

• class_or_instance (type | object)

• methodtype (str)

exception fractal.exceptions.AgentStreamError

Bases: RuntimeError

Raised when an agent reports a failure on its own JSON stream.

Distinct from a fractal-side stream-consumer failure: the agent drained cleanly (exit 0) but its events named an error, so the loop books the step as an agent error, not a stream error.

fractal.typing module

Type hints for fractal.

fractal.typing.PathLike = str | os.PathLike

filesystem path accepted at boundaries

fractal.typing.Row

database row (a sqlite3.Row surfaced as a plain dict)

alias of dict[str, Any]

Module contents

The fractal package.

Hierarchical agent loops with recursive self-organization.