refactoring

Author: tom-sapletta-com

C2L.md

@@ -0,0 +1,100 @@
+# LLM i limit kontekstu: Dlaczego JSON to ślepa uliczka i jak Code2Logic zmienia zasady gry
+
+**Autor: Tom Sapletta**
+
+Jeśli kiedykolwiek próbowałeś "nakarmić" model językowy (LLM) całym repozytorium kodu, by poprosić go o refaktoryzację, znalezienie błędu czy wygenerowanie dokumentacji, na pewno zderzyłeś się ze ścianą. Ścianą tą jest limit okna kontekstowego oraz zjawisko znane jako *lost in the middle* – model zapomina lub ignoruje informacje znajdujące się w środku długiego promptu. 
+
+Cześć, jestem Tom Sapletta i od dłuższego czasu pracuję nad tym, jak zoptymalizować komunikację między kodem źródłowym a sztuczną inteligencją. Tak właśnie narodził się projekt **Code2Logic**.
+
+## Dlaczego powstał Code2Logic?
+
+Kiedy LLM analizuje nasz kod, nie potrzebuje wszystkich średników, nawiasów, wcięć ani nadmiarowej struktury danych. Tradycyjne podejście polega na serializacji struktury projektu do formatu JSON. Niestety, JSON jest dla LLM-ów "głośny". 
+
+Spójrzmy na to zjawisko wizualnie:
+
+```text
++-----------------------------------+   +-----------------------+
+|  Tradycyjny JSON (Duży szum)      |   |  Format TOON (Czysto) |
+|-----------------------------------|   |-----------------------|
+| {                                 |   | classes:              |
+|   "User": {                       |   |   User                |
+|     "methods": [                  |   |     - get_email()     |
+|       {                           |   |     - set_email(e)    |
+|         "name": "get_email",      |   |                       |
+|         "type": "string"          |   |                       |
+|       }                           |   |                       |
+|     ]                             |   |                       |
+|   }                               |   |                       |
+| }                                 |   |                       |
++-----------------------------------+   +-----------------------+
+```
+
+W formacie JSON większość tokenów, za które płacimy (i które marnują "uwagę" modelu), to nawiasy klamrowe, cudzysłowy i powtarzające się klucze. Code2Logic powstał po to, aby wyekstrahować **czystą logikę** z kodu i przekazać ją do modelu w maksymalnie skompresowanych formatach, takich jak nasz autorski **TOON** czy **LogicML**.
+
+Poniższy diagram obrazuje, jak Code2Logic zmienia architekturę przepływu danych:
+
+```mermaid
+graph TD
+    A[Repozytorium Kodu] -->|Parsowanie<br/>Code2Logic| B(Abstrakcyjna Reprezentacja)
+    B --> C{Wybór Formatu}
+    
+    C -->|Tradycyjny| D[JSON / XML]
+    D -->|Zapychanie kontekstu| E(LLM traci skupienie)
+    E -->|Gorsza jakość| F[Zła odpowiedź / Błędy]
+    
+    C -->|Zoptymalizowany| G[TOON / LogicML]
+    G ==>|Maksymalna kompresja tokenów| H((LLM skupia się<br/>na architekturze))
+    H ==>|Wysoka precyzja| I[Doskonały Kod / Refaktoring]
+    
+    style G fill:#2ecc71,stroke:#333,stroke-width:2px,color:white
+    style H fill:#3498db,stroke:#333,stroke-width:2px,color:white
+    style D fill:#e74c3c,stroke:#333,stroke-width:2px,color:white
+```
+
+## Fascynujące rezultaty benchmarków
+
+Zbudowałem w pełni zautomatyzowane środowisko testowe, które sprawdza, jak LLM (np. `google/gemini-3-flash-preview`) radzi sobie z rekonstrukcją kodu na podstawie różnych specyfikacji. Otrzymane wyniki przerosły moje oczekiwania i jednoznacznie pokazały, że format ma znaczenie.
+
+Oto co odkryliśmy w trakcie naszych najnowszych benchmarków na próbie 20 plików:
+
+### 1. Kolosalna różnica w rozmiarze i tokenach
+Zrzut struktury tego samego projektu waży:
+* **JSON:** ~918 KB (~235 000 tokenów)
+* **TOON:** ~170 KB (~43 000 tokenów)
+
+Zredukowaliśmy objętość ponad 5-krotnie! Oznacza to, że do kontekstu modelu jesteśmy w stanie zmieścić 5 razy większy projekt, płacąc ułamek oryginalnej ceny.
+
+### 2. LLM lepiej rozumie skompresowaną wiedzę
+Mogłoby się wydawać, że JSON, jako standard branżowy, będzie najbardziej zrozumiały dla maszyny. Prawda jest jednak inna. Brak redundancji w formacie TOON sprawia, że LLM znacznie rzadziej się "gubi".
+
+Wyniki z naszego *Project Benchmark* (Zdolność LLM do odtworzenia poprawnego strukturalnie i semantycznie kodu na bazie specyfikacji):
+
+```mermaid
+xychart-beta
+    title "Jakość Reprodukcji Projektu przez LLM (Wynik w %)"
+    x-axis ["TOON", "YAML", "Markdown", "LogicML", "JSON", "CSV", "Gherkin"]
+    y-axis "Zgodność rekonstrukcji (%)" 40 --> 90
+    bar [82.7, 79.2, 76.2, 76.0, 73.5, 67.8, 48.0]
+```
+
+Format **TOON uzyskał imponujące 82.7%**, zostawiając JSON (73.5%) daleko w tyle. Jeszcze ciekawszy jest **LogicML**, który zużywa średnio zaledwie 245 tokenów na plik (10-krotnie mniej niż JSON!), a nadal utrzymuje wynik powyżej 76%.
+
+## Wnioski i wyzwania na przyszłość
+
+Dane z benchmarków pokazały nam drogę, ale obnażyły też obszary do natychmiastowej poprawy:
+
+1. **Przejście z heurystyk (Regex) na AST (Abstract Syntax Tree):**  
+   Obecny benchmark świetnie radzi sobie z Pythonem, ale traci skuteczność przy ocenie rekonstrukcji w JavaScripcie, Javie czy Rust (często oceniając wygenerowane struktury na 0%). Wdrożenie parserów opartych na AST sprawi, że metryki będą w 100% niezależne od języka, a ewaluacja struktury (klasy, funkcje) nie będzie mylona z różnicami w formatowaniu tekstu.
+
+2. **Głębsza reprodukcja logiki funkcji:**  
+   O ile ogólna architektura klas odtwarza się na poziomie ~82%, o tyle rekonstrukcja wewnętrznej logiki ukrytej *w ciałach funkcji* nadal oscyluje wokół 38.5%. Rozwiązaniem, które właśnie testujemy, jest równoległe dołączanie pliku `project.functions.toon`, który w kompresowanym formacie wstrzykuje informacje o przepływie danych wewnątrz metod.
+
+## Podsumowanie
+
+Przekładanie całego repozytorium do formatu JSON, by porozmawiać z LLM-em o architekturze, to ślepa uliczka zjadająca budżet i precyzję. **Code2Logic** udowadnia, że kluczem do lepszych wyników AI nie zawsze jest większy lub droższy model – częściej jest nim po prostu podanie mu wiedzy w lepszym, "czystszym" formacie bez zbędnego szumu.
+
+Dalszy rozwój projektu to pełna abstrakcja języków poprzez AST i poprawa ewaluacji behawioralnej. Przed nami jeszcze sporo pracy, ale już teraz TOON i LogicML mogą uratować Wasze portfele i nerwy.
+
+---
+*Jeśli interesuje Cię, jak optymalizować pracę sztucznej inteligencji z kodem,
+sprawdź [repozytorium projektu Code2Logic](http://github.com/wronai/code2logic) na GitHubie!*

Makefile

@@ -325,7 +325,7 @@ status: ## Show library status
 BENCH_SAMPLES := tests/samples
 BENCH_OUTPUT  := examples/output
 BENCH_LIMIT   := 20
-BENCH_FORMATS := yaml toon logicml json markdown csv gherkin
+BENCH_FORMATS := yaml toon logicml json markdown csv gherkin function.toon
 
 # Set BENCH_USE_LLM=1 to run benchmarks with a configured LLM provider
 # (e.g. OpenRouter) instead of offline template mode.
@@ -336,7 +336,7 @@ 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)
+benchmark: benchmark-format benchmark-function-logic 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,6 +360,17 @@ 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

code2logic/benchmarks/common.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 
 from ..generators import CSVGenerator, JSONGenerator, YAMLGenerator
+from ..function_logic import FunctionLogicGenerator
 from ..gherkin import GherkinGenerator
 from ..logicml import LogicMLGenerator
 from ..markdown_format import MarkdownHybridGenerator
@@ -32,6 +33,15 @@ def generate_spec(project: ProjectInfo, fmt: str) -> str:
     if fmt == "gherkin":
         gen = GherkinGenerator()
         return gen.generate(project)
+    if fmt == "function.toon":
+        gen = FunctionLogicGenerator()
+        return gen.generate_toon(
+            project,
+            detail="full",
+            no_repeat_name=True,
+            no_repeat_details=True,
+            include_does=True,
+        )
     if fmt == "csv":
         gen = CSVGenerator()
         return gen.generate(project, detail="full")
@@ -206,6 +216,17 @@ 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.""",
+
+        "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'""",
     }
 
     max_spec = 5000

examples/benchmark_report.py

@@ -84,6 +84,11 @@ def main() -> None:
 
     artifacts: List[Artifact] = [
         Artifact("Format benchmark", out_dir / "benchmark_format.json", "Format comparison across multiple files"),
+        Artifact(
+            "Function-logic format benchmark",
+            out_dir / "benchmark_function_logic.json",
+            "Standalone format benchmark for function-logic TOON (function.toon)",
+        ),
         Artifact("Token benchmark", out_dir / "benchmark_token.json", "Token efficiency comparison"),
         Artifact("Project benchmark", out_dir / "benchmark_project.json", "Project-level benchmark"),
         Artifact("Function benchmark", out_dir / "benchmark_function.json", "Function-level benchmark"),
@@ -104,6 +109,7 @@ def main() -> None:
     ]
 
     fmt = _load_json(out_dir / "benchmark_format.json")
+    flog = _load_json(out_dir / "benchmark_function_logic.json")
     tok = _load_json(out_dir / "benchmark_token.json")
     proj = _load_json(out_dir / "benchmark_project.json")
     fun = _load_json(out_dir / "benchmark_function.json")
@@ -126,6 +132,11 @@ def main() -> None:
     if fmt:
         n, avg, syn, run = _calc_file_summary(fmt)
         lines.append(f"| Format | {n} files | {avg:.1f}% | {syn:.0f}% | {run:.0f}% | {fmt.get('best_format','')} ({fmt.get('best_score',0):.1f}%) |")
+    if flog:
+        n, avg, syn, run = _calc_file_summary(flog)
+        lines.append(
+            f"| Function-logic format | {n} files | {avg:.1f}% | {syn:.0f}% | {run:.0f}% | {flog.get('best_format','')} ({flog.get('best_score',0):.1f}%) |"
+        )
     if tok:
         n, avg, syn, run = _calc_file_summary(tok)
         lines.append(f"| Token | {n} files | {avg:.1f}% | {syn:.0f}% | {run:.0f}% | {tok.get('best_format','')} ({tok.get('best_score',0):.1f}%) |")

examples/benchmark_summary.py

@@ -30,6 +30,7 @@ def main():
 
     files = {
         "Format": os.path.join(out, "benchmark_format.json"),
+        "FuncLogic": os.path.join(out, "benchmark_function_logic.json"),
         "Token": os.path.join(out, "benchmark_token.json"),
         "Project": os.path.join(out, "benchmark_project.json"),
         "Function": os.path.join(out, "benchmark_function.json"),