ECC
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
- 309k
- JavaScript
- MIT
- 2 d ago
Declarative rule engine for conversational agents and interactive workflows
Repo phpro/agent-rules, read from GitHub 3 d ago. phpro has not joined Take My Repo.
phpro/agent-rules is a public repo on GitHub by phpro. Declarative rule engine for conversational agents and interactive workflows. It declares the MIT license on GitHub. It is written mainly in PHP, has 5 stars and last changed on 2026-05-21. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-19.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
A declarative rule engine designed for conversational agents, AI assistants, and interactive workflows.
Perfect for building chatbots, AI agents, CLI wizards, or any system that guides users through multi-step processes by asking questions and validating responses.
Agent Rules provides a logical processing unit for handling unstructured input in a structured and interactive way. It enables you to define validation rules that can request missing information, enforce business logic, and provide intelligent feedback to users or AI agents.
Built to be compatible with Symfony AI Agent, this library integrates seamlessly with AI-powered tools and conversational interfaces.
Sequence (AND), Any (OR), and Either patternscomposer require phpro/agent-rules
The subject is the data being validated:
final class OrderRequest
{
public function __construct(
public readonly ?string $email,
public readonly ?string $productId,
public readonly ?int $quantity,
) {}
}
Each rule checks one aspect and can request missing information:
use Phpro\AgentRules\RuleInterface;
use Phpro\AgentRules\RuleEvaluation;
use Phpro\AgentRules\Result\IncompleteResult;
/**
* @implements RuleInterface<OrderRequest>
*/
class EmailRule implements RuleInterface
{
public function name(): string
{
return 'email_validation';
}
public function dependencies(): array
{
return []; // No dependencies
}
public function check(mixed $subject): RuleEvaluation
{
// Missing email? Ask for it!
if ($subject->email === null) {
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'email',
message: 'Please provide your email address to proceed.'
)
);
}
// Invalid format? Request correction!
if (!filter_var($subject->email, FILTER_VALIDATE_EMAIL)) {
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'email',
message: 'The email address is invalid. Please provide a valid email.'
)
);
}
// All good!
return RuleEvaluation::pass();
}
}
use Phpro\AgentRules\RuleEngine;
$engine = new RuleEngine(
new EmailRule(),
new ProductRule(),
new QuantityRule(),
);
$request = new OrderRequest(
email: null,
productId: 'PROD-123',
quantity: 2
);
$evaluation = $engine->evaluate($request);
if (!$evaluation->isPass()) {
$result = $evaluation->result;
echo $result->message; // "Please provide your email address to proceed."
echo $result->missingField; // "email"
}
The engine provides four result types to communicate different states:
| Result Type | Status | Use Case | Key Fields |
|---|---|---|---|
CompleteResult |
complete |
Validation passed | message |
IncompleteResult |
incomplete |
Missing/invalid data | missingField, message |
BlockedResult |
blocked |
Access denied | reason, message |
ErrorResult |
error |
Processing error | message, resolution |
return RuleEvaluation::respond(
new CompleteResult(
message: 'Order validated successfully!'
)
);
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'shippingAddress',
message: 'We need your shipping address to complete the order.'
)
);
return RuleEvaluation::respond(
new BlockedResult(
reason: 'Product out of stock',
message: 'This product is currently unavailable.'
)
);
return RuleEvaluation::respond(
new ErrorResult(
message: 'Unable to validate product availability.',
resolution: 'Please try again later or contact support.'
)
);
All rules must pass. First failure stops execution:
use Phpro\AgentRules\Sequence;
$allRequired = new Sequence(
new EmailRule(),
new ProductRule(),
new QuantityRule(),
);
At least one rule must pass:
use Phpro\AgentRules\Any;
$paymentMethod = new Any(
new CreditCardRule(),
new PayPalRule(),
new BankTransferRule(),
);
Try left, fall back to right:
use Phpro\AgentRules\Either;
$authentication = new Either(
new OAuthRule(),
new PasswordRule(),
);
Rules can declare dependencies to ensure proper execution order:
class DiscountRule implements RuleInterface
{
public function dependencies(): array
{
return ['product_validation', 'user_authentication'];
}
public function name(): string
{
return 'discount_calculation';
}
public function check(mixed $subject): RuleEvaluation
{
// This runs only after dependencies pass
// ...
}
}
The engine automatically:
You can attach contextual information to results that helps users or AI agents understand where to find more information:
use Phpro\AgentRules\Source\Source;
$result = new IncompleteResult(
missingField: 'productId',
message: 'Please provide the product ID.'
);
$result->sources()->add(
new Source(
name: 'Product Catalog',
reference: 'https://example.com/products',
content: 'Browse our product catalog to find product IDs.'
)
);
return RuleEvaluation::respond($result);
Sources are particularly useful for:
Configure the rule engine as a service:
# config/services.yaml
services:
OrderValidationEngine:
class: Phpro\AgentRules\RuleEngine
factory: ['Phpro\AgentRules\RuleEngine', 'fromIterable']
arguments:
- !tagged_iterator order.validation.rule
Tag your rules:
use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;
#[AutoconfigureTag('order.validation.rule', ['priority' => 100])]
class EmailRule implements RuleInterface
{
// ...
}
Imagine building a conversational AI that helps users complete a multi-step registration form. The AI needs to:
sequenceDiagram
participant User
participant AI Agent
participant Registration Tool
participant Rule Engine
participant Rules
User->>AI Agent: I want to create an account
AI Agent->>Registration Tool: validate_registration(context={})
Registration Tool->>Rule Engine: evaluate(request)
Rule Engine->>Rules: Check email rule
Rules-->>Rule Engine: IncompleteResult(missing: email)
Rule Engine-->>Registration Tool: First rule failed
Registration Tool-->>AI Agent: IncompleteResult
AI Agent->>User: What's your email address?
User->>AI Agent: john@example.com
AI Agent->>Registration Tool: validate_registration(email="john@example.com")
Registration Tool->>Rule Engine: evaluate(request)
Rule Engine->>Rules: Check email rule
Rules-->>Rule Engine: Pass ✓
Rule Engine->>Rules: Check password rule
Rules-->>Rule Engine: IncompleteResult(missing: password)
Rule Engine-->>Registration Tool: Second rule failed
Registration Tool-->>AI Agent: IncompleteResult
AI Agent->>User: Please create a password (min 8 chars)
User->>AI Agent: MySecurePass123
AI Agent->>Registration Tool: validate_registration(email="...", password="...")
Registration Tool->>Rule Engine: evaluate(request)
Rule Engine->>Rules: Check all rules
Rules-->>Rule Engine: All Pass ✓
Rule Engine-->>Registration Tool: RuleEvaluation::pass()
Registration Tool-->>AI Agent: CompleteResult
AI Agent->>User: Account created successfully!
use Symfony\AI\Platform\Contract\JsonSchema\Attribute\With;
final class RegistrationRequest
{
public function __construct(
public readonly ?string $email = null,
#[With(minLength: 10, maxLength: 255)]
#[\SensitiveParameter]
public readonly ?string $password = null,
public readonly ?string $fullName = null,
public readonly ?bool $termsAccepted = null,
) {}
}
#[AutoconfigureTag('registration.rule', ['priority' => 100])]
class EmailRule implements RuleInterface
{
public function name(): string { return 'email'; }
public function dependencies(): array { return []; }
public function check(mixed $subject): RuleEvaluation
{
if (!$subject->email) {
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'email',
message: "What's your email address?"
)
);
}
if (!filter_var($subject->email, FILTER_VALIDATE_EMAIL)) {
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'email',
message: 'Please provide a valid email address.'
)
);
}
return RuleEvaluation::pass();
}
}
#[AutoconfigureTag('registration.rule', ['priority' => 90])]
class PasswordRule implements RuleInterface
{
public function name(): string { return 'password'; }
public function dependencies(): array { return ['email']; }
public function check(mixed $subject): RuleEvaluation
{
if (!$subject->password) {
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'password',
message: 'Please create a password (minimum 8 characters).'
)
);
}
if (strlen($subject->password) < 8) {
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'password',
message: 'Password must be at least 8 characters long.'
)
);
}
return RuleEvaluation::pass();
}
}
This is an example of linking the rule engine to a Symfony AI agent tool:
#[AsTool(
name: 'validate_registration',
description: 'Validates user registration data and requests missing information.'
)]
final class RegistrationTool implements HasSourcesInterface
{
use HasSourcesTrait;
public function __construct(
#[Autowire(service: 'RegistrationEngine')]
private RuleEngine $ruleEngine,
) {}
public function __invoke(
RegistrationRequest $request,
): ResultInterface {
$evaluation = $this->ruleEngine->evaluate($request);
$result = $evaluation->result ?? new CompleteResult(
message: 'Registration validated! Your account has been created.'
);
foreach ($result->sources() as $source) {
$this->addSource(new \Symfony\AI\Agent\Toolbox\Source\Source(
name: $source->name,
reference: $source->reference,
content: $source->content
));
}
return $result;
}
}
With following agent configuration:
ai:
agent:
registration_assistant:
platform: 'ai.platform.openai'
model: 'gpt-4'
prompt: |
You help users create accounts by collecting required information.
WORKFLOW:
1. Call validate_registration with any info you have
2. Tool returns what's missing → ask the user
3. Call validate_registration again with ALL collected data
4. Repeat until you get "complete" status
NEVER make up information. Always call the tool to know what to ask next.
tools:
- { service: 'RegistrationTool' }
User: I want to sign up
AI: [Calls validate_registration()]
What's your email address?
User: john@example.com
AI: [Calls validate_registration(email="john@example.com")]
Please create a password (minimum 8 characters).
User: MyPass
AI: [Calls validate_registration(email="...", password="MyPass")]
Password must be at least 8 characters long.
User: MySecurePassword123
AI: [Calls validate_registration(email="...", password="MySecurePassword123")]
What's your full name?
User: John Doe
AI: [Calls validate_registration(email="...", password="...", fullName="John Doe")]
Registration validated! Your account has been created.
Guide users through complex forms by requesting one piece of information at a time based on validation rules.
Validate customer requests interactively, asking clarifying questions when information is missing or invalid.
Build interactive command-line tools that guide users through setup by validating configuration step-by-step.
Validate API requests from AI agents, providing structured feedback on missing or invalid parameters.
Check documents for completeness, requesting missing sections or data from users or automated systems.
class ConditionalShippingRule implements RuleInterface
{
public function check(mixed $subject): RuleEvaluation
{
// Only check shipping if physical product
if ($subject->productType !== 'physical') {
return RuleEvaluation::pass();
}
if (!$subject->shippingAddress) {
return RuleEvaluation::respond(
new IncompleteResult(
missingField: 'shippingAddress',
message: 'Physical products require a shipping address.'
)
);
}
return RuleEvaluation::pass();
}
}
$checkoutValidation = new Sequence(
new UserAuthenticationRule(),
new Any(
new GuestCheckoutRule(),
new AccountRequiredRule(),
),
new Either(
new ExpressCheckoutRule(),
new Sequence(
new ShippingRule(),
new PaymentRule(),
new BillingRule(),
),
),
);
class InventoryRule implements RuleInterface
{
public function __construct(
private ProductRepository $products,
) {}
public function check(mixed $subject): RuleEvaluation
{
$product = $this->products->find($subject->productId);
if (!$product || $product->stock < $subject->quantity) {
return RuleEvaluation::respond(
new BlockedResult(
reason: 'Insufficient inventory',
message: 'This product is out of stock.'
)
);
}
// You could even save products based on the subject input.
return RuleEvaluation::pass();
}
}
use PHPUnit\Framework\TestCase;
class EmailRuleTest extends TestCase
{
public function test_it_requests_missing_email(): void
{
$rule = new EmailRule();
$request = new OrderRequest(email: null, productId: 'P1', quantity: 1);
$evaluation = $rule->check($request);
$this->assertFalse($evaluation->isPass());
$this->assertInstanceOf(IncompleteResult::class, $evaluation->result);
$this->assertEquals('email', $evaluation->result->missingField);
}
public function test_it_validates_email_format(): void
{
$rule = new EmailRule();
$request = new OrderRequest(email: 'invalid-email', productId: 'P1', quantity: 1);
$evaluation = $rule->check($request);
$this->assertFalse($evaluation->isPass());
$this->assertStringContainsString('valid email', $evaluation->result->message);
}
public function test_it_passes_with_valid_email(): void
{
$rule = new EmailRule();
$request = new OrderRequest(email: 'john@example.com', productId: 'P1', quantity: 1);
$evaluation = $rule->check($request);
$this->assertTrue($evaluation->isPass());
}
}
readonly and final for predictable behavior@template annotationsRuleInterface<T>
↑
├── RuleEngine (orchestrator)
├── Sequence (AND composite)
├── Any (OR composite)
├── Either (binary composite)
└── [Your custom rules]
RuleEvaluation
├── result: null (pass)
└── result: ResultInterface (fail)
ResultInterface
├── CompleteResult
├── IncompleteResult
├── BlockedResult
└── ErrorResult
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License. See LICENSE file for details.
phpro/agent-rules is a public repo on GitHub by phpro. Declarative rule engine for conversational agents and interactive workflows.
It declares the MIT license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-05-21. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Reverse engineer anything with agents, from app behavior down to native binaries.
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
Knowledge infrastructure to make your agents smarter. Search, scrape and access 550+ data providers through one API.

This repository provides easy way to install GrumPHP without the risk of conflicting dependencies.
