Skip to content

Automation foundation model for tiny devices: 2-bit, 8-29 MB, tool calls, ASR, structured extraction and embeddings on phones, wearables, smart homes, robots, cars and microcontrollers.

feat: add type hints to public API (Needle, tool, extract, build_schema, pydantic_schema) (#74)

Yunare Maiac94d256eff6f
diff --git a/needle/__init__.py b/needle/__init__.py
index 7e8a0de..169dea3 100644
--- a/needle/__init__.py
+++ b/needle/__init__.py
@@ -100,7 +100,7 @@ class Needle:
schemas.append(entry)
return schemas
- def complete(self, text, max_new_tokens=256):
+ def complete(self, text: str, max_new_tokens: int = 256) -> dict:
self._bind()
rc = _lib().needle_complete(text.encode("utf-8"), int(max_new_tokens),
self._buffer, len(self._buffer))
@@ -116,7 +116,7 @@ class Needle:
response["confidence"] = None
return response
- def run(self, query, max_steps=8, max_new_tokens=256):
+ def run(self, query: str, max_steps: int = 8, max_new_tokens: int = 256) -> dict:
response = self.complete(query, max_new_tokens)
executed = []
for _ in range(max_steps):
@@ -138,7 +138,7 @@ class Needle:
response["results"] = executed
return response
- def extract(self, text, schema, max_new_tokens=256):
+ def extract(self, text: str, schema: type | dict, max_new_tokens: int = 256) -> object:
return extract(text, schema, max_new_tokens=max_new_tokens)
def reset(self):
@@ -154,7 +154,7 @@ def _jsonable(value):
return str(value)
-def extract(text, schema, system=None, max_new_tokens=256):
+def extract(text: str, schema: type | dict, system: str | None = None, max_new_tokens: int = 256) -> object:
"""One-shot structured extraction: declare `schema` as the only tool and return
the parsed object (a Pydantic instance if `schema` is a model, else a dict).
Re-initializes the shared engine with this single schema."""
diff --git a/needle/agent/tools.py b/needle/agent/tools.py
index be06e1f..2d430e8 100644
--- a/needle/agent/tools.py
+++ b/needle/agent/tools.py
@@ -3,6 +3,7 @@ import inspect
import re
import types
import typing
+from typing import Callable
_JSON_TYPES = {str: "string", int: "integer", float: "number", bool: "boolean",
list: "array", dict: "object"}
@@ -107,7 +108,7 @@ def _parse_doc(doc):
return " ".join(w for w in desc if w).strip(), args
-def build_schema(fn):
+def build_schema(fn: Callable) -> dict:
signature = inspect.signature(fn)
try:
hints = typing.get_type_hints(fn, include_extras=True)
@@ -146,7 +147,7 @@ def _is_pydantic_model(obj):
for base in obj.__mro__)
-def pydantic_schema(model):
+def pydantic_schema(model: type) -> dict:
raw = model.model_json_schema() if hasattr(model, "model_json_schema") else model.schema()
parameters = {"type": "object", "properties": raw.get("properties", {})}
for key in ("required", "$defs", "definitions"):
@@ -159,6 +160,6 @@ def pydantic_schema(model):
return out
-def tool(fn):
+def tool(fn: Callable) -> Callable:
fn._needle_tool = build_schema(fn)
return fn