# CPPTAI

Python framework (standard library only) for a 5‑phase cognitive pipeline, DeepSeek API integration (OpenAI‑compatible), automated benchmarks with CSV/JSON reports, and LaTeX research generation with auto‑loaded tables and plots.

## Overview
- Five‑phase architecture: Entropic segregation → Vertical topology → Cognitive descent → External convergence → Presentation (Phase V).
- Minimal DeepSeek client with `.env` key management and model fallback.
- Benchmarks: accuracy vs baselines (CoT, ToT, GoT, ReAct), diversity (Shannon on clusters), error rates (GSM8K/MATH/AIME), time‑per‑problem; outputs in `benchmarks.csv` and `benchmarks.json`.
- LaTeX research (`research.tex`) using `pgfplotstable`/`pgfplots` to load results directly.

## Requirements
- Python ≥ 3.10.
- No external dependencies; everything uses the standard library.
- Optional: DeepSeek API key for live responses.

## Setup
1. Create a `.env` file at the project root:
   
   ```
   DEEPSEEK_API_KEY=your_key
   ```
   
   Do not share or commit real keys.

2. Main file structure:
   - `src/cpptai/core.py` – 5‑phase orchestrator.
   - `src/cpptai/deepseek_client.py` – DeepSeek API client with `.env` loader.
   - `src/cpptai/benchmarks.py` – execution and metrics, CSV/JSON outputs.
   - `src/cpptai/presentation.py` – Phase V formatting (executive/technical/public).
   - `src/cpptai/types.py` – base types (difficulty, problem blocks).
   - `src/cpptai/env.py` – `.env` loader without dependencies.
   - `src/main.py` – startup CLI.
   - `tests/` – unit tests.
   - `research.tex` – LaTeX document (auto‑loaded charts/tables).

## Quick Start
- Run the main pipeline:
  - Windows PowerShell: `python .\src\main.py`
  - Alternative: `python -m src.main`

- Primary outputs:
  - `ragionamenti.csv` – pipeline artifacts.
  - `memoria.json` – execution state/memory.
  - `benchmarks.csv` and `benchmarks.json` – quantitative results.

## Benchmarks
- Implemented metrics:
  - Accuracy vs baselines: CoT, ToT, GoT, ReAct.
  - Diversity: Shannon entropy over solution clusters (hash embeddings + k‑means).
  - Error rates: GSM8K/MATH/AIME sets (proxy/placeholder if data unavailable).
  - Average time per problem and token counts.
- Execution: run `src/main.py`; benchmarks run automatically and are saved to `benchmarks.csv`/`benchmarks.json`.

## LaTeX Research
- `research.tex` loads `benchmarks.csv` with `pgfplotstable` and generates tables/plots.
- Typical compilation:
  - `pdflatex research.tex`
  - Repeat compilation if needed to update references.
- Requires a LaTeX distribution with `pgfplots`/`pgfplotstable` (e.g., TeX Live/MiKTeX).

## Tests
- Run unit tests:
  - `python -m unittest discover -s tests -p "test_*.py" -q`
- Tests use only the standard library’s `unittest`.

## Security Notes
- Do not commit API keys/secrets.
- The client avoids logging sensitive content and uses fallbacks when no key is present.

## Troubleshooting
- Import errors in tests: ensure `src` is on `PYTHONPATH` or use the commands above; tests already include a local path fix.
- No response from DeepSeek: verify `DEEPSEEK_API_KEY` in `.env` and connectivity.

## Availability
- Repository: https://github.com/fra150/CPPTAI

## Generate Benchmarks and Figures
- Disable external calls if needed: PowerShell `$env:BENCH_DISABLE_EXTERNAL=1; python .\src\main.py`
- Outputs:
  - `benchmarks.csv`, `benchmarks_summary.csv`, `benchmarks.json`
  - `cumulative_accuracy.csv`, `error_by_phase.csv`, `stats_summary.csv`
- Compile LaTeX: `pdflatex research.tex` (twice for references).

## License
- MIT open‑source