Implementation of the adachsoft/agent-rule-contract library. This package provides JSON-based implementations of RuleReaderInterface and RuleWriterInterface for managing agent rules in the AdachSoft AI ecosystem.

Features

JSON Rule Reader: Read rules from a single JSON file using the stable contracts (Rule, RuleId, RuleCollection).
JSON Rule Writer: Write-side implementation of RuleWriterInterface for a single JSON file.
Public API Builder (read-side): Simple entry point to construct a JSON-based rule reader.
Public API Builder (write-side): Builder to create a JSON-based rule writer.

Requirements

PHP ^8.3
adachsoft/agent-rule-contract ^0.4.0

Installation

composer require adachsoft/agent-rule

JSON format

The JSON file is expected to contain an array of rule definitions. Each rule is represented as an object with the following fields:

id (string) stable identifier of the rule (must match RuleId constraints: lowercase letters, digits and underscores, at least 3 characters),
type (string) one of: requirement, prohibition, guideline, constraint,
projectId (int|null) null for global rules, positive integer for project rules,
target (string) one of: agent, tool, code, output,
content (string) human- or machine-readable rule content (at least 10 characters),
priority (int) optional priority used by consumers to order or select rules (default 0),
createdAt (string) creation datetime in DateTimeImmutable::ATOM format,
updatedAt (string) last update datetime in DateTimeImmutable::ATOM format,
metadata (object|null) optional key-value object with additional data.

Usage

Read-side (RuleReaderInterface)

Use the JsonRuleRegistryBuilder to create a reader instance implementing RuleReaderInterface:

use AdachSoft\AgentRule\PublicApi\Builder\JsonRuleRegistryBuilder;
use AdachSoft\AgentRuleContract\ValueObject\RuleId;

$builder = new JsonRuleRegistryBuilder();
$reader = $builder->fromSinglePath('/path/to/rules.json');

// Get all rules (global and project-specific) across all projects
$allRules = $reader->getAll();

// Get only global rules
$globalRules = $reader->getAllByProject(null);

// Get global + project rules for project 1
$projectRules = $reader->getAllByProject(1);

// Get a single rule by id
$rule = $reader->getRuleById(new RuleId('example_rule'));

Write-side (RuleWriterInterface)

Use the JsonRuleWriterBuilder to create a writer instance implementing RuleWriterInterface:

use AdachSoft\AgentRule\PublicApi\Builder\JsonRuleWriterBuilder;
use AdachSoft\AgentRuleContract\Enum\RuleTargetEnum;
use AdachSoft\AgentRuleContract\Enum\RuleTypeEnum;
use AdachSoft\AgentRuleContract\ValueObject\Rule;
use AdachSoft\AgentRuleContract\ValueObject\RuleId;

$builder = new JsonRuleWriterBuilder();
$writer = $builder->fromSinglePath('/path/to/rules.json');

$now = new \DateTimeImmutable();

$rule = new Rule(
    new RuleId('example_rule'),
    RuleTypeEnum::REQUIREMENT,
    null, // global rule
    RuleTargetEnum::AGENT,
    'Example rule content',
    10,
    $now,
    $now,
    null,
);

$writer->create($rule);

// Later you can update, delete or check existence of rules.
// When the underlying JSON file is corrupted or unreadable,
// the writer (including exists()) will throw RuleException
// to signal a storage-level problem.