polya

Polya gives AI agents operations for cipher decoding, symbolic constraints, automata and exact candidate checks. Python, a JSON CLI and a stdio MCP server share the same contracts. The agent picks the strategy; each operation does one bounded computation and says what its result covers.

See it work

Three short CLI recordings, using synthetic inputs and the base install.

Find an operation and inspect its input. Search for Vigenere, then ask for a ready-to-run JSON example.

Decode a supplied cipher. With key LEMON, LXFOPVEFRNHR becomes ATTACKATDAWN. The result includes source offsets and the transformation's scope.

Enumerate a finite constraint system. Two binary variables must differ. Polya returns both assignments and reports COMPLETE after exhausting this system.

Copy the commands or re-record the demos.

Quick start

python -m pip install "git+https://github.com/Amal-David/polya.git"

The distribution will be polya-puzzles on PyPI; publication is pending. Optional extras (images, Z3, CP-SAT, AALpy) are listed in getting started.

polya find vigenere --limit 1
polya inspect cipher.polyalphabetic --example
polya run cipher.polyalphabetic --result-only \
  --json '{"text":"LXFOPVEFRNHR","key":"LEMON","variant":"vigenere"}'

The decoded text is ATTACKATDAWN. Omit --result-only to include the execution receipt. Use polya list for the full catalogue, or polya inspect <operation_id> for its contract; add --schema for the full JSON schema.

The same Vigenere example in Python:

from polya import run

result = run("cipher.polyalphabetic", {
    "text": "LXFOPVEFRNHR",
    "key": "LEMON",
    "variant": "vigenere",
})["result"]
assert result["text"] == "ATTACKATDAWN"

Use with agents

Run polya mcp as a local stdio server, or deploy the included remote HTTPS adapter to Render. Both expose puzzle.find to search for or inspect an operation, and puzzle.run to execute one. Start with the complete agent workflow for evidence, model checks, experiment choice, execution and continuation. See also MCP and agent setup.

Investigation council

Use the evidence-first council and investigation guide for evidence packets, local artifact handles, next-test ranking, bounded unknown-key proposals and matched agent evaluation. Four read-only subagent definitions are included; the host supplies actual model execution. No vote is treated as proof.

For educational puzzles, source-backed method selection adds six cited teaching cases, method.retrieve, and offline fresh-context/evaluation helpers. These are development references; no learned solving gain is claimed.

What it covers

Area	Operations
Image evidence	artifact.png_bitplane: lossless PNG channel and bit selection with source hashes and pixel coordinates
Ciphers and decoding	cipher.polyalphabetic, cipher.bifid, cipher.checkerboard, cipher.periodic_cribs, grid.traverse, text.symbol_map, bytes.from_radix
Mechanism search	mechanism.recipe_scan over recipe products; mechanism.plan_scan over typed artifact-to-target plans with resumable paging
Crypto targets	crypto.openssl_scan calibrated multi-lock scans, crypto.target_check SHA256 and P2PKH checks, pattern.equality_check whole-output patterns
Constraints	symbolic.solve, symbolic.analyze, hypotheses.compare over Z3, CP-SAT or a reference solver; constraints.solve for finite tables
Automata	automata.simulate_many, automata.distinguish for shortest distinguishing inputs, automata.learn_local for bounded active learning
Mathematics	jacobian.find and jacobian.run delegate to an optional, separately installed Jacobian runtime

Every operation is listed in the operation reference.

Scope and limits

Results describe the model and inputs you supply, not the puzzle author's intent. UNKNOWN, timeouts and unavailable backends are not negatives; valid padding is not a solution; bounded conformance does not prove equivalence. Source labels are caller claims, and receipts are not independent reproduction. Raw audio and semantic image interpretation are not implemented. No new open-puzzle solve or agent speedup is claimed.

Documentation

• Getting started: install matrix, first run, discovery
• Operation reference: every operation contract, generated from the registry
• Guides: ciphers, constraints, automata, plans, execution and evaluation, Jacobian
• Agents: workflow, MCP, investigating, setup
• Internals: architecture, performance, Python support, scope, adversarial review
• Examples and history (past validation and change records)

Development

python -m pip install -e ".[test,imaging,z3,learning]"
python -m pytest -q

Pre-stable. See contributing and the maintainer guide in AGENTS.md.

Inspired by Jacobian. MIT; catalogue attribution is in third-party notices.

For compound crypto experiments, use preflight and typed pipelines to compose the existing ciphers, extraction steps and exact checks without custom glue.