feat(examples): CLI interface improvements

changes:
  - file: common.py
    area: core
    modified: [generate_spec]
  - file: function_logic.py
    area: core
    modified: [FunctionLogicGenerator, generate_toon_schema]
  - file: behavioral_benchmark.py
    area: core
    added: [_looks_like_template_stub]
    modified: [main, _run_case, FunctionBehaviorResult]
  - file: benchmark_report.py
    area: core
    modified: [main]
  - file: benchmark_summary.py
    area: core
    added: [_token_estimate_bytes, _fmt_bytes, _artifact_row]
    modified: [main]

stats:
  lines: "+209/-66 (net +143)"
  files: 14
  complexity: "Large structural change (normalized)"

Author: tom-sapletta-com

.env.example

@@ -8,6 +8,7 @@
 # OpenRouter (https://openrouter.ai)
 OPENROUTER_API_KEY=sk-or-v1-your-key-here
 OPENROUTER_MODEL=qwen/qwen-2.5-coder-32b-instruct
+BENCH_USE_LLM=1
 
 # OpenAI (https://platform.openai.com)
 OPENAI_API_KEY=sk-your-key-here

CHANGELOG.md

@@ -1,3 +1,30 @@
+## [1.0.39] - 2026-02-25
+
+### Summary
+
+feat(examples): CLI interface improvements
+
+### Docs
+
+- docs: update README
+- docs: update 03-cli-reference.md
+- docs: update 07-toon.md
+
+### Other
+
+- update .env.example
+- build: update Makefile
+- update code2logic/benchmarks/common.py
+- update code2logic/function_logic.py
+- update examples/behavioral_benchmark.py
+- update examples/benchmark_report.py
+- update examples/benchmark_summary.py
+- update function.toon
+- update project.functions-schema.json
+- update project.functions.toon
+- ... and 1 more
+
+
 ## [1.0.38] - 2026-02-25
 
 ### Summary

Makefile

@@ -306,7 +306,16 @@ status: ## Show library status
 BENCH_SAMPLES := tests/samples
 BENCH_OUTPUT  := examples/output
 BENCH_LIMIT   := 20
-BENCH_FORMATS := yaml toon logicml json
+BENCH_FORMATS := yaml toon logicml json markdown csv gherkin
+
+# Set BENCH_USE_LLM=1 to run benchmarks with a configured LLM provider
+# (e.g. OpenRouter) instead of offline template mode.
+BENCH_USE_LLM ?= 0
+ifeq ($(BENCH_USE_LLM),1)
+BENCH_NO_LLM_FLAG :=
+else
+BENCH_NO_LLM_FLAG := --no-llm
+endif
 
 benchmark: benchmark-format benchmark-function benchmark-token benchmark-project benchmark-toon benchmark-compare ## Run all benchmarks (no LLM)
 	@echo ""
@@ -324,19 +333,19 @@ benchmark-format: ## Benchmark format reproduction (yaml/toon/logicml/json)
 	@echo "# Auto-generated by make benchmark" > $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
 	@echo "set -euo pipefail" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
 	@echo "" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
-	@printf '%s\n' "$(PYTHON) examples/15_unified_benchmark.py --no-llm --type format --folder $(BENCH_SAMPLES)/ --formats $(BENCH_FORMATS) --limit $(BENCH_LIMIT) --verbose --output $(BENCH_OUTPUT)/benchmark_format.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
+	@printf '%s\n' "$(PYTHON) examples/15_unified_benchmark.py $(BENCH_NO_LLM_FLAG) --type format --folder $(BENCH_SAMPLES)/ --formats $(BENCH_FORMATS) --limit $(BENCH_LIMIT) --verbose --output $(BENCH_OUTPUT)/benchmark_format.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
 	$(PYTHON) examples/15_unified_benchmark.py \
-		--no-llm --type format \
+		$(BENCH_NO_LLM_FLAG) --type format \
 		--folder $(BENCH_SAMPLES)/ \
 		--formats $(BENCH_FORMATS) \
 		--limit $(BENCH_LIMIT) --verbose \
 		--output $(BENCH_OUTPUT)/benchmark_format.json
 
 benchmark-function: ## Benchmark function-level reproduction
 	@echo "$(BLUE)━━━ Function Benchmark ━━━$(NC)"
-	@printf '%s\n' "$(PYTHON) examples/15_unified_benchmark.py --no-llm --type function --file $(BENCH_SAMPLES)/sample_functions.py --limit 10 --verbose --output $(BENCH_OUTPUT)/benchmark_function.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
+	@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
 	$(PYTHON) examples/15_unified_benchmark.py \
-		--no-llm --type function \
+		$(BENCH_NO_LLM_FLAG) --type function \
 		--file $(BENCH_SAMPLES)/sample_functions.py \
 		--limit 10 --verbose \
 		--output $(BENCH_OUTPUT)/benchmark_function.json
@@ -347,19 +356,19 @@ benchmark-function: ## Benchmark function-level reproduction
 
 benchmark-token: ## Benchmark token efficiency across formats
 	@echo "$(BLUE)━━━ Token Efficiency Benchmark ━━━$(NC)"
-	@printf '%s\n' "$(PYTHON) examples/11_token_benchmark.py --no-llm --folder $(BENCH_SAMPLES)/ --formats $(BENCH_FORMATS) --limit $(BENCH_LIMIT) --verbose --output $(BENCH_OUTPUT)/benchmark_token.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
+	@printf '%s\n' "$(PYTHON) examples/11_token_benchmark.py $(BENCH_NO_LLM_FLAG) --folder $(BENCH_SAMPLES)/ --formats $(BENCH_FORMATS) --limit $(BENCH_LIMIT) --verbose --output $(BENCH_OUTPUT)/benchmark_token.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
 	$(PYTHON) examples/11_token_benchmark.py \
-		--no-llm \
+		$(BENCH_NO_LLM_FLAG) \
 		--folder $(BENCH_SAMPLES)/ \
 		--formats $(BENCH_FORMATS) \
 		--limit $(BENCH_LIMIT) --verbose \
 		--output $(BENCH_OUTPUT)/benchmark_token.json
 
 benchmark-project: ## Benchmark project-level reproduction
 	@echo "$(BLUE)━━━ Project Benchmark ━━━$(NC)"
-	@printf '%s\n' "$(PYTHON) examples/15_unified_benchmark.py --no-llm --type project --folder $(BENCH_SAMPLES)/ --formats $(BENCH_FORMATS) --limit $(BENCH_LIMIT) --verbose --output $(BENCH_OUTPUT)/benchmark_project.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
+	@printf '%s\n' "$(PYTHON) examples/15_unified_benchmark.py $(BENCH_NO_LLM_FLAG) --type project --folder $(BENCH_SAMPLES)/ --formats $(BENCH_FORMATS) --limit $(BENCH_LIMIT) --verbose --output $(BENCH_OUTPUT)/benchmark_project.json" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
 	$(PYTHON) examples/15_unified_benchmark.py \
-		--no-llm --type project \
+		$(BENCH_NO_LLM_FLAG) --type project \
 		--folder $(BENCH_SAMPLES)/ \
 		--formats $(BENCH_FORMATS) \
 		--limit $(BENCH_LIMIT) --verbose \
@@ -368,14 +377,15 @@ benchmark-project: ## Benchmark project-level reproduction
 benchmark-toon: ## Generate TOON + function-logic for self-analysis
 	@echo "$(BLUE)━━━ TOON Self-Analysis ━━━$(NC)"
 	@mkdir -p $(BENCH_OUTPUT)
+	@rm -f $(BENCH_OUTPUT)/function.toon $(BENCH_OUTPUT)/function-schema.json 2>/dev/null || true
 	@printf '%s\n' "$(PYTHON) -m code2logic ./ -f toon --compact --name project -o ./" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
 	$(PYTHON) -m code2logic ./ -f toon --compact --name project -o ./
-	@printf '%s\n' "$(PYTHON) -m code2logic ./ -f toon --compact --no-repeat-module --function-logic function.toon --with-schema --name project -o ./" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
-	$(PYTHON) -m code2logic ./ -f toon --compact --no-repeat-module --function-logic function.toon --with-schema --name project -o ./
+	@printf '%s\n' "$(PYTHON) -m code2logic ./ -f toon --compact --no-repeat-module --function-logic --with-schema --name project -o ./" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
+	$(PYTHON) -m code2logic ./ -f toon --compact --no-repeat-module --function-logic --with-schema --name project -o ./
 	@cp -f project.toon $(BENCH_OUTPUT)/project.toon 2>/dev/null || true
 	@cp -f project.toon-schema.json $(BENCH_OUTPUT)/project.toon-schema.json 2>/dev/null || true
-	@cp -f function.toon $(BENCH_OUTPUT)/function.toon 2>/dev/null || true
-	@cp -f function-schema.json $(BENCH_OUTPUT)/function-schema.json 2>/dev/null || true
+	@cp -f project.functions.toon $(BENCH_OUTPUT)/project.functions.toon 2>/dev/null || true
+	@cp -f project.functions-schema.json $(BENCH_OUTPUT)/project.functions-schema.json 2>/dev/null || true
 	@printf '%s\n' "$(PYTHON) -m code2logic ./ -f yaml --compact --name project -o $(BENCH_OUTPUT)/" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
 	$(PYTHON) -m code2logic ./ -f yaml --compact --name project -o $(BENCH_OUTPUT)/
 	@printf '%s\n' "$(PYTHON) -m code2logic ./ -f json --name project -o $(BENCH_OUTPUT)/" >> $(BENCH_OUTPUT)/BENCHMARK_COMMANDS.sh
@@ -390,7 +400,7 @@ benchmark-toon: ## Generate TOON + function-logic for self-analysis
 	@echo "$(BLUE)Format size comparison (self-analysis):$(NC)"
 	@printf "  %-25s %10s %10s\n" "Format" "Size" "~Tokens"
 	@printf "  %-25s %10s %10s\n" "-------------------------" "----------" "----------"
-	@for f in $(BENCH_OUTPUT)/project.toon $(BENCH_OUTPUT)/function.toon $(BENCH_OUTPUT)/project.yaml $(BENCH_OUTPUT)/project.json $(BENCH_OUTPUT)/project.md $(BENCH_OUTPUT)/project.txt $(BENCH_OUTPUT)/project.csv; do \
+	@for f in $(BENCH_OUTPUT)/project.toon $(BENCH_OUTPUT)/project.functions.toon $(BENCH_OUTPUT)/project.yaml $(BENCH_OUTPUT)/project.json $(BENCH_OUTPUT)/project.md $(BENCH_OUTPUT)/project.txt $(BENCH_OUTPUT)/project.csv; do \
 		if [ -f "$$f" ]; then \
 			sz=$$(wc -c < "$$f"); \
 			tok=$$((sz / 4)); \
@@ -399,7 +409,7 @@ benchmark-toon: ## Generate TOON + function-logic for self-analysis
 	done
 	@echo ""
 	@echo "$(GREEN)TOON files:$(NC)"
-	@ls -lh $(BENCH_OUTPUT)/project.toon $(BENCH_OUTPUT)/function.toon $(BENCH_OUTPUT)/project.toon-schema.json $(BENCH_OUTPUT)/function-schema.json 2>/dev/null
+	@ls -lh $(BENCH_OUTPUT)/project.toon $(BENCH_OUTPUT)/project.functions.toon $(BENCH_OUTPUT)/project.toon-schema.json $(BENCH_OUTPUT)/project.functions-schema.json 2>/dev/null
 
 benchmark-compare: ## Show summary comparison of all benchmark results
 	@echo ""

README.md

@@ -49,9 +49,9 @@ pip install code2logic[nlp]         # Enhanced intents
 ## 📖 Quick Start
 ```bash
 code2logic ./ -f yaml --compact --function-logic --with-schema -o project.yaml
-code2logic ./ -f toon --function-logic function.toon --with-schema --name project -o ./
-# Optional: include function intent/purpose column in function.toon
-code2logic ./ -f toon --function-logic function.toon --does --name project -o ./
+code2logic ./ -f toon --function-logic --with-schema --name project -o ./
+# Optional: include function intent/purpose column in project.functions.toon
+code2logic ./ -f toon --function-logic --does --name project -o ./
 ```
 
 ### Command Line

VERSION

@@ -1 +1 @@
-1.0.38
+1.0.39

code2logic/__init__.py

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

code2logic/benchmarks/common.py

@@ -4,7 +4,7 @@
 from datetime import datetime
 from pathlib import Path
 
-from ..generators import JSONGenerator, YAMLGenerator
+from ..generators import CSVGenerator, JSONGenerator, YAMLGenerator
 from ..gherkin import GherkinGenerator
 from ..logicml import LogicMLGenerator
 from ..markdown_format import MarkdownHybridGenerator
@@ -32,6 +32,9 @@ def generate_spec(project: ProjectInfo, fmt: str) -> str:
     if fmt == "gherkin":
         gen = GherkinGenerator()
         return gen.generate(project)
+    if fmt == "csv":
+        gen = CSVGenerator()
+        return gen.generate(project, detail="full")
     if fmt == "yaml":
         gen = YAMLGenerator()
         return gen.generate(project, detail="full")

code2logic/function_logic.py

@@ -160,7 +160,7 @@ def generate_toon_schema(self) -> str:
             "$schema": "https://json-schema.org/draft/2020-12/schema",
             "title": "Code2Logic Function-Logic TOON Schema",
             "description": (
-                "Schema for function.toon — compact function/method index. "
+                "Schema for function-logic TOON output (e.g. project.functions.toon) — compact function/method index. "
                 "Conventions: name containing '.' = method (Class.method), "
                 "~prefix = async, 'cc:N' suffix = cyclomatic complexity (only when >1)."
             ),

docs/03-cli-reference.md

@@ -120,11 +120,11 @@ code2logic /path/to/project -f hybrid -o analysis.hybrid.yaml
 # Standard TOON (token-efficient)
 code2logic /path/to/project -f toon -o analysis.toon
 
-# Function-logic TOON (outputs function.toon + optional schema)
-code2logic /path/to/project -f toon --compact --function-logic function.toon --name project -o ./
+# Function-logic TOON (outputs project.functions.toon + optional schema)
+code2logic /path/to/project -f toon --compact --function-logic --name project -o ./
 
 # Same as above, but also compress repeated module paths and generate JSON Schema
-code2logic /path/to/project -f toon --compact --no-repeat-module --function-logic function.toon --with-schema --name project -o ./
+code2logic /path/to/project -f toon --compact --no-repeat-module --function-logic --with-schema --name project -o ./
 
 # Ultra-compact TOON (71% smaller, single-letter keys)
 code2logic /path/to/project -f toon --ultra-compact -o analysis-ultra.toon
@@ -141,8 +141,8 @@ code2logic /path/to/project -f toon --function-logic --name project -o ./ --no-r
 # Generate function-logic TOON with intent descriptions (does column)
 code2logic /path/to/project -f toon --function-logic --does --name project -o ./
 
-# Generate function-logic TOON + schema (function.toon + function-schema.json)
-code2logic /path/to/project -f toon --function-logic function.toon --with-schema --name project -o ./
+# Generate function-logic TOON + schema (project.functions.toon + project.functions-schema.json)
+code2logic /path/to/project -f toon --function-logic --with-schema --name project -o ./
 ```
 
 Token-oriented object notation - most efficient format for LLM consumption.
@@ -163,7 +163,7 @@ Generated artifacts (written to `examples/output/`):
   - Exact commands used to generate each artifact
 - `benchmark_format.json`, `benchmark_project.json`, `benchmark_token.json`, `benchmark_function.json`
   - Raw benchmark results
-- `project.toon`, `function.toon` (+ `*-schema.json`)
+- `project.toon`, `project.functions.toon` (+ `*-schema.json`)
   - Self-analysis outputs used for size/token comparisons
 
 Run all example scripts step-by-step:

docs/07-toon.md

@@ -129,20 +129,20 @@ code2logic /path/to/project -f toon --no-repeat-module -o analysis.toon
 code2logic /path/to/project -f toon --function-logic --name project -o ./ --no-repeat-details
 
 # Generate function-logic TOON
-# Output file: function.toon
-code2logic /path/to/project -f toon --function-logic function.toon --name project -o ./
+# Output file: project.functions.toon
+code2logic /path/to/project -f toon --function-logic --name project -o ./
 
 # Generate function-logic TOON + schema
 # Output files:
-# - function.toon
-# - function-schema.json
-code2logic /path/to/project -f toon --function-logic function.toon --with-schema --name project -o ./
+# - project.functions.toon
+# - project.functions-schema.json
+code2logic /path/to/project -f toon --function-logic --with-schema --name project -o ./
 
 # Generate function-logic TOON + schema + compress repeated module paths
 # Output files:
-# - function.toon
-# - function-schema.json
-code2logic /path/to/project -f toon --compact --no-repeat-module --function-logic function.toon --with-schema --name project -o ./
+# - project.functions.toon
+# - project.functions-schema.json
+code2logic /path/to/project -f toon --compact --no-repeat-module --function-logic --with-schema --name project -o ./
 ```
 
 ### Reducing Path Repetition (Filesystem Tree Hint)
@@ -250,8 +250,8 @@ Use `--does` when you need the LLM to understand **what each function does**, no
 When `--with-schema` is used with `--function-logic` and TOON format, a JSON schema is written alongside:
 
 ```bash
-code2logic /path/to/project -f toon --function-logic function.toon --with-schema --name project -o ./
-# Produces: function.toon + function-schema.json
+code2logic /path/to/project -f toon --function-logic --with-schema --name project -o ./
+# Produces: project.functions.toon + project.functions-schema.json
 ```
 
 If using `--stdout`, the function-logic schema is printed under the `=== FUNCTION_LOGIC_SCHEMA ===` section marker.