Hierarchical Configuration

Project-aware JSON config discovery for the praisonai CLI — walk-up from subdirectories, stop at the git boundary

The praisonai CLI reads .praison.json from your project — and finds it automatically even when you run the CLI from a deep subdirectory.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
agent.start("Summarise the README")

The user runs the agent from any subdirectory; hierarchical config supplies merged settings.

Precedence

Quick Start

1. Drop .praison.json in your project root

   {
     "model": "gpt-4o-mini",
     "temperature": 0.3
   }

2. Use an agent from anywhere inside the repo

   from praisonaiagents import Agent
   
   agent = Agent(name="assistant", instructions="Be helpful.")
   agent.start("Summarise the README")

   The CLI discovers .praison.json automatically — no extra setup needed, even if you’re nested deep inside repo/src/deep/pkg/.

3. Verify what got merged

   from praisonai.cli.features.config_hierarchy import load_config
   
   print(load_config())

How Walk-up Works

• Starts at project_dir (defaults to os.getcwd()).
• At every level, checks .praison.json then praison.json (in that precedence order).
• Stops at a directory containing .git — config never leaks across project boundaries.
• When no .git is ever found, caps the walk at 10 ancestor levels to avoid accidentally picking up unrelated configs.
• Nearest config wins — the first hit is returned.

Choose Your Mode

Default walk-up (recommended):

from praisonai.cli.features.config_hierarchy import HierarchicalConfig

config = HierarchicalConfig()
settings = config.load()

Disable walk-up (cwd only):

config = HierarchicalConfig(walk_up=False)
settings = config.load()

Explicit starting directory:

config = HierarchicalConfig(project_dir="/path/to/project")
settings = config.load()

Walk-up Boundaries

The walk stops when it hits either:

• A directory containing .git (inclusive — the git-root itself is still checked for configs).
• 10 ancestor levels without finding any .git marker.

Configuration File Precedence

Configuration Schema

Top-level keys supported in .praison.json:

Example .praison.json:

{
  "model": "gpt-4o",
  "temperature": 0.7,
  "permissions": {
    "allowed_tools": ["read_file", "write_file"],
    "allowed_paths": ["./src", "./tests"]
  },
  "output": {
    "mode": "compact",
    "color": true
  }
}

Common Patterns

Monorepo with per-package overrides:

Place a root .praison.json with your default model, then add a packages/frontend/.praison.json for package-specific overrides:

// packages/frontend/.praison.json
{
  "model": "gpt-4o",
  "temperature": 0.1
}

Running praisonai run "..." from inside packages/frontend/ picks up the nearest config automatically.

Pin model and permissions for the whole repo:

A single .praison.json at the repo root applies to every subdirectory:

{
  "model": "gpt-4o-mini",
  "permissions": {
    "allowed_tools": ["read_file"],
    "allowed_paths": ["./src"]
  }
}

Test fixture isolation:

from praisonai.cli.features.config_hierarchy import HierarchicalConfig

def test_my_feature(tmp_path):
    config = HierarchicalConfig(project_dir=str(tmp_path), walk_up=False)
    settings = config.load()

Constructor Parameters

Best Practices

Related