refactor(examples): CLI interface improvements

changes:
  - file: base_generator.py
    area: core
    added: [generate, ProjectGenerator]
  - file: common.py
    area: core
    modified: [get_token_reproduction_prompt]
  - file: runner.py
    area: core
    modified: [_template_generate_code, BenchmarkRunner]
  - file: llm_clients_new.py
    area: cli
    removed: [get_provider_priorities_from_litellm]
  - file: parsers.py
    area: analyzer
    modified: [_parse_java, _parse_csharp, UniversalParser]
  - file: benchmark_report.py
    area: core
    modified: [main]
  - file: benchmark_summary.py
    area: core
    modified: [main]

stats:
  lines: "+233/-6029 (net -5796)"
  files: 14
  complexity: "+22% complexity (new features)"

Author: tom-sapletta-com

CHANGELOG.md

@@ -1,3 +1,28 @@
+## [1.0.41] - 2026-02-25
+
+### Summary
+
+refactor(examples): CLI interface improvements
+
+### Docs
+
+- docs: update README
+
+### Other
+
+- build: update Makefile
+- update code2logic/base_generator.py
+- update code2logic/benchmarks/common.py
+- update code2logic/benchmarks/runner.py
+- update code2logic/llm_clients_new.py
+- update code2logic/parsers.py
+- update examples/benchmark_report.py
+- update examples/benchmark_summary.py
+- update function-schema.json
+- update function.toon
+- ... and 3 more
+
+
 ## [1.0.40] - 2026-02-25
 
 ### Summary

Makefile

@@ -336,7 +336,7 @@ else
 BENCH_NO_LLM_FLAG := --no-llm
 endif
 
-benchmark: benchmark-format benchmark-function-logic benchmark-function benchmark-token benchmark-project benchmark-toon benchmark-compare ## Run all benchmarks (no LLM)
+benchmark: benchmark-format benchmark-function benchmark-token benchmark-project benchmark-toon benchmark-compare ## Run all benchmarks (no LLM)
 	@echo ""
 	@echo "$(GREEN)All benchmarks completed!$(NC)"
 	@echo "Results in $(BENCH_OUTPUT)/"
@@ -360,17 +360,6 @@ benchmark-format: ## Benchmark format reproduction (yaml/toon/logicml/json)
 		--limit $(BENCH_LIMIT) --verbose \
 		--output $(BENCH_OUTPUT)/benchmark_format.json
 
-benchmark-function-logic: ## Benchmark function-logic TOON reproduction as a standalone format
-	@echo "$(BLUE)━━━ Function-Logic Format Benchmark ━━━$(NC)"
-	@mkdir -p $(BENCH_OUTPUT)
-	@printf '%s\n' "$(PYTHON) examples/15_unified_benchmark.py $(BENCH_NO_LLM_FLAG) --type format --folder $(BENCH_SAMPLES)/ --formats function.toon --limit $(BENCH_LIMIT) --verbose --output $(BENCH_OUTPUT)/benchmark_function_logic.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
-	$(PYTHON) examples/15_unified_benchmark.py \
-		$(BENCH_NO_LLM_FLAG) --type format \
-		--folder $(BENCH_SAMPLES)/ \
-		--formats function.toon \
-		--limit $(BENCH_LIMIT) --verbose \
-		--output $(BENCH_OUTPUT)/benchmark_function_logic.json
-
 benchmark-function: ## Benchmark function-level reproduction
 	@echo "$(BLUE)━━━ Function Benchmark ━━━$(NC)"
 	@printf '%s\n' "$(PYTHON) examples/15_unified_benchmark.py $(BENCH_NO_LLM_FLAG) --type function --file $(BENCH_SAMPLES)/sample_functions.py --limit 10 --verbose --output $(BENCH_OUTPUT)/benchmark_function.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh

VERSION

@@ -1 +1 @@
-1.0.40
+1.0.41

code2logic/__init__.py

@@ -18,7 +18,7 @@
     >>> print(output)
 """
 
-__version__ = "1.0.40"
+__version__ = "1.0.41"
 __author__ = "Softreck"
 __email__ = "info@softreck.dev"
 __license__ = "MIT"

code2logic/base_generator.py

@@ -0,0 +1,6 @@
+from typing import Protocol, Any
+from .models import ProjectInfo
+
+class ProjectGenerator(Protocol):
+    def generate(self, project: ProjectInfo, **kwargs: Any) -> Any:
+        ...

code2logic/benchmarks/common.py

@@ -189,14 +189,21 @@ def get_async_reproduction_prompt(spec: str, fmt: str, file_name: str, with_test
 
 def get_token_reproduction_prompt(spec: str, fmt: str, file_name: str, language: str = "python") -> str:
     format_hints = {
-        "json": "Parse the JSON structure and implement all classes and functions.",
-        "json_compact": "Parse the compact JSON and implement all elements.",
+        "json": "Parse the JSON structure and implement all classes and functions with exact signatures.",
+        "json_compact": "Parse the compact JSON and implement all elements with exact signatures.",
         "yaml": "Parse the YAML structure and implement all classes and functions with exact signatures.",
-        "gherkin": "Implement scenarios as SIMPLE, MINIMAL code. NO over-engineering. Keep code short and direct.",
-        "markdown": "Parse embedded Gherkin (behaviors) and YAML (structures).",
+        "gherkin": """Parse Gherkin/BDD scenarios and implement them as working code:
+- Each Feature maps to a class or module
+- Each Scenario maps to a function
+- Given/When/Then steps describe the logic flow
+- Implement actual logic, not just stubs
+Focus on the described behavior and implement it directly.""",
+        "markdown": "Parse embedded Gherkin (behaviors) and YAML (structures). Implement all described classes and functions.",
         "logicml": """Parse LogicML and generate VALID code:
 - 'sig:' lines describe function signatures (translate to the target language)
 - 'type: re-export' means this module primarily re-exports symbols
+- 'attrs:' = instance attributes to set in constructor
+- 'bases:' = parent classes to inherit from
 CRITICAL: Ensure valid syntax - balanced brackets, proper indentation, no undefined variables.""",
         "toon": """Parse TOON (Token-Oriented Object Notation) format carefully:
 
@@ -216,20 +223,32 @@ def get_token_reproduction_prompt(spec: str, fmt: str, file_name: str, language:
 - 'decorators: @staticmethod|@cache' = multiple decorators
 
 CRITICAL: Use imports[], function_docs, and exact signatures to reproduce code accurately.""",
+        "csv": """Parse the CSV table where each row describes a code element:
+- Columns: path, type (class/method/function), name, signature, language, intent, category, domain, imports
+- 'method' rows belong to the class in the preceding 'class' row
+- Implement all elements with the exact signatures shown
+Generate complete code with all classes, methods, and functions.""",
+        "function.toon": """Parse the function-logic TOON format:
+- 'modules[N]{path,lang,items}:' lists files
+- 'function_details:' contains per-module function listings
+- Each function has: line number, name, signature, description
+- 'ClassName.method_name' = method of that class
+- 'cc:N' after name = cyclomatic complexity
+Implement all listed functions with matching signatures and described behavior.""",
+    }
 
-        "function.toon": """Parse function-logic TOON carefully (function/method index):
-
-STRUCTURE:
-- 'modules[N]{path,lang,items}:' module index
-- 'function_details:' per-module tables
-
-CRITICAL:
-- Use the tabular rows (line,name,sig,does,decorators,calls,raises)
-- Reconstruct the full module code even if class bodies are not explicitly described
-- Preserve exact function signatures from 'sig'""",
+    # Language-specific guidance appended to prompt
+    lang_hints = {
+        "javascript": "Use ES6+ syntax (const/let, arrow functions, classes). Use module.exports or export.",
+        "typescript": "Use TypeScript syntax with interfaces, type annotations, and export statements.",
+        "go": "Use proper Go syntax: package declaration, func receivers for methods, error returns.",
+        "rust": "Use proper Rust syntax: impl blocks for methods, pub fn, Result/Option types, ownership.",
+        "java": "Use proper Java syntax: public class, access modifiers, typed parameters, semicolons.",
+        "csharp": "Use proper C# syntax: namespaces, access modifiers, typed parameters, semicolons.",
+        "sql": "Use standard SQL: CREATE TABLE/VIEW/FUNCTION, proper column types, constraints.",
     }
 
-    max_spec = 5000
+    max_spec = 8000
     spec_truncated = spec[:max_spec] if len(spec) > max_spec else spec
 
     language_norm = (language or "python").strip().lower()
@@ -245,8 +264,11 @@ def get_token_reproduction_prompt(spec: str, fmt: str, file_name: str, language:
     }
     lang_label = lang_label_map.get(language_norm, language_norm)
 
+    lang_hint = lang_hints.get(language_norm, '')
+    lang_hint_line = f"\n{lang_hint}" if lang_hint else ''
+
     prompt = f"""Generate {lang_label} code from this {fmt.upper()} specification.
-{format_hints.get(fmt, '')}
+{format_hints.get(fmt, '')}{lang_hint_line}
 
 {spec_truncated}
 

code2logic/benchmarks/runner.py

@@ -217,12 +217,37 @@ def _template_generate_code(self, spec: str, fmt: str, file_name: str, language:
         classes: List[str] = []
         functions: List[str] = []
 
-        # Common patterns
+        # Common patterns across formats
         classes.extend(re.findall(r"\bclass\s+([A-Za-z_][A-Za-z0-9_]*)", spec))
-        classes.extend(re.findall(r"^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*$", spec, re.MULTILINE))
+        classes.extend(re.findall(r'"name":\s*"([A-Z][A-Za-z0-9_]*)"', spec))
         functions.extend(re.findall(r"\bdef\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(", spec))
         functions.extend(re.findall(r"\bFunction:\s*([A-Za-z_][A-Za-z0-9_]*)", spec))
         functions.extend(re.findall(r"\bScenario:\s*([A-Za-z_][A-Za-z0-9_]*)", spec))
+        # TOON format: function lines like "  42,func_name,(params)"
+        functions.extend(re.findall(r'^\s+\d+,([A-Za-z_][A-Za-z0-9_]*),', spec, re.MULTILINE))
+        # TOON class.method: "  42,ClassName.method_name,"
+        for cm in re.findall(r'^\s+\d+,([A-Z][A-Za-z0-9_]*)\.([a-z_][A-Za-z0-9_]*),', spec, re.MULTILINE):
+            classes.append(cm[0])
+            functions.append(cm[1])
+        # YAML/JSON: "n: ClassName" or name patterns
+        classes.extend(re.findall(r'(?:^|\s)n:\s*([A-Z][A-Za-z0-9_]*)', spec, re.MULTILINE))
+        # CSV format: path,type,name columns
+        for row_m in re.findall(r',class,([A-Z][A-Za-z0-9_]*),', spec):
+            classes.append(row_m)
+        for row_m in re.findall(r',(?:function|method),([a-z_][A-Za-z0-9_]*),', spec):
+            functions.append(row_m)
+        # Gherkin: Feature/Scenario names
+        functions.extend(re.findall(r'Scenario(?:\s+Outline)?:\s*(?:Test\s+)?([A-Za-z_][A-Za-z0-9_]*)', spec))
+        # Non-Python: func/fn/function declarations
+        functions.extend(re.findall(r"\bfunc\s+([A-Za-z_][A-Za-z0-9_]*)", spec))
+        functions.extend(re.findall(r"\bfn\s+([A-Za-z_][A-Za-z0-9_]*)", spec))
+        functions.extend(re.findall(r"\bfunction\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(", spec))
+        # Java/C# style: "public static Type methodName("
+        functions.extend(re.findall(r"(?:public|private)\s+(?:static\s+)?\w+\s+([a-z][A-Za-z0-9_]*)\s*\(", spec))
+        # Interfaces/structs/enums
+        classes.extend(re.findall(r"\binterface\s+([A-Za-z_][A-Za-z0-9_]*)", spec))
+        classes.extend(re.findall(r"\bstruct\s+([A-Za-z_][A-Za-z0-9_]*)", spec))
+        classes.extend(re.findall(r"\benum\s+([A-Za-z_][A-Za-z0-9_]*)", spec))
 
         # Deduplicate while preserving order
         def uniq(items: List[str]) -> List[str]:

code2logic/llm_clients_new.py

@@ -2212,30 +2212,30 @@ def _parse_java(self, filepath: str, content: str) -> ModuleInfo:
         for m in re.finditer(r'^import\s+([^;]+);', content, re.MULTILINE):
             imports.append(m.group(1).strip())
 
-        for m in re.finditer(r'^(?:public\s+)?(?:abstract\s+)?class\s+(\w+)', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?(?:abstract\s+)?class\s+(\w+)', content, re.MULTILINE):
             name = m.group(1)
             classes.append(ClassInfo(name=name, is_abstract='abstract' in m.group(0)))
             exports.append(name)
 
-        for m in re.finditer(r'^(?:public\s+)?interface\s+(\w+)', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?interface\s+(\w+)', content, re.MULTILINE):
             name = m.group(1)
             classes.append(ClassInfo(name=name, is_interface=True))
             exports.append(name)
             types.append(TypeInfo(name=name, kind='interface', definition=''))
 
-        for m in re.finditer(r'^(?:public\s+)?enum\s+(\w+)', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?enum\s+(\w+)', content, re.MULTILINE):
             name = m.group(1)
             types.append(TypeInfo(name=name, kind='enum', definition=''))
             exports.append(name)
 
-        for m in re.finditer(r'^(?:public\s+)?record\s+(\w+)\s*\(', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?record\s+(\w+)\s*\(', content, re.MULTILINE):
             name = m.group(1)
             classes.append(ClassInfo(name=name))
             types.append(TypeInfo(name=name, kind='record', definition=''))
             exports.append(name)
 
-        # Very rough method detection (only top-level class members are not tracked here)
-        for m in re.finditer(r'^(?:public|protected|private)\s+(?:static\s+)?([\w<>\[\]]+)\s+(\w+)\s*\(([^)]*)\)\s*\{', content, re.MULTILINE):
+        # Method detection – allow indented declarations inside classes
+        for m in re.finditer(r'^\s*(?:@\w+\s+)*(?:public|protected|private)\s+(?:static\s+)?(?:final\s+)?(?:synchronized\s+)?([\w<>\[\],\s]+?)\s+(\w+)\s*\(([^)]*)\)\s*(?:throws\s+[\w,\s]+)?\s*\{', content, re.MULTILINE):
             ret_type = m.group(1)
             name = m.group(2)
             params = [p.strip() for p in (m.group(3) or '').split(',') if p.strip()][:8]
@@ -2260,7 +2260,7 @@ def _parse_java(self, filepath: str, content: str) -> ModuleInfo:
                 is_private=False,
             ))
 
-        for m in re.finditer(r'^(?:public\s+)?static\s+final\s+[\w<>\[\]]+\s+([A-Z][A-Z0-9_]*)\b', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?static\s+final\s+[\w<>\[\]]+\s+([A-Z][A-Z0-9_]*)\b', content, re.MULTILINE):
             constants.append(m.group(1))
 
         lines = content.split('\n')
@@ -2290,24 +2290,24 @@ def _parse_csharp(self, filepath: str, content: str) -> ModuleInfo:
         for m in re.finditer(r'^using\s+([^;]+);', content, re.MULTILINE):
             imports.append(m.group(1).strip())
 
-        for m in re.finditer(r'^(?:public\s+)?interface\s+(I\w+)', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?interface\s+(I\w+)', content, re.MULTILINE):
             name = m.group(1)
             classes.append(ClassInfo(name=name, is_interface=True))
             exports.append(name)
             types.append(TypeInfo(name=name, kind='interface', definition=''))
 
-        for m in re.finditer(r'^(?:public\s+)?(?:abstract\s+)?class\s+(\w+)', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?(?:abstract\s+)?class\s+(\w+)', content, re.MULTILINE):
             name = m.group(1)
             classes.append(ClassInfo(name=name, is_abstract='abstract' in m.group(0)))
             exports.append(name)
 
-        for m in re.finditer(r'^(?:public\s+)?record\s+(\w+)', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?record\s+(\w+)', content, re.MULTILINE):
             name = m.group(1)
             classes.append(ClassInfo(name=name))
             exports.append(name)
             types.append(TypeInfo(name=name, kind='record', definition=''))
 
-        for m in re.finditer(r'^(?:public|private|protected|internal)\s+(?:static\s+)?([\w<>\[\]?]+)\s+(\w+)\s*\(([^)]*)\)\s*\{', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public|private|protected|internal)\s+(?:static\s+)?(?:async\s+)?(?:override\s+)?(?:virtual\s+)?([\w<>\[\]?]+)\s+(\w+)\s*\(([^)]*)\)\s*\{', content, re.MULTILINE):
             ret_type = m.group(1)
             name = m.group(2)
             params = [p.strip() for p in (m.group(3) or '').split(',') if p.strip()][:8]
@@ -2332,7 +2332,7 @@ def _parse_csharp(self, filepath: str, content: str) -> ModuleInfo:
                 is_private=False,
             ))
 
-        for m in re.finditer(r'^(?:public\s+)?const\s+[\w<>\[\]]+\s+([A-Z][A-Z0-9_]*)\b', content, re.MULTILINE):
+        for m in re.finditer(r'^\s*(?:public\s+)?const\s+[\w<>\[\]]+\s+([A-Z][A-Z0-9_]*)\b', content, re.MULTILINE):
             constants.append(m.group(1))
 
         lines = content.split('\n')

code2logic/parsers.py

@@ -165,7 +165,7 @@ def main() -> None:
     lines.append("| Artifact | File | Size | ~Tokens | Description |")
     lines.append("|---|---|---:|---:|---|")
     for a in artifacts:
-        rel = a.path.relative_to(out_dir) if a.path.exists() and out_dir in a.path.parents else a.path
+        rel = a.path.relative_to(out_dir) if out_dir in a.path.parents else a.path
         size = _sizeof(a.path)
         tok_est = _token_estimate_bytes(size)
         file_cell = f"`{rel}`" if isinstance(rel, Path) else f"`{rel}`"