iil-reflex 0.1.0__tar.gz

iil_reflex-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.env.test
+*.so
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/

iil_reflex-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: iil-reflex
+Version: 0.1.0
+Summary: REFLEX — Reflexive Evidence-based Loop for UI Development
+Project-URL: Homepage, https://github.com/achimdehnert/iil-reflex
+Project-URL: Repository, https://github.com/achimdehnert/iil-reflex
+Project-URL: Documentation, https://knowledge.iil.pet/doc/adr-162-reflex
+Author-email: Achim Dehnert <achim@iil.gmbh>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: iil-promptfw<1,>=0.7.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: aifw
+Requires-Dist: iil-aifw>=0.9.0; extra == 'aifw'
+Provides-Extra: all
+Requires-Dist: iil-aifw>=0.9.0; extra == 'all'
+Requires-Dist: litellm>=1.40; extra == 'all'
+Requires-Dist: playwright>=1.40; extra == 'all'
+Requires-Dist: pytest-cov; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: ruff>=0.4; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: litellm>=1.40; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.40; extra == 'llm'
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == 'playwright'
+Description-Content-Type: text/markdown
+
+# iil-reflex
+
+**REFLEX — Reflexive Evidence-based Loop for UI Development**
+
+Evidence-based UI development methodology with LLM-powered domain agent,
+UC quality checker, and failure classifier. Pure Python — no Django dependency.
+
+## Architecture
+
+```
+reflex/
+├── agent.py       # DomainAgent (variable domain, LLM-powered)
+├── quality.py     # UC Quality Checker (11 criteria, rule-based)
+├── classify.py    # Failure Classifier (decision tree + LLM)
+├── config.py      # ReflexConfig from reflex.yaml
+├── providers.py   # KnowledgeProvider, DocumentProvider (Protocol)
+├── types.py       # Dataclasses (Results, Questions, Entries)
+└── templates/     # promptfw .jinja2 templates (6 templates)
+```
+
+## Installation
+
+```bash
+pip install iil-reflex
+# Optional: Playwright for Zirkel 2
+pip install iil-reflex[playwright]
+```
+
+## Quick Start
+
+```python
+from reflex.agent import DomainAgent
+from reflex.config import ReflexConfig
+from reflex.quality import UCQualityChecker
+
+# 1. Load hub config
+config = ReflexConfig.from_yaml("reflex.yaml")
+
+# 2. UC Quality Check (rule-based, no LLM needed)
+checker = UCQualityChecker(config)
+result = checker.check(uc_text="...", uc_slug="sds-upload")
+print(f"Score: {result.score_percent}%, Passed: {result.passed}")
+
+# 3. Domain Agent (LLM-powered)
+agent = DomainAgent(
+    config=config,
+    llm=your_llm_provider,
+    knowledge=your_knowledge_provider,  # optional
+    documents=your_document_provider,   # optional
+)
+research = agent.research("SDS Upload Pipeline")
+questions = agent.generate_interview(research)
+kb = agent.distill_kb(research, expert_answers={...})
+```
+
+## Hub Configuration (reflex.yaml)
+
+```yaml
+hub_name: risk-hub
+vertical: chemical_safety
+domain_keywords: ["SDS", "CAS", "GHS", "REACH"]
+quality:
+  min_acceptance_criteria: 2
+  max_uc_steps: 7
+  require_error_cases: true
+viewports:
+  - {name: mobile, width: 375, height: 812}
+  - {name: desktop, width: 1280, height: 800}
+htmx_patterns:
+  banned: ["hx-boost"]
+  required_on_forms: ["hx-indicator"]
+permissions_matrix:
+  /substances/: {anonymous: 302, viewer: 200, admin: 200}
+```
+
+## Provider Pattern
+
+All external dependencies use Protocols (Dependency Inversion):
+
+```python
+from reflex.providers import KnowledgeProvider, LLMProvider
+
+class OutlineProvider(KnowledgeProvider):
+    def search(self, query, limit=5):
+        return mcp3_search_knowledge(query, limit=limit)
+
+class GroqProvider(LLMProvider):
+    def complete(self, messages, action_code=""):
+        return groq_client.chat(messages=messages)
+```
+
+Mock providers included for testing:
+`MockKnowledgeProvider`, `MockDocumentProvider`, `MockLLMProvider`
+
+## REFLEX Methodology
+
+Three quality circles — no artifact without evidence:
+
+1. **Zirkel 0** — Domain KB (DomainAgent + Expert sign-off)
+2. **Zirkel 1** — UC Quality (11 criteria, 100% score required)
+3. **Zirkel 2** — Playwright Tests (1 test per acceptance criterion)
+
+Failure Classification:
+- **UC_PROBLEM** → UC needs revision (Zirkel 1 restart)
+- **UI_PROBLEM** → Wireframe needs fix
+- **INFRA_PROBLEM** → Server/browser/network issue
+
+## Dependencies
+
+- `iil-promptfw>=0.7.0` — prompt template rendering
+- `pyyaml>=6.0` — config file parsing
+- Optional: `playwright` — for Zirkel 2 test execution
+
+## Related
+
+- [ADR-162](https://knowledge.iil.pet/doc/adr-162-reflex) — Full ADR
+- [iil-promptfw](https://github.com/achimdehnert/promptfw) — Prompt framework
+- Platform: [achimdehnert/platform](https://github.com/achimdehnert/platform)
+
+## License
+
+MIT

iil_reflex-0.1.0/README.md

@@ -0,0 +1,122 @@
+# iil-reflex
+
+**REFLEX — Reflexive Evidence-based Loop for UI Development**
+
+Evidence-based UI development methodology with LLM-powered domain agent,
+UC quality checker, and failure classifier. Pure Python — no Django dependency.
+
+## Architecture
+
+```
+reflex/
+├── agent.py       # DomainAgent (variable domain, LLM-powered)
+├── quality.py     # UC Quality Checker (11 criteria, rule-based)
+├── classify.py    # Failure Classifier (decision tree + LLM)
+├── config.py      # ReflexConfig from reflex.yaml
+├── providers.py   # KnowledgeProvider, DocumentProvider (Protocol)
+├── types.py       # Dataclasses (Results, Questions, Entries)
+└── templates/     # promptfw .jinja2 templates (6 templates)
+```
+
+## Installation
+
+```bash
+pip install iil-reflex
+# Optional: Playwright for Zirkel 2
+pip install iil-reflex[playwright]
+```
+
+## Quick Start
+
+```python
+from reflex.agent import DomainAgent
+from reflex.config import ReflexConfig
+from reflex.quality import UCQualityChecker
+
+# 1. Load hub config
+config = ReflexConfig.from_yaml("reflex.yaml")
+
+# 2. UC Quality Check (rule-based, no LLM needed)
+checker = UCQualityChecker(config)
+result = checker.check(uc_text="...", uc_slug="sds-upload")
+print(f"Score: {result.score_percent}%, Passed: {result.passed}")
+
+# 3. Domain Agent (LLM-powered)
+agent = DomainAgent(
+    config=config,
+    llm=your_llm_provider,
+    knowledge=your_knowledge_provider,  # optional
+    documents=your_document_provider,   # optional
+)
+research = agent.research("SDS Upload Pipeline")
+questions = agent.generate_interview(research)
+kb = agent.distill_kb(research, expert_answers={...})
+```
+
+## Hub Configuration (reflex.yaml)
+
+```yaml
+hub_name: risk-hub
+vertical: chemical_safety
+domain_keywords: ["SDS", "CAS", "GHS", "REACH"]
+quality:
+  min_acceptance_criteria: 2
+  max_uc_steps: 7
+  require_error_cases: true
+viewports:
+  - {name: mobile, width: 375, height: 812}
+  - {name: desktop, width: 1280, height: 800}
+htmx_patterns:
+  banned: ["hx-boost"]
+  required_on_forms: ["hx-indicator"]
+permissions_matrix:
+  /substances/: {anonymous: 302, viewer: 200, admin: 200}
+```
+
+## Provider Pattern
+
+All external dependencies use Protocols (Dependency Inversion):
+
+```python
+from reflex.providers import KnowledgeProvider, LLMProvider
+
+class OutlineProvider(KnowledgeProvider):
+    def search(self, query, limit=5):
+        return mcp3_search_knowledge(query, limit=limit)
+
+class GroqProvider(LLMProvider):
+    def complete(self, messages, action_code=""):
+        return groq_client.chat(messages=messages)
+```
+
+Mock providers included for testing:
+`MockKnowledgeProvider`, `MockDocumentProvider`, `MockLLMProvider`
+
+## REFLEX Methodology
+
+Three quality circles — no artifact without evidence:
+
+1. **Zirkel 0** — Domain KB (DomainAgent + Expert sign-off)
+2. **Zirkel 1** — UC Quality (11 criteria, 100% score required)
+3. **Zirkel 2** — Playwright Tests (1 test per acceptance criterion)
+
+Failure Classification:
+- **UC_PROBLEM** → UC needs revision (Zirkel 1 restart)
+- **UI_PROBLEM** → Wireframe needs fix
+- **INFRA_PROBLEM** → Server/browser/network issue
+
+## Dependencies
+
+- `iil-promptfw>=0.7.0` — prompt template rendering
+- `pyyaml>=6.0` — config file parsing
+- Optional: `playwright` — for Zirkel 2 test execution
+
+## Related
+
+- [ADR-162](https://knowledge.iil.pet/doc/adr-162-reflex) — Full ADR
+- [iil-promptfw](https://github.com/achimdehnert/promptfw) — Prompt framework
+- Platform: [achimdehnert/platform](https://github.com/achimdehnert/platform)
+
+## License
+
+MIT

iil_reflex-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "iil-reflex"
+version = "0.1.0"
+description = "REFLEX — Reflexive Evidence-based Loop for UI Development"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    { name = "Achim Dehnert", email = "achim@iil.gmbh" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "iil-promptfw>=0.7.0,<1",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+llm = ["litellm>=1.40"]
+aifw = ["iil-aifw>=0.9.0"]
+playwright = ["playwright>=1.40"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov",
+    "ruff>=0.4",
+    "litellm>=1.40",
+]
+all = [
+    "iil-reflex[llm,aifw,playwright,dev]",
+]
+
+[project.scripts]
+reflex = "reflex.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/achimdehnert/iil-reflex"
+Repository = "https://github.com/achimdehnert/iil-reflex"
+Documentation = "https://knowledge.iil.pet/doc/adr-162-reflex"
+
+[tool.hatch.build.targets.sdist]
+exclude = [".windsurf", ".github"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["reflex"]
+
+
+[tool.ruff]
+target-version = "py311"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

iil_reflex-0.1.0/reflex/__init__.py

@@ -0,0 +1,27 @@
+"""
+REFLEX — Reflexive Evidence-based Loop for UI Development.
+
+Pure Python package for evidence-based UI quality methodology.
+No Django dependency in core — Django integration stays in each hub.
+
+Architecture:
+    reflex.agent         → DomainAgent (variable domain, LLM-powered)
+    reflex.quality       → UC Quality Checker (11 criteria)
+    reflex.classify      → Failure Classifier (UC_PROBLEM vs UI_PROBLEM)
+    reflex.config        → ReflexConfig from reflex.yaml
+    reflex.providers     → KnowledgeProvider, DocumentProvider (Protocol)
+    reflex.llm_providers → AifwProvider, LiteLLMProvider (via iil-aifw / litellm)
+    reflex.types         → Dataclasses (Results, Questions, Entries)
+    reflex.templates/    → promptfw .jinja2 templates (package_data)
+    reflex.__main__      → CLI: python -m reflex check/research/classify/info
+
+Usage:
+    from reflex.agent import DomainAgent
+    from reflex.config import ReflexConfig
+
+    config = ReflexConfig.from_yaml("reflex.yaml")
+    agent = DomainAgent(config=config)
+    result = agent.research("SDS Upload Pipeline")
+"""
+
+__version__ = "0.1.0"

iil_reflex-0.1.0/reflex/__main__.py

@@ -0,0 +1,241 @@
+"""
+REFLEX CLI — Command-line interface for UC quality checks and domain research.
+
+Usage:
+    python -m reflex check <uc-file> [--config reflex.yaml]
+    python -m reflex research <topic> [--config reflex.yaml] [--backend groq]
+    python -m reflex classify <test-name> <error-msg> [--uc-file <path>]
+    python -m reflex info [--config reflex.yaml]
+
+Examples:
+    python -m reflex check docs/uc/UC-001-sds-upload.md
+    python -m reflex research "Zoneneinteilung nach ATEX" --config reflex.yaml
+    python -m reflex classify "test_should_show_error" "AssertionError: heading"
+    python -m reflex info --config reflex.yaml
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """Run UCQualityChecker on a UC file."""
+    from reflex.config import ReflexConfig
+    from reflex.quality import UCQualityChecker
+
+    config = ReflexConfig.from_yaml(args.config) if args.config else ReflexConfig.from_dict({})
+    checker = UCQualityChecker(config)
+
+    uc_path = Path(args.uc_file)
+    if not uc_path.exists():
+        print(f"ERROR: UC file not found: {uc_path}", file=sys.stderr)
+        return 1
+
+    uc_text = uc_path.read_text(encoding="utf-8")
+    result = checker.check(uc_text, uc_slug=uc_path.stem)
+
+    print(f"\n{'='*60}")
+    print(f"  REFLEX UC Quality Check: {uc_path.name}")
+    print(f"{'='*60}")
+    print(f"  Score: {result.score_percent}% ({sum(1 for c in result.criteria if c.passed)}/{len(result.criteria)} criteria)")
+    print(f"  Passed: {'YES' if result.passed else 'NO'}")
+    print(f"{'='*60}\n")
+
+    for c in result.criteria:
+        icon = "✅" if c.passed else "❌"
+        print(f"  {icon} {c.name}")
+        if not c.passed:
+            print(f"     Evidence: {c.evidence}")
+            print(f"     Fix: {c.suggestion}")
+    print()
+
+    if result.failed_criteria:
+        print(f"  {len(result.failed_criteria)} criteria failed — see suggestions above.\n")
+        return 1
+    print("  All criteria passed!\n")
+    return 0
+
+
+def cmd_research(args: argparse.Namespace) -> int:
+    """Run DomainAgent.research() on a topic."""
+    from reflex.agent import DomainAgent
+    from reflex.config import ReflexConfig
+    from reflex.llm_providers import get_provider
+
+    config = ReflexConfig.from_yaml(args.config) if args.config else ReflexConfig.from_dict({})
+
+    provider_kwargs = {}
+    if args.model and args.backend in ("litellm", "auto"):
+        provider_kwargs["model"] = args.model
+    llm = get_provider(backend=args.backend, **provider_kwargs)
+
+    agent = DomainAgent(config=config, llm=llm)
+    topic = " ".join(args.topic)
+
+    model_name = getattr(llm, "model", args.backend)
+    print(f"\nResearching: {topic}")
+    print(f"  Vertical: {config.vertical}")
+    print(f"  Backend:  {args.backend} ({model_name})")
+    print(f"  {'─'*50}")
+
+    result = agent.research(topic)
+
+    print(f"\n  Confidence: {result.confidence:.0%}")
+    print(f"  Sources: {', '.join(result.sources_used) or 'LLM only'}")
+
+    if result.facts:
+        print(f"\n  Facts ({len(result.facts)}):")
+        for f in result.facts:
+            print(f"    • {f}")
+
+    if result.gaps:
+        print(f"\n  Gaps ({len(result.gaps)}):")
+        for g in result.gaps:
+            print(f"    ? {g}")
+
+    if result.contradictions:
+        print(f"\n  Contradictions ({len(result.contradictions)}):")
+        for c in result.contradictions:
+            print(f"    ⚠ {c}")
+
+    print()
+
+    if args.json:
+        output = {
+            "topic": result.topic,
+            "vertical": result.vertical,
+            "facts": result.facts,
+            "gaps": result.gaps,
+            "contradictions": result.contradictions,
+            "confidence": result.confidence,
+            "sources_used": result.sources_used,
+        }
+        print(json.dumps(output, indent=2, ensure_ascii=False))
+
+    return 0
+
+
+def cmd_classify(args: argparse.Namespace) -> int:
+    """Run FailureClassifier on a test failure."""
+    from reflex.classify import FailureClassifier
+
+    uc_text = ""
+    if args.uc_file:
+        uc_path = Path(args.uc_file)
+        if uc_path.exists():
+            uc_text = uc_path.read_text(encoding="utf-8")
+
+    classifier = FailureClassifier()
+    result = classifier.classify(
+        test_name=args.test_name,
+        error_message=args.error_message,
+        uc_text=uc_text,
+    )
+
+    print(f"\n{'='*60}")
+    print(f"  REFLEX Failure Classification")
+    print(f"{'='*60}")
+    print(f"  Test:       {args.test_name}")
+    print(f"  Type:       {result.failure_type.value}")
+    print(f"  Confidence: {result.confidence:.0%}")
+    print(f"  Reasoning:  {result.reasoning}")
+    print(f"  Action:     {result.suggested_action}")
+    if result.affected_criterion:
+        print(f"  Criterion:  {result.affected_criterion}")
+    print()
+
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    """Show REFLEX config info."""
+    from reflex.config import ReflexConfig
+
+    if not args.config:
+        print("ERROR: --config is required for info command", file=sys.stderr)
+        return 1
+
+    config = ReflexConfig.from_yaml(args.config)
+
+    print(f"\n{'='*60}")
+    print(f"  REFLEX Config: {args.config}")
+    print(f"{'='*60}")
+    print(f"  Hub:       {config.hub_name}")
+    print(f"  Vertical:  {config.vertical}")
+    print(f"  Keywords:  {', '.join(config.domain_keywords[:8])}")
+    print(f"  Viewports: {', '.join(v.name for v in config.viewports)}")
+    print(f"\n  Quality Rules:")
+    print(f"    Max steps:           {config.quality.max_uc_steps}")
+    print(f"    Min AK:              {config.quality.min_acceptance_criteria}")
+    print(f"    Require error cases: {config.quality.require_error_cases}")
+    print(f"    Forbid impl details: {config.quality.forbid_implementation_details}")
+    print(f"    Forbid soft lang:    {config.quality.forbid_soft_language}")
+
+    if config.htmx_patterns.banned:
+        print(f"\n  HTMX Banned: {', '.join(config.htmx_patterns.banned)}")
+
+    if config.permissions_matrix:
+        print(f"\n  Permission Matrix ({len(config.permissions_matrix)} URLs):")
+        for url, roles in config.permissions_matrix.items():
+            print(f"    {url}: {roles}")
+
+    print()
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="reflex",
+        description="REFLEX — Reflexive Evidence-based Loop for UI Development",
+    )
+    parser.add_argument("--config", "-c", help="Path to reflex.yaml")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # check
+    p_check = sub.add_parser("check", help="Check UC quality (11 criteria)")
+    p_check.add_argument("uc_file", help="Path to UC markdown file")
+
+    # research
+    p_research = sub.add_parser("research", help="Domain research via LLM")
+    p_research.add_argument("topic", nargs="+", help="Research topic")
+    p_research.add_argument(
+        "--backend", "-b", default="litellm",
+        help="LLM backend: auto (aifw if Django, else litellm), aifw, litellm",
+    )
+    p_research.add_argument(
+        "--model", "-m", default="groq/llama-3.3-70b-versatile",
+        help="litellm model string (e.g. groq/llama-3.3-70b-versatile, openai/gpt-4o-mini)",
+    )
+    p_research.add_argument("--json", "-j", action="store_true", help="Output JSON")
+
+    # classify
+    p_classify = sub.add_parser("classify", help="Classify test failure")
+    p_classify.add_argument("test_name", help="Test function name")
+    p_classify.add_argument("error_message", help="Error message")
+    p_classify.add_argument("--uc-file", help="UC file for context")
+
+    # info
+    sub.add_parser("info", help="Show config info")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    commands = {
+        "check": cmd_check,
+        "research": cmd_research,
+        "classify": cmd_classify,
+        "info": cmd_info,
+    }
+    return commands[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())