Référence API

grimoire.core

GrimoireConfig

grimoire.core.config.GrimoireConfig dataclass

Root Grimoire project configuration.

Immutable after construction. Unrecognised top-level keys are stored in extra so tools can access them without schema changes.

from_yaml(path) classmethod

Load config from a YAML file.

Raises :class:GrimoireConfigError if the file is missing, unreadable, or contains invalid YAML.

from_dict(data) classmethod

Build a :class:GrimoireConfig from a parsed YAML dict.

Raises :class:GrimoireConfigError on validation failures.

find_and_load(start=None) classmethod

Walk up the directory tree to find project-context.yaml.

Starts from start (default: cwd) and searches upward. Raises :class:GrimoireConfigError if no config file is found.

validate()

Return a list of config warnings (empty means valid).

Checks semantic consistency that goes beyond parse-time validation.

Sous-sections : project (ProjectConfig), user (UserConfig), memory (MemoryConfig), agents (AgentsConfig), installed_archetypes, extra

---

Sous-sections de config

ProjectConfig

grimoire.core.config.ProjectConfig dataclass

The project: section.

UserConfig

grimoire.core.config.UserConfig dataclass

The user: section.

MemoryConfig

grimoire.core.config.MemoryConfig dataclass

The memory: section.

AgentsConfig

grimoire.core.config.AgentsConfig dataclass

The agents: section.

---

GrimoireProject

grimoire.core.project.GrimoireProject

Entry point for interacting with a Grimoire project.

Parameters:

Name	Type	Description	Default
root	Path	Path to the project directory (must contain project-context.yaml).	required
strict	bool	If True (default), raise :class:GrimoireProjectError when the project is not properly initialised. Set to False for read-only inspection of partially-initialised projects.	True

root property

Project root directory.

grimoire_dir property

Path to _grimoire/.

config_path property

Path to project-context.yaml.

config property

Loaded and validated config.

Raises :class:GrimoireProjectError if the config is unavailable.

resolver property

Path / template resolver bound to this project.

is_initialized()

Check whether the project has a valid Grimoire installation.

agents()

List agents deployed in this project.

status()

Return a full status snapshot of this project.

context()

Build a context payload for agent consumption.

---

GrimoireError

Exception de base. Toutes les exceptions Grimoire en héritent.

from grimoire.core.exceptions import GrimoireError

try:
    cfg = GrimoireConfig.from_yaml(path)
except GrimoireError as e:
    print(e.error_code)  # ex: "GR001"

Exception	Code	Usage
GrimoireConfigError	GR001–GR003	Fichier config manquant, YAML invalide, section requise absente
GrimoireProjectError	—	Projet non initialisé ou structure invalide
GrimoireAgentError	GR101–GR103	Agent introuvable, archétype absent, registre en erreur
GrimoireToolError	GR401–GR402	Outil en échec ou introuvable
GrimoireMergeError	GR501–GR502	Erreur de fusion, conflit non résolu
GrimoireMemoryError	GR201–GR202	Backend mémoire en erreur ou inaccessible
GrimoireTimeoutError	GR301	Timeout réseau
GrimoireNetworkError	GR302–GR303	Erreur réseau ou MCP
GrimoireValidationError	GR501	Validation échouée

---

configure_logging

grimoire.core.log.configure_logging(level=None, *, fmt='text')

Set up the grimoire.* logger hierarchy.

Parameters:

Name	Type	Description	Default
level	str | None	Log level name (DEBUG, INFO, WARNING, ERROR). Falls back to :envvar:GRIMOIRE_LOG_LEVEL, then WARNING.	None
fmt	str	"text" (default) for human-readable output, "json" for structured JSON lines.	'text'

Variable d'environnement : GRIMOIRE_LOG_LEVEL (override le niveau par défaut WARNING).

---

Validation

grimoire.core.validator.validate_config(data, *, project_root=None)

Validate a parsed YAML dict against the Grimoire schema.

Returns a list of :class:ValidationError; empty list means valid.

grimoire.core.validator.ValidationError dataclass

A single validation problem.

---

@deprecated

grimoire.core.deprecation.deprecated(*, reason, version, alternative=None)

Mark a callable as deprecated.

Emits :class:DeprecationWarning on every call.

Parameters:

Name	Type	Description	Default
reason	str	Human-readable explanation of why the function is deprecated.	required
version	str	The version in which the deprecation was introduced.	required
alternative	str | None	Optional replacement function/method name.	None

Examples:

@deprecated(reason="Replaced by new_func", version="3.2.0",
            alternative="new_func")
def old_func() -> None: ...

---

@with_retry

grimoire.core.retry.with_retry(*, max_attempts=3, initial_delay=0.5, max_delay=30.0, backoff=2.0, jitter=True, retryable=(ConnectionError, TimeoutError, OSError))

Retry a callable with exponential backoff.

Parameters:

Name	Type	Description	Default
max_attempts	int	Total number of attempts (including the first call).	3
initial_delay	float	Delay in seconds before the first retry.	0.5
max_delay	float	Upper bound for the delay between retries.	30.0
backoff	float	Multiplier applied to the delay after each failure.	2.0
jitter	bool	Randomise the delay (±25 %) to avoid thundering-herd effects.	True
retryable	tuple[type[BaseException], ...]	Exception types that trigger a retry. All others propagate immediately.	(ConnectionError, TimeoutError, OSError)

Examples:

from grimoire.core.retry import with_retry

@with_retry(max_attempts=3, retryable=(ConnectionError,))
def fetch(url: str) -> bytes: ...

---

grimoire.registry

Plugin Discovery

Les packages tiers peuvent enregistrer des extensions via les entry points :

# pyproject.toml du plugin
[project.entry-points."grimoire.tools"]
my_tool = "my_package:MyTool"

[project.entry-points."grimoire.backends"]
my_backend = "my_package:MyBackend"

from grimoire.registry import discover_tools, discover_backends

tools = discover_tools()       # {"my_tool": MyTool, ...}
backends = discover_backends() # {"my_backend": MyBackend, ...}

---

grimoire.core.error_codes

Codes stables pour documentation et outillage.

Catégorie	Plage	Description
Configuration	GR001–GR003	Config introuvable, YAML invalide, section manquante
Agents / Registry	GR101–GR103	Agent/archétype introuvable, registre en erreur
Memory	GR201–GR202	Backend mémoire en erreur ou inaccessible
Network / MCP	GR301–GR303	Timeout, erreur réseau, MCP inaccessible
Tools	GR401–GR402	Outil en échec ou introuvable
Validation / Merge	GR501–GR502	Validation échouée, conflit de fusion

from grimoire.core.error_codes import CODES

for code, ec in CODES.items():
    print(f"{code}: {ec.summary}")