arbiterx-gate 0.1.0__tar.gz

arbiterx_gate-0.1.0/.agents/rules.md

@@ -0,0 +1,69 @@
+# Agent Rules — ArbiterX
+
+## Project Overview
+
+ArbiterX is a CLI tool that generates token-efficient codebase maps for AI-assisted development. It parses source code via AST analysis, extracts structural information (functions, classes, imports, dependencies), and compresses it into a compact representation that fits within LLM context windows. The tool supports incremental updates via content hashing and task-aware context prioritization.
+
+## Tech Stack
+
+- **Language:** Python 3.11+
+- **CLI Framework:** Click
+- **AST Parsing:** tree-sitter (multi-language), ast (Python stdlib fallback)
+- **Hashing:** hashlib (SHA-256)
+- **Configuration:** tomllib / tomli
+- **AI Integration:** litellm (multi-provider)
+- **Testing:** pytest, pytest-cov
+- **Linting/Formatting:** ruff
+- **Packaging:** hatchling / pyproject.toml
+
+## Coding Conventions
+
+- **Python version:** 3.11+ minimum. Use modern syntax (match statements, `type` aliases, ExceptionGroups where appropriate).
+- **Type hints:** Required on all public functions and methods. Use `from __future__ import annotations` in every module.
+- **Line length:** 100 characters max.
+- **Formatter/Linter:** ruff (format + check). Configuration lives in `pyproject.toml`.
+- **Imports:** Group as stdlib → third-party → local. Use absolute imports.
+- **Docstrings:** Google style. Required on all public classes and functions.
+- **Naming:** snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE for constants.
+- **Error handling:** Use custom exception classes in `src/arbiterx/exceptions.py`. Never catch bare `Exception` in library code.
+- **No global mutable state.** Pass dependencies explicitly or use dependency injection.
+
+## Project Structure
+
+```
+src/arbiterx/
+├── __init__.py
+├── cli.py              # Click CLI entry points
+├── mapper.py           # Core map generation logic
+├── hasher.py           # File content hashing (SHA-256)
+├── classifier.py       # Task classification for relevance ranking
+├── parser/             # Language-specific AST parsers
+├── output/             # Formatters (markdown, json, prompt)
+├── config.py           # Configuration loading
+├── exceptions.py       # Custom exceptions
+└── models.py           # Data classes / types
+```
+
+## Testing Approach
+
+- **Framework:** pytest
+- **Structure:** `tests/unit/` for isolated logic, `tests/integration/` for CLI and end-to-end flows.
+- **Naming:** Test files mirror source: `src/arbiterx/hasher.py` → `tests/unit/test_hasher.py`
+- **Fixtures:** Use `conftest.py` for shared fixtures. Prefer `tmp_path` for filesystem tests.
+- **Coverage:** Aim for 80%+ on core modules (mapper, hasher, classifier, parser).
+- **Mocking:** Mock external I/O (filesystem, network, LLM calls). Never mock the unit under test.
+- **Run tests:** `pytest` from project root. CI runs against Python 3.11 and 3.12.
+
+## Key Decisions
+
+- Maps are deterministic — same input always produces same output (for caching).
+- The tool must work fully offline (no network calls during `map`).
+- Token counting uses tiktoken with cl100k_base encoding.
+- File hashing uses SHA-256 for cache invalidation.
+- Configuration is optional — sensible defaults work out of the box.
+
+## Common Tasks
+
+- **Add a new language parser:** Create a module in `src/arbiterx/parser/`, implement the `Parser` protocol, register in `parser/__init__.py`.
+- **Add a CLI command:** Add to `src/arbiterx/cli.py` using Click decorators.
+- **Update output format:** Modify or add a formatter in `src/arbiterx/output/`.

arbiterx_gate-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "arbiterx-marketplace",
+  "description": "ArbiterX — AI code quality middleware. Quality gate, smart routing, 97% token reduction.",
+  "owner": {
+    "name": "Neel Patel",
+    "url": "https://github.com/NeelPrime"
+  },
+  "plugins": [
+    {
+      "name": "arbiterx",
+      "source": ".",
+      "description": "Engineering discipline for AI code generation — enforces 10 rules for minimal, robust, unbreakable code. Includes quality gate, smart routing, and codebase mapping.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Neel Patel"
+      }
+    }
+  ]
+}

arbiterx_gate-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "arbiterx",
+  "version": "0.1.0",
+  "description": "Engineering discipline for AI code generation — enforces 10 rules for minimal, robust, unbreakable code with quality gate scoring.",
+  "author": {
+    "name": "Neel Patel",
+    "url": "https://github.com/NeelPrime"
+  },
+  "homepage": "https://github.com/NeelPrime/arbiterx",
+  "install": {
+    "command": "pip install arbiterx-gate",
+    "checkCommand": "arbiterx --version",
+    "instructions": "Requires Python 3.9+. Install with: pip install arbiterx-gate"
+  },
+  "setup": {
+    "command": "arbiterx init",
+    "description": "Initialize ArbiterX in the current project"
+  },
+  "skills": [
+    {
+      "name": "arbiterx",
+      "file": "skills/arbiterx.md",
+      "alwaysOn": true,
+      "description": "Engineering discipline rules — always active"
+    },
+    {
+      "name": "arbiterx-review",
+      "file": "skills/arbiterx-review.md",
+      "description": "Review code against engineering rules"
+    },
+    {
+      "name": "arbiterx-gate",
+      "file": "skills/arbiterx-gate.md",
+      "description": "Run quality gate on generated code"
+    }
+  ],
+  "hooks": "hooks/hooks.json"
+}

arbiterx_gate-0.1.0/.codex-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "arbiterx",
+  "version": "0.1.0",
+  "description": "Engineering discipline for AI code generation — 10 rules for minimal, robust code with quality gate scoring.",
+  "author": {
+    "name": "Neel Patel",
+    "url": "https://github.com/NeelPrime"
+  },
+  "homepage": "https://github.com/NeelPrime/arbiterx",
+  "install": {
+    "command": "pip install arbiterx-gate",
+    "checkCommand": "arbiterx --version"
+  },
+  "skills": [
+    {
+      "name": "arbiterx",
+      "file": "skills/arbiterx.md",
+      "alwaysOn": true,
+      "description": "Engineering discipline rules — always active"
+    },
+    {
+      "name": "arbiterx-review",
+      "file": "skills/arbiterx-review.md",
+      "description": "Review code against engineering rules"
+    },
+    {
+      "name": "arbiterx-gate",
+      "file": "skills/arbiterx-gate.md",
+      "description": "Run quality gate on generated code"
+    }
+  ],
+  "hooks": "hooks/hooks.json"
+}

arbiterx_gate-0.1.0/.cursor/rules/arbiterx.mdc

@@ -0,0 +1,31 @@
+---
+description: ArbiterX engineering discipline — enforces minimal, robust, unbreakable code
+globs: ["**/*.py", "**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.go", "**/*.rs", "**/*.java", "**/*.c", "**/*.cpp"]
+alwaysApply: true
+---
+
+# ArbiterX: Engineering Discipline
+
+Before writing code, check: Does this need to exist? Can stdlib do it? Is it already in the codebase? Can it be one line? Only then write the minimum that works.
+
+## ENFORCE on all generated code:
+
+1. Type all function signatures (params + return values)
+2. Handle every error — specific exceptions, never bare `except:`
+3. Use context managers for resources (`with open(...)`)
+4. Name all constants — no inline magic numbers
+5. One function = one job, max 30 lines
+6. Validate inputs at function entry
+7. No dead code — no commented code, no unused imports
+8. No TODO/FIXME — finish it or don't write it
+9. Prefer immutable data structures
+10. Every line must earn its place
+
+## NEVER generate:
+
+- Hardcoded API keys, passwords, or tokens
+- SQL with string formatting (use parameterized queries)
+- `eval()` or `exec()`
+- `subprocess` with `shell=True`
+- Network calls without timeouts
+- File operations without error handling

arbiterx_gate-0.1.0/.env.example

@@ -0,0 +1,14 @@
+# Cartograph - Environment Variables
+# Copy this file to .env and fill in your API keys.
+
+# Anthropic (Claude) - https://console.anthropic.com/
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# OpenAI (GPT-4o) - https://platform.openai.com/api-keys
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Google AI (Gemini) - https://aistudio.google.com/apikey
+GOOGLE_AI_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# OpenRouter (multi-model gateway) - https://openrouter.ai/keys
+OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

arbiterx_gate-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug Report
+about: Something isn't working
+title: '[Bug] '
+labels: bug
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- **Python version**: 
+- **OS**: 
+- **arbiterx version**: 
+
+## Additional Context
+
+Add any other context, logs, or screenshots about the problem here.

arbiterx_gate-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest a new feature
+title: '[Feature] '
+labels: enhancement
+---
+
+## Problem
+
+A clear description of the problem or limitation you're experiencing.
+
+## Proposed Solution
+
+Describe the solution you'd like to see implemented.
+
+## Alternatives Considered
+
+Any alternative solutions or features you've considered.
+
+## Additional Context
+
+Add any other context, mockups, or references here.

arbiterx_gate-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Description
+
+A brief summary of the changes in this PR.
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+
+## How Has This Been Tested?
+
+Describe the tests you ran to verify your changes.
+
+## Checklist
+
+- [ ] All tests pass (`pytest`)
+- [ ] Documentation has been updated (if applicable)
+- [ ] No TODOs left in the code

arbiterx_gate-0.1.0/.github/TOPICS.md

@@ -0,0 +1,24 @@
+# These topics appear on the GitHub repo page and are indexed by search engines.
+# Set them via: Settings → General → Topics
+# 
+# Recommended topics for ArbiterX:
+#   ai-code-quality
+#   ai-coding-assistant
+#   ai-middleware
+#   claude-code-plugin
+#   code-quality
+#   codex-plugin
+#   cursor-rules
+#   developer-tools
+#   engineering-discipline
+#   llm
+#   llm-optimization
+#   model-routing
+#   prompt-engineering
+#   smart-routing
+#   token-reduction
+#   tree-sitter
+#   yagni
+#   code-review
+#   static-analysis
+#   agent-skills

arbiterx_gate-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,27 @@
+# Engineering Rules (ArbiterX)
+
+All generated code must follow these rules:
+
+## Required
+- Type hints on all function parameters and return values
+- Error handling for all I/O operations (try/except or context managers)
+- Named constants instead of magic numbers
+- Input validation at function entry
+- Context managers for files and connections (`with open(...)`)
+- Functions under 30 lines
+
+## Forbidden
+- No hardcoded secrets or API keys
+- No bare except clauses
+- No string formatting in SQL queries (use parameterized)
+- No eval() or exec()
+- No TODO/FIXME comments — implement fully or skip
+- No functions longer than 30 lines
+- No unused imports or commented-out code
+
+## Prefer
+- Standard library over external dependencies
+- Early returns over deep nesting
+- Immutable data where possible
+- Specific exceptions over generic ones
+- `str.join()` over string concatenation in loops

arbiterx_gate-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Check formatting with ruff
+        run: ruff format --check .
+
+      - name: Run tests
+        run: pytest --tb=short

arbiterx_gate-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,40 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

arbiterx_gate-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/arbiterx-gate/
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

arbiterx_gate-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+*.pyc
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# ArbiterX map store
+.arbiterx/
+
+# Embeddings binary
+embeddings.bin
+
+# Environment variables
+.env
+
+# Type checking
+.mypy_cache/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Linting
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

arbiterx_gate-0.1.0/.kiro/steering/arbiterx.md

@@ -0,0 +1,16 @@
+# ArbiterX: Engineering Discipline
+
+Enforce these principles on all generated code:
+
+1. Use stdlib before dependencies. Does it need to exist? YAGNI.
+2. Type all function signatures — parameters and return values.
+3. Handle every error path. No bare `except:`. Catch specific exceptions.
+4. Close every resource. Use `with open(...)`, never bare open().
+5. Name constants. No magic numbers inline.
+6. One function = one responsibility. Max 30 lines.
+7. Validate inputs at function entry, not buried in logic.
+8. No dead code. No commented-out code. No unused imports.
+9. Never leave TODO/FIXME. Implement fully or skip entirely.
+10. Delete any line that doesn't change behavior.
+
+Never generate: hardcoded secrets, SQL with string formatting, eval/exec, subprocess shell=True, network calls without timeouts.

arbiterx_gate-0.1.0/.well-known/agent.json

@@ -0,0 +1,27 @@
+{
+  "name": "ArbiterX",
+  "description": "AI code quality middleware — 97% token reduction, smart model routing, quality gate scoring 0-100.",
+  "version": "0.1.0",
+  "author": "Neel Patel",
+  "homepage": "https://github.com/NeelPrime/arbiterx",
+  "install": "pip install arbiterx-gate",
+  "capabilities": [
+    "code-quality-gate",
+    "codebase-mapping",
+    "smart-model-routing",
+    "engineering-rule-enforcement"
+  ],
+  "supported_tools": [
+    "claude-code",
+    "codex-cli",
+    "cursor",
+    "github-copilot",
+    "aider",
+    "windsurf",
+    "kiro",
+    "zed",
+    "chatgpt"
+  ],
+  "rules_file": "AGENTS.md",
+  "llms_txt": "llms.txt"
+}

arbiterx_gate-0.1.0/.well-known/ai-plugin.json

@@ -0,0 +1,17 @@
+{
+  "schema_version": "v1",
+  "name_for_human": "ArbiterX",
+  "name_for_model": "arbiterx",
+  "description_for_human": "AI code quality middleware. 97% token reduction, smart model routing, quality gate scoring 0-100. Works with Claude Code, Codex, Cursor, Copilot, Aider.",
+  "description_for_model": "ArbiterX enforces engineering discipline on AI-generated code. It provides: (1) Codebase mapping that reduces context tokens by 97% using tree-sitter and PageRank, (2) Smart model routing that classifies task complexity and routes to optimal LLM, (3) Quality gate that scores code 0-100 checking security, robustness, efficiency, types, style, completeness. Install: pip install arbiterx-gate. Initialize: arbiterx init. Map: arbiterx map. Gate: arbiterx gate --file <file>.",
+  "auth": {
+    "type": "none"
+  },
+  "api": {
+    "type": "cli",
+    "install": "pip install arbiterx-gate"
+  },
+  "logo_url": "https://raw.githubusercontent.com/NeelPrime/arbiterx/main/assets/arbiterx-logo.svg",
+  "contact_email": "",
+  "legal_info_url": "https://github.com/NeelPrime/arbiterx/blob/main/LICENSE"
+}

arbiterx_gate-0.1.0/.windsurf/rules/arbiterx.md

@@ -0,0 +1,42 @@
+# ArbiterX: Engineering Discipline
+
+Before writing ANY code, follow this ladder:
+1. Does this need to exist? → If no, skip (YAGNI)
+2. Already in codebase? → Reuse, don't rewrite
+3. Stdlib does it? → Use stdlib
+4. One line? → Write one line, no abstraction
+
+## When Writing Code — ENFORCE:
+
+1. Type all function signatures — parameters and return values
+2. Handle every error — no bare `except:`, catch specific exceptions
+3. Close every resource — use `with open(...)`, never bare open()
+4. Name all constants — no magic numbers inline
+5. One function = one job — max 30 lines
+6. Validate inputs at function entry, not deep in logic
+7. No dead code — no commented-out code, no unused imports
+8. Never leave TODO/FIXME — implement fully or skip entirely
+9. Prefer immutable — frozen dataclasses, tuples
+10. Delete any line that doesn't change behavior
+
+## NEVER Generate:
+
+- Hardcoded secrets (API keys, passwords, tokens)
+- SQL with string formatting (use parameterized queries)
+- eval() or exec()
+- subprocess with shell=True
+- Network calls without timeouts
+- File operations without error handling
+
+## After Writing:
+
+- Can any line be deleted without breaking behavior? → Delete it
+- Is there a simpler stdlib approach? → Use it
+- Would this pass a senior engineer's review? → If not, fix it
+
+## Install ArbiterX for active quality gate:
+```
+pip install arbiterx-gate
+arbiterx init
+arbiterx gate --file <your_file>
+```

arbiterx_gate-0.1.0/.zed/assistant/rules.md

@@ -0,0 +1,34 @@
+# ArbiterX: Engineering Discipline
+
+Before writing ANY code, follow this ladder:
+1. Does this need to exist? → If no, skip (YAGNI)
+2. Already in codebase? → Reuse, don't rewrite
+3. Stdlib does it? → Use stdlib
+4. One line? → Write one line, no abstraction
+
+## When Writing Code — ENFORCE:
+
+1. Type all function signatures — parameters and return values
+2. Handle every error — no bare `except:`, catch specific exceptions
+3. Close every resource — use `with open(...)`, never bare open()
+4. Name all constants — no magic numbers inline
+5. One function = one job — max 30 lines
+6. Validate inputs at function entry, not deep in logic
+7. No dead code — no commented-out code, no unused imports
+8. Never leave TODO/FIXME — implement fully or skip entirely
+9. Prefer immutable — frozen dataclasses, tuples
+10. Delete any line that doesn't change behavior
+
+## NEVER Generate:
+
+- Hardcoded secrets (API keys, passwords, tokens)
+- SQL with string formatting (use parameterized queries)
+- eval() or exec()
+- subprocess with shell=True
+- Network calls without timeouts
+- File operations without error handling
+
+## Install ArbiterX for active quality gate:
+```
+pip install arbiterx-gate && arbiterx init
+```