{"id":30046705,"url":"https://github.com/tokenlay/tokenlay-rules","last_synced_at":"2026-01-20T16:30:31.893Z","repository":{"id":306743502,"uuid":"1027094076","full_name":"tokenlay/tokenlay-rules","owner":"tokenlay","description":"Tokenlay Rules Engine","archived":false,"fork":false,"pushed_at":"2025-07-27T11:30:35.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-10T08:57:36.698Z","etag":null,"topics":["ai-infrastructure","api-gateway","json-rules","llm","npm-package","open-source","openai","policy-engine","rate-limiting","rules-engine","tokenlay","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@tokenlay/rules","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tokenlay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-27T09:53:08.000Z","updated_at":"2025-07-27T11:30:39.000Z","dependencies_parsed_at":"2025-07-27T11:36:30.286Z","dependency_job_id":"c699bbd2-76a5-4f6a-a3d3-3baf72fb7b83","html_url":"https://github.com/tokenlay/tokenlay-rules","commit_stats":null,"previous_names":["tokenlay/tokenlay-rules"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tokenlay/tokenlay-rules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenlay%2Ftokenlay-rules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenlay%2Ftokenlay-rules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenlay%2Ftokenlay-rules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenlay%2Ftokenlay-rules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tokenlay","download_url":"https://codeload.github.com/tokenlay/tokenlay-rules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokenlay%2Ftokenlay-rules/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607163,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-infrastructure","api-gateway","json-rules","llm","npm-package","open-source","openai","policy-engine","rate-limiting","rules-engine","tokenlay","typescript"],"created_at":"2025-08-07T08:53:28.776Z","updated_at":"2026-01-20T16:30:31.876Z","avatar_url":"https://github.com/tokenlay.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @tokenlay/rules\n\nA smart rule engine for AI usage routing and cost control logic. This TypeScript library allows you to define declarative rules that match request contexts and determine model routing, rate limiting, and cost enforcement policies.\n\n## Features\n\n- **Declarative Rules**: Define conditions and actions in a simple, readable format\n- **Smart Routing**: Route requests to different AI models based on user tier, usage, or custom criteria\n- **Cost Control**: Enforce usage limits by requests, tokens, cost, or concurrent connections\n- **Flexible Conditions**: Support for comparison operators, logical operators, and nested conditions\n- **Window-based Limits**: Track usage across different time windows (minute, hour, day, month, year)\n- **Graceful Degradation**: Downgrade to cheaper models when limits are exceeded\n- **Type Safety**: Full TypeScript support with Zod schema validation\n\n## Installation\n\n```bash\nnpm install @tokenlay/rules\n```\n\n## Quick Start\n\n```typescript\nimport { evaluateRules, type Rule, type EvaluationContext } from '@tokenlay/rules';\n\n// Define your rules\nconst rules: Rule[] = [\n  {\n    id: 'free-tier',\n    if: { tier: 'free' },\n    then: {\n      model: 'gpt-3.5-turbo',\n      limits: [{\n        type: 'requests',\n        max: 100,\n        window: 'day',\n        per: 'user'\n      }]\n    },\n    priority: 1\n  },\n  {\n    id: 'pro-tier',\n    if: { tier: 'pro' },\n    then: {\n      model: 'gpt-4',\n      limits: [{\n        type: 'cost',\n        max: 50,\n        window: 'month',\n        per: 'user'\n      }],\n      on_limit_exceeded: {\n        action: 'downgrade',\n        downgrade_to: 'gpt-3.5-turbo'\n      }\n    },\n    priority: 2\n  }\n];\n\n// Evaluate against context\nconst context: EvaluationContext = {\n  tier: 'pro',\n  user: 'user123',\n  usage: {\n    requests: 50,\n    tokens: 10000,\n    cost: 45,\n    concurrent: 2\n  },\n  windows: {}\n};\n\nconst result = evaluateRules(rules, context);\nconsole.log(result);\n// { matched: true, rule_id: 'pro-tier', action: 'allow', model: 'gpt-4', ... }\n```\n\n## Rule Structure\n\n### Conditions (`if`)\n\nSupport various matching patterns:\n\n```typescript\n// Simple equality\n{ tier: 'free' }\n\n// Comparison operators\n{ 'usage.cost': { gte: 50 } }\n{ requests: { lt: 100 } }\n{ feature: { in: ['chat', 'completion'] } }\n\n// Logical operators\n{\n  and: [\n    { tier: 'enterprise' },\n    { 'usage.cost': { lt: 1000 } }\n  ]\n}\n\n{\n  or: [\n    { admin: true },\n    { tier: { in: ['pro', 'enterprise'] } }\n  ]\n}\n\n// Negation\n{ not: { blocked: true } }\n```\n\n### Comparison Operators\n\n- `gt`, `gte`, `lt`, `lte`: Numeric comparisons\n- `eq`, `neq`: Equality checks\n- `in`, `nin`: Array membership\n- `contains`, `startsWith`, `endsWith`: String operations\n\n### Actions (`then`)\n\nDefine what happens when a rule matches:\n\n```typescript\n{\n  model: 'gpt-4',                    // Model to use\n  model_params: { temperature: 0.7 }, // Model parameters\n  action: 'allow',                    // allow | block | warn | queue\n  limits: [{                          // Usage limits\n    type: 'tokens',\n    max: 100000,\n    window: 'day',\n    per: 'user'\n  }],\n  on_limit_exceeded: {                // What to do when limit hit\n    action: 'downgrade',\n    downgrade_to: 'gpt-3.5-turbo',\n    error_message: 'Daily token limit exceeded'\n  }\n}\n```\n\n### Limit Types\n\n- `requests`: Number of API requests\n- `tokens`: Token consumption\n- `cost`: Monetary cost\n- `concurrent`: Concurrent connections\n\n### Window Types\n\n- `minute`, `hour`, `day`, `month`, `year`, `total`\n\n## Advanced Usage\n\n### Custom Tracking Keys\n\nGroup usage by custom fields:\n\n```typescript\n{\n  limits: [{\n    type: 'cost',\n    max: 100,\n    window: 'month',\n    per: 'project',\n    tracking_key: 'project_id'  // Use context.project_id for grouping\n  }]\n}\n```\n\n### Priority Resolution\n\nRules are evaluated by priority (higher first), then by order:\n\n```typescript\nconst rules: Rule[] = [\n  { if: { tier: 'free' }, then: { model: 'gpt-3.5' }, priority: 1 },\n  { if: { tier: 'free', vip: true }, then: { model: 'gpt-4' }, priority: 10 }\n];\n// VIP free users get GPT-4\n```\n\n### Window-based Usage Tracking\n\nTrack usage across time windows:\n\n```typescript\nconst context: EvaluationContext = {\n  usage: { requests: 50, tokens: 10000, cost: 5, concurrent: 1 },\n  windows: {\n    'requests_hour_user_123': {\n      current: 45,\n      limit: 50,\n      resets_at: '2025-07-27T15:00:00Z'\n    }\n  },\n  // ... other fields\n};\n```\n\n## API Reference\n\n### `evaluateRules(rules: Rule[], context: EvaluationContext): EvaluationResult`\n\nMain evaluation function that processes rules against context.\n\n### Types\n\n```typescript\ninterface Rule {\n  id?: string;\n  description?: string;\n  priority?: number;\n  if: Condition;\n  then: Action;\n}\n\ninterface EvaluationContext {\n  usage: {\n    requests: number;\n    tokens: number;\n    cost: number;\n    concurrent: number;\n  };\n  windows: Record\u003cstring, WindowData\u003e;\n  [key: string]: any; // Custom fields\n}\n\ninterface EvaluationResult {\n  matched: boolean;\n  rule_id?: string;\n  action: 'allow' | 'block' | 'warn' | 'queue';\n  model?: string;\n  limit_exceeded?: boolean;\n  error_code?: string;\n  error_message?: string;\n  // ... other fields\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Type check\nnpm run typecheck\n```\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenlay%2Ftokenlay-rules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftokenlay%2Ftokenlay-rules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokenlay%2Ftokenlay-rules/lists"}