k8math 0.1.0__tar.gz

k8math-0.1.0/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright © 2026 Ramiro Santa Ana Anguiano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

k8math-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: k8math
+Version: 0.1.0
+Summary: Generate math word problems with AI
+Keywords: k8math,ai,math,math word problem,generator
+Author: ram
+Author-email: ram <hi@colima.press>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Requires-Dist: anthropic>=1.2.0
+Requires-Dist: simpleeval>=1.0.7
+Maintainer: ram
+Maintainer-email: ram <hi@colima.press>
+Requires-Python: >=3.12
+Project-URL: Repository, https://gitlab.com/perritotuerto/codigo/k8math
+Project-URL: Changelog, https://gitlab.com/perritotuerto/codigo/k8math/-/blob/main/CHANGELOG.md
+Project-URL: Releases, https://gitlab.com/perritotuerto/codigo/k8math/-/releases
+Description-Content-Type: text/markdown
+
+# K8Math
+
+Generate math word problems with AI.
+
+**NOTE**. Requires Anthropic API key.
+
+## Usage
+
+Generate wit CLI:
+
+```
+uv run k8math -k $ANTHROPIC_API_KEY -l english "3 + 4 = 7"
+```
+
+Print help:
+
+```
+uv run k8math -h
+```
+
+Import as a module:
+
+```
+import os
+from k8math import K8Math
+
+k8m = K8Math(
+  expressions=["3 + 4 = 7"],
+  api_key=os.environ.get("ANTHROPIC_API_KEY"),
+  language="english",
+)
+k8m.generate()
+```
+
+## Development
+
+Clone:
+
+```
+git clone TODO
+```
+
+Format:
+
+```
+uv run ruff format .
+uv run isort .
+```
+
+Check:
+
+```
+uv run ruff check .
+```
+
+Test:
+
+```
+uv run python -m pytest -s --durations 0
+```
+
+Tag version:
+
+```
+git tag v1.0.0
+git push origin tag v1.0.0
+```

k8math-0.1.0/README.md

@@ -0,0 +1,67 @@
+# K8Math
+
+Generate math word problems with AI.
+
+**NOTE**. Requires Anthropic API key.
+
+## Usage
+
+Generate wit CLI:
+
+```
+uv run k8math -k $ANTHROPIC_API_KEY -l english "3 + 4 = 7"
+```
+
+Print help:
+
+```
+uv run k8math -h
+```
+
+Import as a module:
+
+```
+import os
+from k8math import K8Math
+
+k8m = K8Math(
+  expressions=["3 + 4 = 7"],
+  api_key=os.environ.get("ANTHROPIC_API_KEY"),
+  language="english",
+)
+k8m.generate()
+```
+
+## Development
+
+Clone:
+
+```
+git clone TODO
+```
+
+Format:
+
+```
+uv run ruff format .
+uv run isort .
+```
+
+Check:
+
+```
+uv run ruff check .
+```
+
+Test:
+
+```
+uv run python -m pytest -s --durations 0
+```
+
+Tag version:
+
+```
+git tag v1.0.0
+git push origin tag v1.0.0
+```

k8math-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "k8math"
+version = "0.1.0"
+description = "Generate math word problems with AI"
+readme = "README.md"
+keywords = [
+    "k8math",
+    "ai",
+    "math",
+    "math word problem",
+    "generator",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Education",
+]
+license = "MIT"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.12"
+dependencies = [
+    "anthropic>=1.2.0",
+    "simpleeval>=1.0.7",
+]
+
+[[project.authors]]
+name = "ram"
+email = "hi@colima.press"
+
+[[project.maintainers]]
+name = "ram"
+email = "hi@colima.press"
+
+[project.scripts]
+k8math = "k8math.cli:main"
+
+[project.urls]
+Repository = "https://gitlab.com/perritotuerto/codigo/k8math"
+Changelog = "https://gitlab.com/perritotuerto/codigo/k8math/-/blob/main/CHANGELOG.md"
+Releases = "https://gitlab.com/perritotuerto/codigo/k8math/-/releases"
+
+[dependency-groups]
+dev = [
+    "isort>=8.0.1",
+    "pytest>=9.0.3",
+    "ruff>=0.15.11",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.13"]
+build-backend = "uv_build"

k8math-0.1.0/pyproject.toml.orig

@@ -0,0 +1,36 @@
+[project]
+name = "k8math"
+version = "0.1.0"
+description = "Generate math word problems with AI"
+readme = "README.md"
+authors = [{ name = "ram", email = "hi@colima.press" }]
+maintainers = [{ name = "ram", email = "hi@colima.press" }]
+keywords = ["k8math", "ai", "math", "math word problem", "generator"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Education",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Education",
+]
+license = "MIT"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.12"
+dependencies = ["anthropic>=1.2.0", "simpleeval>=1.0.7"]
+
+[dependency-groups]
+dev = ["isort>=8.0.1", "pytest>=9.0.3", "ruff>=0.15.11"]
+
+[project.scripts]
+k8math = "k8math.cli:main"
+
+[project.urls]
+Repository = "https://gitlab.com/perritotuerto/codigo/k8math"
+Changelog = "https://gitlab.com/perritotuerto/codigo/k8math/-/blob/main/CHANGELOG.md"
+Releases = "https://gitlab.com/perritotuerto/codigo/k8math/-/releases"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.13"]
+build-backend = "uv_build"

k8math-0.1.0/src/k8math/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+  return "Hello from k8math!"

k8math-0.1.0/src/k8math/cli.py

@@ -0,0 +1,67 @@
+import argparse
+from pathlib import Path
+
+from k8math.core import K8Math
+
+
+def main() -> None:
+  parser = argparse.ArgumentParser(
+    prog=Path(__file__).stem,
+    description="Generate math word problems with AI",
+    epilog="hi@colima.press",
+  )
+  parser.add_argument(
+    "math_expressions",
+    help="one or more math expressions; e.g., '1 * 2 / 2 = 1'",
+    metavar="EXP",
+    nargs="+",
+  )
+  parser.add_argument(
+    "-k",
+    "--key",
+    help="Anthropic API key",
+    metavar="KEY",
+    required=True,
+  )
+  parser.add_argument(
+    "-l",
+    "--language",
+    help="problem language",
+    metavar="LANG",
+    choices=["english", "spanish"],
+  )
+  parser.add_argument(
+    "-s",
+    "--subject",
+    help="one or more subjects",
+    metavar="SUBJ",
+    action="append",
+  )
+  parser.add_argument(
+    "-o",
+    "--object",
+    help="one or more objects",
+    metavar="OBJ",
+    action="append",
+  )
+  parser.add_argument(
+    "-v",
+    "--verb",
+    help="one or more verbs",
+    metavar="VERB",
+    action="append",
+  )
+  args = parser.parse_args()
+  k8m = K8Math(
+    expressions=args.math_expressions,
+    api_key=args.key,
+    language=args.language,
+    subjects=args.subject,
+    objects=args.object,
+    verbs=args.verb,
+  )
+  k8m.generate()
+
+
+if __name__ == "__main__":
+  main()

k8math-0.1.0/src/k8math/core.py

@@ -0,0 +1,172 @@
+import io
+import json
+import tokenize
+
+from anthropic import Anthropic
+from simpleeval import simple_eval
+
+
+class K8Math:
+  MODEL = "claude-haiku-4-5-20251001"  # cheapest with structured-output
+  SCHEMA = {  # noqa: RUF012
+    "type": "array",
+    "items": {
+      "type": "object",
+      "properties": {
+        "text": {"type": "string"},
+        "index": {"type": "integer"},
+        "num": {"type": "number"},
+        "op": {"enum": ["+", "-", "*", "/"]},
+        "par": {"enum": ["(", ")"]},
+        "subject": {"type": "string"},
+        "subject_in_text": {"type": "string"},
+        "object": {"type": "string"},
+        "object_in_text": {"type": "string"},
+        "verb": {"type": "string"},
+        "verb_in_text": {"type": "string"},
+      },
+      "additionalProperties": False,
+    },
+  }
+  SYSTEM_PROMPT = """
+You write short kinder and elementary-school (K-8) word problems encoded as a
+JSON array.
+
+Rules:
+- Reproduce every given math token exactly (same num/op/par value, same index).
+- NEVER alter, add, or remove a math token.
+- Every object except "par" objects must have a non-empty "text".
+- "par" objects never have "text" and never appear in the narrated sentence.
+- "subject", "object" and "verb" objects have to appear at least once in "text"
+- Every "*_in_text" field must be a literal substring of that same object's
+  "text".
+- The verb may be conjugated freely in "verb_in_text" regardless of the form
+  given in "verb".
+- If the change described is small or trivial (like going from 1 to 2), phrase
+  it the way someone would naturally say it in conversation — don't reach for
+  formal math language like 'doubles' or 'multiplies by' when a simpler phrase
+  fits better.
+- MUST make sense in real world and it should not seem like a verbose math
+  expression.
+- ATTACH every number to a concrete, countable noun the reader can picture.
+- ALWAYS write naturally and for a kid.
+- ALWAYS leave the punctuation, such as periods and commas, at the end of
+  "text".
+- ALWAYS be clear and specific in what you ask.
+- NEVER use the name of the operation.
+- NEVER use dashes nor semicolons.
+- NEVER hide a quantity behind a vague pronoun like 'it', 'them', or
+  'everything'.
+- NEVER use the name of the math operator in the word problem.
+- NEVER give the result and answer away.
+- Respond with ONLY the JSON array. No explanation, no markdown, no code
+  fences.
+
+Example 1:
+Math tokens (reproduce exactly, with its order in "index"):
+("9", "-", "7" "=", "2")
+
+Output:
+[
+  {"text":"Rosa","subject":"Rosa","subject_in_text":"Rosa"},
+  {"text":"has","verb":"have","verb_in_text":"has"},
+  {"text":"9","index":0,"num":9},
+  {"text":"apples.","object":"apple","object_in_text":"apples"},
+  {"text":"She","subject":"Rosa","subject_in_text":"She"},
+  {"text":"ate","index":1,"op":"-","verb":"eat","verb_in_text":"ate"},
+  {"text":"7.","index":2,"num":7},
+  {"text":"How many does she have left?"}
+]
+
+Example 2:
+Math tokens (reproduce exactly, with its order in "index"):
+("(", "3", "+", "7", ")", "/", "5", "=", "2")
+
+Output:
+[
+  {"text":"Tom","subject":"Tom","subject_in_text":"Tom"},
+  {"index":0,"par":"("},
+  {"text":"buys","verb":"buy","verb_in_text":"buys"},
+  {"text":"3","index":1,"num":3},
+  {"text":"boxes","object":"box","object_in_text":"boxes"},
+  {"text":"and","index":2,"op":"+"},
+  {"text":"7","index":3,"num":7},
+  {"text":"more boxes,","object":"box","object_in_text":"boxes"},
+  {"index":4,"par":")"},
+  {"text":"then splits them evenly among","index":5,"op":"/"},
+  {"text":"5","index":6,"num":5},
+  {"text":"friends. How many boxes does each friend get?"}
+]
+"""
+  USER_PROMPT = """
+Math tokens (reproduce exactly, with its order in "index"): %s
+
+Now produce the JSON array for a new, different word problem in
+%s using these exact math tokens.
+"""
+
+  def __init__(  # noqa: PLR0913,PLR0917
+    self,
+    expressions: list[str] | tuple[str],
+    api_key: str,
+    language: str | None = None,
+    subjects: list | None = None,
+    objects: list | None = None,
+    verbs: list | None = None,
+  ):
+    self.exps = [self._get_exp(exp) for exp in expressions]
+    self._key = api_key
+    self.lang = language if language else "english"
+    self.subjects = subjects
+    self.objects = objects
+    self.verbs = verbs
+
+  def _get_exp(self, raw_exp: str) -> tuple:
+    if "=" not in raw_exp:
+      raise ValueError(f"No equality symbol found in '{raw_exp}'")
+    tokens = tokenize.generate_tokens(io.StringIO(raw_exp).readline)
+    tokens = tuple(t.string for t in tokens if t.string.strip())
+    py_str = "".join(tuple("==" if t == "=" else t for t in tokens))
+    if not simple_eval(py_str):
+      raise ValueError(f"Invalid result '{raw_exp}'")
+    return tokens
+
+  def _get_prompt(self, exp: tuple, lang: str) -> str:
+    prompt = f"\n{exp}"
+    if self.subjects or self.objects or self.verbs:
+      prompt += "\n\nWith this content:"
+    if self.subjects:
+      prompt += f"\n- subjects: {self.subjects}"
+    if self.objects:
+      prompt += f"\n- objects: {self.objects}"
+    if self.verbs:
+      prompt += f"\n- verbs: {self.verbs}"
+    return self.USER_PROMPT % (prompt, lang)
+
+  def _print(self, tokens: list, math_expression: tuple):
+    problem = " ".join([t.get("text", "").strip() for t in tokens])
+    answer = " ".join(math_expression)
+    print(f"{problem}\n\nAnswer: {answer}")
+
+  def generate(self, language: str | None = None):
+    self.problems = []
+    lang = language if language else self.lang
+    client = Anthropic(api_key=self._key)
+    for exp in self.exps:
+      user_prompt = self._get_prompt(exp, lang)
+      response = client.messages.create(
+        model=self.MODEL,
+        max_tokens=1024,
+        system=self.SYSTEM_PROMPT,
+        messages=[{"role": "user", "content": user_prompt}],
+        output_config={
+          "format": {
+            "type": "json_schema",
+            "schema": self.SCHEMA,
+          }
+        },
+      )
+      text_block = next(b for b in response.content if b.type == "text")
+      parsed = json.loads(text_block.text)
+      self._print(parsed, exp)
+      self.problems.append(parsed)