{"id":30656288,"url":"https://github.com/whaaaley/irf","last_synced_at":"2025-08-31T10:44:07.124Z","repository":{"id":308002289,"uuid":"1031309319","full_name":"whaaaley/irf","owner":"whaaaley","description":"A tool that converts unstructured instruction text into structured, parseable rules using AI, grounded in speech act theory and deontic logic.","archived":false,"fork":false,"pushed_at":"2025-08-03T14:42:52.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-03T16:06:21.254Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/whaaaley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-08-03T13:23:27.000Z","updated_at":"2025-08-03T14:42:55.000Z","dependencies_parsed_at":"2025-08-03T16:17:24.983Z","dependency_job_id":null,"html_url":"https://github.com/whaaaley/irf","commit_stats":null,"previous_names":["whaaaley/irf"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/whaaaley/irf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaaaley%2Firf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaaaley%2Firf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaaaley%2Firf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaaaley%2Firf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/whaaaley","download_url":"https://codeload.github.com/whaaaley/irf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/whaaaley%2Firf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272971423,"owners_count":25024094,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-08-31T10:44:06.463Z","updated_at":"2025-08-31T10:44:07.092Z","avatar_url":"https://github.com/whaaaley.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Instruction Rule Formatter (IRF)\n\nA tool that converts unstructured instruction text into structured, parseable rules using AI, grounded in speech act theory and deontic logic.\n\n## Disclaimer\n\nI'm not an NLP expert - I did some research to learn a bit more theory on NLP and stumbled onto speech act theory and deontic logic and thought it could be a good fit for instructions.\nI was annoyed trying to write consistent rules, thinking about phrasing and grammar, so I thought there might be a better way to approach this systematically.\nThis project is just me experimenting with these concepts to see if they can help structure and standardize instruction text.\nThe implementation may not perfectly align with academic definitions, but the goal is practical utility in organizing rule-based content.\n\n## Theoretical Foundation\n\nIRF is inspired by **[speech act theory](https://en.wikipedia.org/wiki/Speech_act)** and **[deontic logic](https://en.wikipedia.org/wiki/Deontic_logic)** to analyze and structure instructions:\n\n### Speech Act Theory\n\nInstructions contain **performative utterances** (statements that create rules) that don't just describe but actively create \"obligations\", \"permissions\", and \"prohibitions\".\nIRF identifies the **illocutionary force** (the intended action or effect) of each instruction by extracting:\n\n- **Action verbs** (use, avoid, ensure, require)\n- **Target objects** (what the action applies to)\n- **Contextual conditions** (when/where the rule applies)\n- **Justifications** (why the rule exists)\n\n### Deontic Logic\n\nIRF categorizes rules using **deontic strength** categories that express different types of rule relationships:\n\n- **Obligatory** - Required actions that create strong obligations\n- **Forbidden** - Prohibited actions with clear boundaries\n- **Permissible** - Allowed actions within acceptable bounds\n- **Optional** - Discretionary choices left to the actor\n- **Supererogatory** - Actions that exceed normal expectations\n- **Indifferent** - Actions with no normative preference\n- **Omissible** - Actions that can be reasonably omitted\n\nThis theoretical grounding enables IRF to find hidden rule structures in instructions and make them clear and consistent.\n\n## Overview\n\nIRF takes raw instruction files and processes them through a two-step AI pipeline:\n\n1. **Parse**: Converts raw text into structured rule components (strength, action, target, context, reason)\n2. **Format**: Converts structured rules back into clean, human-readable text\n\nThis process helps standardize instruction formats, reduce verbosity, and create machine-readable rule structures.\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n## Project Structure\n\n```\nsrc/\n├── schema.ts      # Zod schemas for rules and parsed data\n├── main.ts        # Core AI processing functions\n├── build.ts       # Batch processing script\n├── analyze.ts     # File size comparison tool\n└── env.ts         # Environment configuration\n\nfixtures/          # Input instruction files\ndist/              # Generated output files\n```\n\n## Installation\n\n1. Ensure you have Deno installed\n2. Set your OpenAI API key:\n   ```bash\n   export OPENAI_API_KEY=your_api_key_here\n   ```\n\n## Usage\n\n### Process All Files\n\nConvert all instruction files in the `fixtures/` directory:\n\n```bash\ndeno run --allow-read --allow-write --allow-env src/build.ts\n```\n\nThis generates three files for each input:\n- `.md` - Clean human-readable rules\n- `.parsed.json` - Structured rule components\n- `.rules.json` - Raw AI-generated rules\n\n### Analyze Results\n\nCompare original vs generated file sizes:\n\n```bash\ndeno run --allow-read src/analyze.ts\n```\n\nExample output:\n```\n📊 File Size Analysis: Fixtures vs Generated Markdown\n\nFile                     Original   Generated    Diff    Change\n─────────────────────────────────────────────────────────────────\ncopilot.instructions          1756        1158    598  🟢 −34.1%\naudit.instructions            1235         692    543  🟢 −44.0%\ngit.instructions              1880        1722    158  🟢 −8.4%\nold.instructions               937        1070   -133  🔴 +14.2%\nproject.instructions          1102        1221   -119  🔴 +10.8%\n─────────────────────────────────────────────────────────────────\nTOTAL                         6910        5863   1047  🟢 −15.2%\n\n📈 Summary: SAVED 1047 bytes (15.2%)\n```\n\n## Rule Schema\n\n### Parsed Rule Structure\n```typescript\ntype ParsedRule = {\n  strength: 'obligatory' | 'forbidden' | 'permissible' | 'optional' | 'supererogatory' | 'indifferent' | 'omissible'\n  action: string        // e.g., 'use', 'avoid', 'format'\n  target: string        // e.g., 'return await', 'type assertions'\n  context?: string      // e.g., 'when returning promises'\n  reason: string        // e.g., 'better stack traces'\n}\n```\n\n### Example Transformation\n\n**Input (raw text):**\n```\nAlways use return await when returning promises from async functions. This provides better stack traces and error handling.\n```\n\n**Parsed structure:**\n```json\n{\n  \"strength\": \"obligatory\",\n  \"action\": \"use\",\n  \"target\": \"return await\",\n  \"context\": \"when returning promises from async functions\",\n  \"reason\": \"better stack traces and error handling\"\n}\n```\n\n**Generated rule:**\n```\nUse return await when returning promises from async functions for better stack traces and error handling.\n```\n\n## API\n\n### `generateParsedRules(input: string)`\nConverts raw instruction text into structured parsed rules.\n\n### `generateRules(parsedRules: ParsedRule[])`\nConverts structured rules into human-readable text.\n\n## Performance\n\nThe tool typically achieves:\n- **15-45% size reduction** for verbose instruction files\n- **Consistent formatting** across all outputs\n- **Structured data** for programmatic processing\n\nFiles that are already well-structured may see slight increases (10-15%) as the AI adds connecting phrases for clarity.\n\n## Dependencies\n\n- **Deno**: Runtime environment\n- **Zod**: Schema validation\n- **llm-exe**: AI processing pipeline\n- **fast-glob**: File pattern matching\n\n## TODO\n\n- [ ] **CLI Tool** - Create a command-line interface for easier single-file processing\n- [ ] **MCP Tool** - Implement as a Model Context Protocol tool for integration with AI assistants\n- [ ] **Rule Merging** - Combine similar rules to reduce redundancy\n- [ ] **Combine Similar Rules** - Ability to combine similar rules into one rule\n- [ ] **Split Rules** - Ability to split a single rule up into multiple rules\n- [ ] **Confidence Scoring** - Add confidence scores to parsed rule components\n- [ ] **Deontic Ordering** - Sort rules by deontic strength (Obligatory → Forbidden → Permissible → Optional → Supererogatory → Indifferent → Omissible)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhaaaley%2Firf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhaaaley%2Firf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhaaaley%2Firf/lists"}