Metadata-Version: 2.4
Name: callforge-ai
Version: 0.1.0
Summary: Reliable schema-based function calling for local language models.
Author: Ayoub Benich
License-Expression: MIT
Project-URL: Documentation, https://github.com/USERNAME/callforge-ai#readme
Project-URL: Source, https://github.com/USERNAME/callforge-ai
Project-URL: Issues, https://github.com/USERNAME/callforge-ai/issues
Keywords: llm,function-calling,tool-calling,constrained-decoding,local-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.0
Provides-Extra: huggingface
Requires-Dist: torch>=2.1; extra == "huggingface"
Requires-Dist: transformers>=4.44; extra == "huggingface"
Requires-Dist: huggingface-hub>=0.24; extra == "huggingface"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# CallForge

**Reliable schema-based function calling for local language models.**

CallForge selects a declared function, extracts type-safe parameters from a
natural-language request, and uses constrained decoding only when a choice is
ambiguous. It is designed for local models and works with any model that
implements two small methods:

```python
encode(text)
get_logits_from_input_ids(input_ids)
```

## Installation

Install the lightweight core:

```bash
pip install callforge-ai
```

Install the ready-to-use Hugging Face adapter:

```bash
pip install "callforge-ai[huggingface]"
```

## Python usage

```python
from callforge import FunctionCaller, Function
from callforge.adapters.huggingface import HuggingFaceModel

functions = [
    Function.model_validate(
        {
            "name": "fn_add_numbers",
            "description": "Add two numbers together.",
            "parameters": {
                "a": {"type": "number"},
                "b": {"type": "number"},
            },
            "returns": {"type": "number"},
        }
    )
]

model = HuggingFaceModel("Qwen/Qwen3-0.6B", device="cpu")
caller = FunctionCaller(model=model, functions=functions)
result = caller.call("What is the sum of 2 and 3?")

print(result.model_dump())
# {'prompt': 'What is the sum of 2 and 3?',
#  'name': 'fn_add_numbers',
#  'parameters': {'a': 2.0, 'b': 3.0}}
```

## JSON directory usage

Input directory:

```text
data/input/
├── function_calling_tests.json
└── functions_definition.json
```

Run:

```bash
callforge \
  --input data/input \
  --output data/output \
  --model Qwen/Qwen3-0.6B \
  --device cpu
```

The result is written to:

```text
data/output/function_calling_results.json
```

## Use another local model

You do not need Transformers. Pass any object with the required interface:

```python
class MyModel:
    def encode(self, text: str):
        ...

    def get_logits_from_input_ids(self, input_ids: list[int]) -> list[float]:
        ...

caller = FunctionCaller(model=MyModel(), functions=functions)
```

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest
python -m build
python -m twine check dist/*
```

## Security note

Only enable `--trust-remote-code` for model repositories you trust.

## License

MIT
