Metadata-Version: 2.4
Name: IncludeCPP
Version: 3.3.4
Summary: Professional C++ Python bindings with type-generic templates, pystubs and native threading
Home-page: https://github.com/includecpp/includecpp
Author: IncludeCPP Team
Author-email: IncludeCPP Team <contact@includecpp.dev>
License: MIT
Project-URL: Homepage, https://github.com/includecpp/includecpp
Project-URL: Documentation, https://includecpp.readthedocs.io
Project-URL: Repository, https://github.com/includecpp/includecpp
Project-URL: Bug Tracker, https://github.com/includecpp/includecpp/issues
Keywords: c++,python,bindings,pybind11,template,performance,threading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pybind11>=2.11.0
Requires-Dist: click>=8.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: requests>=2.28.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# IncludeCPP

Write C++ code, use it in Python. Auto-generates pybind11 bindings.

```bash
pip install IncludeCPP
```

# First Steps

## Project Setup

```bash
includecpp init
```

Creates:
- `cpp.proj` - project configuration
- `include/` - your C++ source files
- `plugins/` - generated binding definitions

## Write C++ Code

Put your code in `namespace includecpp`:

```cpp
// include/fast_list.cpp
#include <vector>

namespace includecpp {

class FastList {
public:
    void append(int val) { data.push_back(val); }
    int get(int i) { return data[i]; }
private:
    std::vector<int> data;
};

int add(int a, int b) { return a + b; }

}  // namespace includecpp
```

The parser only scans code inside `namespace includecpp`. Everything else is ignored.

## Generate Bindings

```bash
includecpp plugin fast_list include/fast_list.cpp
```

This runs a C++ parser that:
1. Scans your source files for classes, methods, functions
2. Extracts signatures, return types, parameter names
3. Generates `plugins/fast_list.cp` with binding instructions

## Build

```bash
includecpp rebuild
```

Compiles your C++ into a Python extension module (`.pyd` on Windows, `.so` on Linux/Mac).

## Use in Python

```python
from includecpp import fast_list

my_list = fast_list.FastList()
my_list.append(42)
print(fast_list.add(1, 2))  # 3
```

Alternative syntax:

```python
from includecpp import CppApi

api = CppApi()
fast_list = api.include("fast_list")
```

# How to Start

## Minimal Example

```bash
# 1. Create project
mkdir myproject && cd myproject
includecpp init

# 2. Write C++ (include/math.cpp)
cat > include/math.cpp << 'EOF'
namespace includecpp {
    int square(int x) { return x * x; }
}
EOF

# 3. Generate plugin
includecpp plugin math include/math.cpp

# 4. Build
includecpp rebuild

# 5. Use
python -c "from includecpp import math; print(math.square(7))"
```

## Development Workflow

For active development, use `auto`:

```bash
includecpp auto math
```

This regenerates the `.cp` file from source and rebuilds in one command.

For fastest iteration:

```bash
includecpp rebuild --fast
```

Skips unchanged files. ~0.4s when nothing changed.

# How IncludeCPP Works

## Architecture

```
Your C++ Source            Plugin File (.cp)           Python Module
include/math.cpp    --->   plugins/math.cp     --->    math.cpXXX.pyd
     ^                           ^                          ^
     |                           |                          |
  C++ parser              Binding config             pybind11 compiled
  extracts API            (editable)                 extension
```

## The Parser

The C++ parser (`parser.cpp`) runs as a compiled executable. It:

1. Tokenizes your C++ source files
2. Identifies the `namespace includecpp` block
3. Extracts:
   - Class names and inheritance
   - Method signatures (name, return type, parameters)
   - Function signatures
   - Template instantiations
   - Const/static qualifiers
4. Outputs structured binding instructions to `.cp` files

## Plugin Files (.cp)

The `.cp` format is a declarative binding specification:

```
SOURCE(math.cpp) math

PUBLIC(
    math CLASS(Calculator) {
        CONSTRUCTOR()
        CONSTRUCTOR(int)
        METHOD(add)
        METHOD_CONST(getValue)
        FIELD(value)
    }

    math FUNC(square)
    math TEMPLATE_FUNC(maximum) TYPES(int, float, double)
)
```

Key directives:
- `SOURCE(file.cpp) module_name` - links source to module
- `PUBLIC(...)` - defines public bindings
- `CLASS(Name)` - expose a class
- `STRUCT(Name)` - expose a struct
- `FUNC(name)` - expose a free function
- `METHOD(name)` - expose a class method
- `METHOD_CONST(name, signature)` - for overloaded methods
- `TEMPLATE_FUNC(name) TYPES(...)` - instantiate template
- `CONSTRUCTOR(args)` - expose constructor
- `FIELD(name)` - expose member variable
- `DEPENDS(mod1, mod2)` - declare module dependencies

## Build System

The build manager:

1. Reads `cpp.proj` configuration
2. Parses all `.cp` files in `plugins/`
3. Generates pybind11 binding code
4. Compiles using CMake with detected compiler (MSVC, GCC, Clang)
5. Places output in `~/.includecpp/builds/` (not in your project)
6. Creates a registry so Python can find modules

Caching layers:
- **Object files**: Only recompile changed `.cpp` files
- **Generator cache**: Compiler/CMake detection runs once
- **SHA256 hashes**: Skip unchanged modules entirely

# CLI Reference

Use `includecpp <command> --help` for details.

| Command | Description |
|---------|-------------|
| `init` | Create project structure |
| `plugin <name> <files>` | Generate .cp from C++ sources |
| `auto <plugin>` | Regenerate .cp and rebuild |
| `auto --all` | Regenerate and rebuild all plugins |
| `auto --all -x <name>` | All plugins except specified |
| `fix <module>` | Analyze C++ code for issues |
| `fix --all` | Analyze all modules |
| `fix --undo` | Revert last fix changes |
| `fix --ai <module>` | AI-enhanced code analysis |
| `ai key <key>` | Set OpenAI API key |
| `ai enable` | Enable AI features |
| `ai disable` | Disable AI features |
| `ai model --list` | List available models |
| `ai model set <name>` | Set active model |
| `ai --info` | Show AI configuration and usage |
| `ai optimize <module>` | AI code optimization |
| `ai optimize --agent "<task>"` | Custom AI task |
| `ai ask "<question>"` | Ask about project with full context |
| `ai ask "<question>" <module>` | Ask about specific module |
| `ai edit "<task>"` | Edit code with AI assistance |
| `ai edit "<task>" --think2` | Thorough edit mode |
| `ai undo` | Restore files after AI changes |
| `rebuild` / `build` | Compile all modules |
| `get <module>` | Show module API (classes, methods, functions) |
| `install <name>` | Install community module |
| `update` | Update IncludeCPP |
| `bug` | Report an issue |
| `--doc` | Show documentation |
| `--changelog` | Show latest version changelog |
| `cppy convert <files> --cpp` | Convert Python to C++ |
| `cppy convert <files> --py` | Convert C++ to Python |
| `cppy convert <files> --cpp --no-h` | Convert without header |
| `cppy convert <files> --cpp --ai` | AI-assisted conversion |
| `cppy analyze <files>` | Analyze code structure |
| `cppy types` | Show type mapping tables |

## Build Flags

```bash
includecpp rebuild                  # Standard build
includecpp rebuild --clean          # Full rebuild, clear caches
includecpp rebuild --fast           # Fast incremental (~0.4s if unchanged)
includecpp rebuild --verbose        # Show compiler output
includecpp rebuild -m crypto        # Build specific module only
includecpp rebuild -j 8             # Use 8 parallel jobs
includecpp rebuild --keep           # Keep generator between builds
includecpp rebuild --no-incremental # Force full recompilation
includecpp rebuild --this           # Build current directory as module
```

## Fast Mode

`--fast` enables object file caching:

| Scenario | Time |
|----------|------|
| No changes | ~0.4s |
| Source changed | ~5-10s |
| Full rebuild | ~30s |

Clear caches with `--clean`.

## Incompatible Flag Combinations

| Flags | Reason |
|-------|--------|
| `--fast` + `--no-incremental` | Fast mode requires incremental |
| `--fast` + `--clean` | Fast uses caches, clean deletes them |
| `--fast` + `--this` | Not supported together |
| `--incremental` + `--no-incremental` | Contradictory |

# Advanced Features

## AI Integration

IncludeCPP integrates with OpenAI for intelligent code analysis and optimization.

### Setup

```bash
includecpp ai key sk-your-api-key-here
includecpp ai enable
```

### Available Models

```bash
includecpp ai model --list
```

- `gpt-5` (default) - 256k context
- `gpt-5-nano` - 32k context, fast
- `gpt-4o` - 128k context
- `gpt-4-turbo` - 128k context
- `gpt-3.5-turbo` - 16k context

### AI-Enhanced Fix

```bash
includecpp fix --ai mymodule
includecpp fix --ai --all
```

Sends source files to AI for analysis, suggests improvements while preserving all existing functions.

### AI Optimize

```bash
includecpp ai optimize mymodule                        # Optimize module sources
includecpp ai optimize --file src/utils.cpp            # Optimize specific files
includecpp ai optimize --agent mymodule "add SIMD"     # Custom task
```

### AI Ask

Ask questions about your project with full context awareness:

```bash
includecpp ai ask "where is collision detection?"              # Search all modules
includecpp ai ask "how does chunk generation work?" chunk_utils  # Specific module
includecpp ai ask "explain the biome system" --file include/biomes.cpp
includecpp ai ask "list all public methods" --all -x tests      # All except tests
```

Supports: module name, --file, --all, -x/--exclude

### AI Edit

Edit code with AI assistance:

```bash
includecpp ai edit "add logging to all methods" collision
includecpp ai edit "optimize the loop" --file include/utils.cpp
includecpp ai edit "add error handling" --all --think2          # Thorough mode
```

Flags:
- `--file` - specific files
- `--all` - all modules
- `-x/--exclude` - exclude modules
- `--think2` - thorough analysis (more tokens)

### AI Generate (Super Assistant)

The most powerful AI command - a full assistant with file operations and command execution.

```bash
# Basic usage
includecpp ai generate "add error handling to all functions" --file mymodule.cp

# Create new module from scratch
includecpp ai generate "fast SIMD math library" --t-new-module simd_math

# Planning mode (search, analyze, then execute)
includecpp ai generate "refactor for better performance" --t-plan --think2

# With Python file (auto-detect module usage)
includecpp ai generate "update api methods" --file mymod.cp --python main.py

# Full context mode
includecpp ai generate "comprehensive optimization" --t-max-context --think3
```

**Flags:**
| Flag | Description |
|------|-------------|
| `--file <path>` | Add files (multiple allowed). .cp files auto-resolve to source |
| `--think/2/3` | Extended context and planning |
| `--websearch` | Enable web research |
| `--t-max-context` | No context reduction |
| `--t-plan` | Search/grep before executing |
| `--t-new-module <name>` | Create new module (cpp + plugin + build) |
| `--python <file.py>` | Include Python file, auto-detect modules |
| `--confirm` | Skip confirmations |

### AI Tools

List available tools for the generate command:

```bash
includecpp ai tools
```

Available tools: READ_FILE, WRITE_FILE, EDIT_FILE, DELETE_FILE, CREATE_FOLDER, LIST_FOLDER, SEARCH_FILES, GREP, RUN_CMD, INCLUDECPP_CMD

### Build Error Analysis

When AI is enabled and `rebuild` fails, the build error is automatically analyzed:
- Root cause identification
- Code fix suggestions
- Prevention tips

### Configuration

```bash
includecpp ai --info          # Show status, model, usage stats
includecpp ai disable         # Disable without removing key
```

API key stored in `~/.includecpp/.secret`.

## Overloaded Methods

Specify the signature to disambiguate:

```
MODULE CLASS(Circle) {
    METHOD_CONST(intersects, const Circle&)
    METHOD_CONST(intersects, const Rect&)
}
```

## Template Instantiation

```
MODULE TEMPLATE_FUNC(maximum) TYPES(int, float, double)

MODULE STRUCT(Point) TYPES(int, float) {
    FIELD(x)
    FIELD(y)
}
```

Generates `maximum_int`, `maximum_float`, `maximum_double` and `Point_int`, `Point_float`.

## Module Dependencies

```
DEPENDS(math_utils, geometry)
```

Ensures dependent modules build first.

## VSCode IntelliSense

Generates `.pyi` stub files for autocomplete. Enable in `cpp.proj`:

```json
{
  "CPI-IntelliSense": true
}
```

## CPPY Code Conversion

Convert code between Python and C++ with full support for classes, functions, and type hints.

### Python to C++

```bash
includecpp cppy convert math_utils.py --cpp
includecpp cppy convert data.py --cpp --no-h  # Skip header
includecpp cppy convert src/*.py --cpp -o include/
```

Converts Python code to optimized C++ with:
- Type hints mapped to C++ types (int, str -> std::string, List -> std::vector)
- Classes with constructors, methods, fields
- Functions with proper signatures
- List comprehensions to STL algorithms
- Exception handling to try/catch

### C++ to Python

```bash
includecpp cppy convert utils.cpp --py
includecpp cppy convert mymodule.cp --py  # Auto-resolve SOURCE()
```

Converts C++ to Python with:
- STL types mapped to Python equivalents
- Classes with type hints
- Methods become class methods with self
- Structs become dataclasses

### AI-Assisted Conversion

```bash
includecpp cppy convert complex_lib.py --cpp --ai
includecpp cppy convert advanced.cpp --py --ai -v
```

The `--ai` flag enables intelligent conversion with:
- Section-by-section analysis and processing
- Automatic `--think2` context level
- Comprehensive rulebase for precise conversions
- pybind11 wrappers for Python features without C++ equivalents:
  - Generators -> callback pattern / py::iterator
  - Async/await -> std::async / std::future
  - Context managers -> RAII pattern
  - Duck typing -> templates with concepts
- Reports API changes to user
- Fallback to standard conversion if AI unavailable

**Workaround Examples:**
| Python Feature | C++ Workaround |
|----------------|----------------|
| `yield` | Callback pattern or py::iterator |
| `async/await` | std::async + std::future |
| `with` context | RAII ScopedResource class |
| List comprehension | transform_to_vector template |
| Dict comprehension | transform_to_map template |
| Dynamic attributes | py::object |

### Analyze Code

```bash
includecpp cppy analyze math.py           # View structure
includecpp cppy analyze utils.cpp --json  # JSON output
```

### Type Mapping

```bash
includecpp cppy types  # Show conversion tables
```

| Python | C++ |
|--------|-----|
| int | int |
| float | double |
| str | std::string |
| bool | bool |
| List[T] | std::vector<T> |
| Dict[K,V] | std::unordered_map<K,V> |
| Optional[T] | std::optional<T> |
| Tuple[...] | std::tuple<...> |

# Configuration

## cpp.proj

```json
{
  "project": "MyProject",
  "include": "/include",
  "plugins": "/plugins",
  "compiler": {
    "standard": "c++17",
    "optimization": "O3"
  }
}
```

Options:
- `project` - project name
- `include` - C++ source directory
- `plugins` - plugin file directory
- `compiler.standard` - C++ standard (c++11, c++14, c++17, c++20)
- `compiler.optimization` - optimization level (O0, O1, O2, O3)

# Requirements

- Python 3.8+
- C++ compiler (g++, clang++, MSVC)
- pybind11 (installed automatically)
- CMake (for build generation)

# Changelog

## v3.3.4
- New `--ai` flag for `cppy convert` - AI-assisted code conversion
- Automatic `--think2` context for intelligent conversion
- Comprehensive rulebase for Python <-> C++ translations
- pybind11 wrappers for unconvertible Python features:
  - Generators -> callback pattern / py::iterator
  - Async/await -> std::async / std::future
  - Context managers -> RAII pattern
  - List/dict comprehensions -> helper templates
- API change detection and user notification
- Section-by-section analysis and conversion
- Graceful fallback to standard conversion if AI unavailable

## v3.3.3
- Fixed `ai generate` loop bug creating duplicate file changes
- Fixed unused variable warning in cppy_converter.py
- Improved deduplication of file changes in AI generate

## v3.3.2
- Fixed version display bug in `includecpp update --version`
- New `cppy convert` command for Python <-> C++ code conversion
- Convert Python to optimized C++ with `--cpp` flag
- Convert C++ to Python with `--py` flag
- `--no-h` flag to skip header generation
- `cppy analyze` command to inspect code structure
- `cppy types` command to view type mapping tables
- Full support for classes, structs, functions, templates

## v3.3.1
- Fixed `ai generate --t-new-module` not creating files (tool parser bug)
- Fixed `ai generate --t-plan` not executing after planning (now runs automatically)
- Added JSON-style tool call parsing as fallback
- Improved prompts with explicit format instructions

## v3.3.0
- New `ai generate "<task>"` - Super assistant with tool execution
- New `ai tools` - List available AI tools
- Tools: READ_FILE, WRITE_FILE, EDIT_FILE, DELETE_FILE, CREATE_FOLDER, LIST_FOLDER, SEARCH_FILES, GREP, RUN_CMD, INCLUDECPP_CMD
- `--t-max-context` - Full context mode
- `--t-plan` - Planning mode with search/grep before executing
- `--t-new-module <name>` - Create new module from scratch (cpp + plugin + build)
- `--python <file.py>` - Include Python files, auto-detect module usage
- Improved `ai edit` parser for complex tasks (better fallback detection)
- Fixed "No changes needed" false positives in `ai edit`

## v3.2.5
- Fixed timeout issue for `ai ask` and `ai edit` with `--think2`/`--think3` flags
- `--think3` now has no timeout limit for complex operations
- `--think2` timeout increased to 7 minutes
- AI can now ask clarifying questions during `--think2`/`--think3` operations

## v3.2.4
- Fixed UTF-16/BOM encoding error in plugin command (source file reading)

## v3.2.3
- Fixed FIELD() syntax: now outputs `FIELD(name)` not `FIELD(type, name)`
- Fixed documentation: PUBLIC() not PUBLIC:
- Fixed AI context to match actual .cp syntax

## v3.2.2
- Plugin command now detects comma-separated field declarations (e.g., `double x, y, z;` generates 3 FIELD entries)
- Fixed `ai optimize` timeout for multi-file operations (increased to 5 minutes)
- AI `ask` now extracts relevant CLI implementation when asking about commands/flags

## v3.2.1
- Fixed encoding error in `ai ask` output on Windows (GPT Unicode characters like non-breaking hyphen)

## v3.2.0
- AI context limits: 3K (standard), 5K (`--think`), 10K (`--think2`), 25K (`--think3`) lines
- AI now has full IncludeCPP knowledge (namespace requirements, .cp format, common errors)
- New `--think` flag for short planning mode (5K context)
- New `--websearch` flag for web research (requires Brave API)
- Daily token limit: 220K default, auto-resets at midnight
- New commands: `ai limit`, `ai limit set <N>`, `ai limit get`
- Fixed "No changes needed" issue in `ai edit` (now more assertive)
- Improved `fix --ai` error detection with line numbers and error categorization
- Settings GUI now shows daily limit option
- Build info from AppData included in AI context

## v3.1.10
- Fixed diff view encoding on Windows (replaced Unicode box chars with ASCII)

## v3.1.9
- AI commands now show colored diff before confirmation prompts
- Renamed `--auto` to `--confirm` for AI confirmation skipping (`fix --confirm`, `ai edit --confirm`, `ai optimize --confirm`)
- Fixed Windows encoding errors (`'charmap' codec` issue)
- All file operations now use UTF-8 encoding explicitly

## v3.1.8
- `--think2` and `--think3` flags added to `ai ask` and `ai edit` commands
- Extended context and web research support for all AI commands
- Fixed `ai undo` command error

## v3.1.7
- `--auto-ai` flag for `rebuild`, `build`, and `auto` commands
- Auto-fix build errors with AI and retry automatically (max 3 attempts)
- AI has CLI access (can run `includecpp plugin <module>` for .cp regeneration)
- `--think2` for extended context (500 lines per file, careful analysis)
- `--think3` for max context + web research + planning mode (requires Brave API)
- `includecpp ai token --brave <TOKEN>` for Brave Search API
- `includecpp settings` opens PyQt6 settings panel (pip install PyQt6)
- Changes from `--auto-ai` can be reverted with `includecpp ai undo`

---

MIT License | v3.3.4 | [GitHub](https://github.com/liliassg/IncludeCPP)
