{"id":38031194,"url":"https://github.com/namin/argir","last_synced_at":"2026-01-16T19:41:43.221Z","repository":{"id":314654731,"uuid":"1056241430","full_name":"namin/argir","owner":"namin","description":"natural language → argument graph → AF semantics → FOL (TPTP)","archived":false,"fork":false,"pushed_at":"2025-12-25T23:43:26.000Z","size":383,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-27T09:49:27.531Z","etag":null,"topics":["argument-debugger","debate","first-order-logic","llm","logic"],"latest_commit_sha":null,"homepage":"https://argir.metareflective.app/","language":"Python","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/namin.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-13T17:14:59.000Z","updated_at":"2025-12-25T23:43:28.000Z","dependencies_parsed_at":"2025-09-13T22:11:19.765Z","dependency_job_id":"a2026974-7791-4e65-8b07-6ca16a80351b","html_url":"https://github.com/namin/argir","commit_stats":null,"previous_names":["namin/argir"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/namin/argir","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namin%2Fargir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namin%2Fargir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namin%2Fargir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namin%2Fargir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namin","download_url":"https://codeload.github.com/namin/argir/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namin%2Fargir/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28481930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"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":["argument-debugger","debate","first-order-logic","llm","logic"],"created_at":"2026-01-16T19:41:42.442Z","updated_at":"2026-01-16T19:41:43.196Z","avatar_url":"https://github.com/namin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ARGIR — Unified Argument IR\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/namin/argir)\n\n\u003e A clean, strict, and analyzable pipeline from **natural language → argument graph → AF semantics → FOL (TPTP)**.\n\nA follow-up from [Argument Debugger](https://github.com/namin/argument-debugger), an LLM+ASP system for analyzing and repairing arguments.\n\nARGIR is a research system and IR that maps argument structure and offers minimal, verified repairs. It integrates AF semantics (clingo) and FOL proving (E‑prover) to (1) diagnose unsupported inferences, circularity, and unresolved contradictions; and (2) repair by (a) abducing missing premises that make conclusions provable and (b) editing AF attacks to restore acceptance—both checked post‑hoc. It comes with a web app, CLI, and documentation.\n\nThis README covers setup, CLI usage, LLM configuration, generated outputs, testing, and the core IR contract.\n\n---\n\n## 1) Install / Setup\n\nYou can run the package straight from source (no build needed).\n\n```bash\n# Core dependencies (Python 3.9+)\n\npip install \"pydantic\u003e=2.0\" google-genai clingo joblib networkx spacy\n\n# Download spaCy language model (required for lemmatization)\npython -m spacy download en_core_web_sm\n\n# System dependencies (optional):\n# - eprover: FOL theorem prover (install via package manager, e.g., apt/brew)\n\n# Note on dependencies:\n# - clingo: ASP solver for computing argumentation framework semantics\n# - joblib: Caching library for LLM responses (reduces API calls and costs)\n# - spacy: NLP library for systematic predicate lemmatization (replaces hardcoded maps)\n```\n\n---\n\n## 2) Configure the LLM\n\nARGIR uses **google-genai**. Choose **one** of the following:\n\n- **Gemini API key**:\n  ```bash\n  export GEMINI_API_KEY=your_key_here\n  ```\n\n- **Vertex AI** (Project + Location, uses your gcloud auth):\n  ```bash\n  export GOOGLE_CLOUD_PROJECT=your-project-id\n  export GOOGLE_CLOUD_LOCATION=us-central1  # or your region\n  ```\n\nOptional environment variables:\n- `LLM_MODEL` (default: `gemini-2.5-flash`)\n- `CACHE_LLM` (set to any value to enable joblib caching)\n- `LLM_CACHE_DIR` (default: `.cache/llm`)\n\n---\n\n## 3) Quickstart (CLI)\n\nFrom the project folder (where `argir/` lives):\n\n```bash\n# Check you’re running the right package version and path\npython -m argir.cli -V\n# → ARGIR v0.3.3 @ /path/to/argir/__init__.py\n\n# Run on the sample\npython -m argir.cli examples/sample.txt --out out\n\n# Optional: defeasible FOL (exceptions become negated conditions in antecedent)\npython -m argir.cli examples/sample.txt --out out --defeasible-fol\n\n# Optional: choose a specific goal to prove in FOL (by node id)\n# First run without --goal to see node IDs in report.md, then use one like:\npython -m argir.cli examples/sample.txt --out out --goal C1\n\n# Optional: use soft IR extraction with deterministic canonicalization\n# This is more robust than the default strict one-shot extraction\npython -m argir.cli examples/sample.txt --out out --soft\n\n# Optional: try multiple samples with soft extraction (picks best)\npython -m argir.cli examples/sample.txt --out out --soft --k-samples 3\n```\n\n**CLI Options**:\n- `--defeasible-fol` — Export FOL with exceptions as negated conditions\n- `--goal NODE_ID` — Force specific node as FOL conjecture\n- `--soft` — Use two-stage soft IR extraction (more robust)\n- `--k-samples N` — Try N soft IR samples, pick best (default: 1, only with --soft)\n- `--strict-fail` — Exit with error on validation issues (for CI/CD)\n\n**Outputs written to `--out`**:\n- `report.md` — human‑readable report (nodes, edges, findings, AF semantics, FOL)\n- `argir.json` — canonical ARGIR object (strictly validated)\n- `fof.p` — TPTP FOF axioms + (optional) conjecture\n- `draft.json` — raw LLM JSON (for debugging)\n- `fol_summary.json` — E‑prover summary (if `eprover` is installed)\n\nThe **AF Semantics** section in `report.md` shows accepted arguments under different semantics (grounded, preferred, stable) computed via clingo\n\n---\n\n## 4) Web Frontend\n\nFor a simpler, see `WEB_README.md`\n\nThe web frontend is publicly available at [argir.metareflective.app](https://argir.metareflective.app/).\nYou can replay [past saved queries](https://argir.metareflective.app/saved/).\nTo run your own new queries, you can bring your own Gemini API key. Anyone can [get a free-tier key](https://ai.google.dev/gemini-api/docs/api-key).\n\n---\n\n## 5) Tests\n\nRun `python tests/run.py --soft`. Do export `CACHE_LLM=true`.\n\n---\n\n## 6) Programmatic Usage\n\n```python\nfrom argir.pipeline import run_pipeline, run_pipeline_soft\n\ntext = \"If it rains, the streets get wet. It is raining. So, the streets will get wet.\"\n\n# Standard strict pipeline (one-shot extraction)\nres = run_pipeline(text, fol_mode=\"classical\", goal_id=None)\n\n# Soft pipeline (two-stage: soft IR → canonicalization → strict ARGIR)\nres = run_pipeline_soft(text, fol_mode=\"classical\", goal_id=None, k_samples=3)\n\nprint(res[\"report_md\"])   # markdown report\nprint(res[\"fof\"])         # list of TPTP lines\nprint(res[\"argir\"])       # canonical JSON-safe dict of the ARGIR\n```\n\n- `fol_mode`: `\"classical\"` or `\"defeasible\"`\n- `goal_id`: force the FOL conjecture to a specific node id\n- `k_samples`: (soft pipeline only) number of extraction attempts, picks best\n\n**Auto‑goal selection**: if there is exactly one **inference node** (has premises + conclusion) that isn't referenced by others, ARGIR emits `fof(goal, conjecture, …)` automatically. Otherwise, use `--goal`.\n\n---\n\n## 7) Soft Pipeline (Recommended)\n\nThe **soft pipeline** (`--soft` flag) is a more robust two-stage approach that addresses the brittleness of one-shot ARGIR generation:\n\n**Stage 1: Soft Extraction (LLM)**\n- LLM produces a permissive \"Soft IR\" format\n- No canonical predicates required\n- Simple predicate names allowed (e.g., \"raining\", \"streets_wet\")\n- Flexible node IDs and references\n\n**Stage 2: Canonicalization \u0026 Compilation (Deterministic)**\n- Automatically normalizes predicates (lowercase, underscores, strip articles)\n- Builds `atom_lexicon` from usage\n- Assigns stable node IDs (R1, C1, P1)\n- Validates and auto-repairs common issues\n- Produces strict ARGIR satisfying all contracts\n\n**Benefits**:\n- **Higher success rate** — LLM focuses on semantics, not syntax\n- **Deterministic canonicalization** — Consistent predicates across runs\n- **Best-of-k selection** — Try multiple samples, pick the one with fewest errors\n- **Graceful error handling** — Auto-repairs missing lexicon entries, dangling refs\n\n**When to use**:\n- Complex arguments with many predicates\n- When the standard pipeline fails with lexicon errors\n- Production systems requiring robustness\n- Experimenting with different LLM models\n\n---\n\n## 8) The ARGIR Contract (Strict Mode)\n\nARGIR is strict on atoms to make FOL sound and comparable.\n\n- The LLM **must** return a single JSON object with keys:\n  - `version`, `source_text`\n  - `graph: { nodes: InferenceStep[], edges: Edge[] }`\n  - `metadata.atom_lexicon`: **required** canonical predicates (keys) → example surface forms (values)\n\n- **Canonical atom enforcement**:\n  - Every `atoms[].pred` in nodes/rules **must** be a key in `metadata.atom_lexicon` (or legacy alias `metadata.symbols.predicates`).\n  - If missing or mismatched, the pipeline **errors** (no fallback).\n\n- **Structure**:\n  - Node = `{ id, premises[], rule?, conclusion?, span?, rationale? }`\n  - Premise = `Statement` or `Ref` (`{\"kind\":\"Ref\",\"ref\": \"nodeId\"}`)\n  - Rule = `{ name, strict, antecedents[], consequents[], exceptions[], ... }`\n  - Edge = `{ source, target, kind: \"support\"|\"attack\", attack_kind?, rationale? }`\n\n- **Reference‑aware coherence**:\n  - If a node’s premises include a `Ref` to a rule node, it’s treated as *rule‑backed* — no false “missing rule” finding.\n\n---\n\n## 9) AF \u0026 FOL\n\n- **AF projection**: every node is an argument; attack edges become `att(a,b)`; support is not encoded in APX (kept in the graph for coherence checks).\n\n- **AF Semantics computation**: ARGIR uses **clingo** (Answer Set Programming solver) to compute standard Dung semantics:\n  - **Grounded**: the minimal complete extension\n  - **Preferred**: maximal admissible sets\n  - **Stable**: extensions that attack all outside arguments\n  - Results appear in `report.md` under \"AF Semantics\" section with accepted arguments\n\n- **FOL lowering** (TPTP FOF):\n  - Always emits:\n    - **Rule axioms** for rule nodes (antecedents ⇒ consequents).\n    - **Premise‑only facts** and **conclusion‑only facts**.\n    - **Linkage axioms** for inference nodes: `(premises ⇒ conclusion)` where `Ref` to a rule collapses into that rule’s formula.\n  - **Defeasible mode** (`--defeasible-fol`): every exception in a rule becomes a **negated** condition conjoined to antecedents.\n\n- **Goal selection**:\n  - If exactly one inference node is unreferenced → auto `fof(goal, conjecture, …)`.\n  - Otherwise, supply `--goal NODE_ID` to force a conjecture.\n  - To find node IDs: run once without `--goal`, check `report.md` for node IDs (e.g., C1, R1, P1)\n  - The auto-selected goal (if any) appears in `metadata.goal_candidate_id` in `argir.json`\n\n---\n\n## 10) Troubleshooting\n\n- **`LLMNotConfigured`**  \n  Set either `GEMINI_API_KEY` or `GOOGLE_CLOUD_PROJECT` (+ `GOOGLE_CLOUD_LOCATION`).\n\n- **`metadata.atom_lexicon ... missing or empty`**  \n  The LLM must include canonical predicates. Tighten the prompt or run in fixtures mode to debug.\n\n- **`Atom predicates must be canonical ...`**  \n  An `atoms[].pred` is not a key in the lexicon. Normalize or update the lexicon.\n\n- **No `fof(goal, ...)` emitted**  \n  Multiple candidate conclusions. Use `--goal NODE_ID`.\n\n- **E‑prover \"not found\"**\n  Install eprover (optional). The rest of the pipeline still works.\n\n- **Version/path confusion**\n  Use `python -m argir.cli -V` to see the active package path and version.\n\n---\n\n## 11) Architecture\n\n```\ntext\n └─▶ (soft) LLM  ──► Soft IR (IDs/Refs/Atoms/Spans)\n                      │\n                      ▼\n                   Compile           Strict checks\n                   (normalize)  ──►  (structure, atoms, refs)\n                      │\n                      ├─▶ AF projection ──► clingo semantics (grounded|preferred|stable)\n                      │\n                      └─▶ FOL export    ──► TPTP/FOF (+ conjecture), optional E‑prover\n```\n\n**Key modules**\n\n- `argir/soft_ir.py` — minimal schema for LLM output\n- `argir/compile_soft.py` — soft → strict ARGIR\n- `argir/core/model.py` — typed strict ARGIR (statements, rules, edges, graph)\n- `argir/canonicalize.py` — canonical predicate table + examples\n- `argir/checks/*` — structural checks and warnings\n- `argir/semantics/*` — AF/APX, clingo backend, helpers\n- `argir/fol/*` — FOL AST, TPTP serializer, translation from ARGIR\n- `argir/diagnostics.py` — issue detectors\n- `argir/repairs/*` — AF enforcement \u0026 FOL abduction\n- `argir/report/*` — report renderer\n- `server.py` — FastAPI integration\n- `frontend/` — Vite/React dev UI\n\n**Design notes**\n\n- Soft IR forbids heavy structure (no strict atoms on first pass). It’s compiled and validated before AF/FOL.\n- FOL export avoids “linkage axioms” that can create **vacuous proofs**; the conjecture targets a selected node.\n- AF semantics use `clingo` via the Python package.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamin%2Fargir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamin%2Fargir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamin%2Fargir/lists"}