Polinko

Maintenance in progress. Documentation and research surfaces are being standardised before this repo is shared as a stable reference.

Polinko is a human-led research system for inspecting AI behaviour through fail-first evaluation, evidence-preserving method work, and repo-native publishing.

The website is a doorway. The repository is the research surface.

Why This Exists

Most AI projects foreground polished outputs and hide the failure structure. Polinko keeps failure visible enough to inspect, classify, and improve. That matters anywhere confidence can outrun source evidence.

The method is intentionally small and strict: preserve the artefact, decide pass or fail, retain useful failures, evict noise, and let the tracked evidence change the next run.

Current Read

Beta 2.3 is the frozen method snapshot. pre-Beta 2.4 is now staged as the next research-model contract before new evidence is cut.

The active read is:

• OCR is the mature green lane, stabilised on the current image set and moving into broader generalisation pressure.
• The discarded run-level rollup path is not being carried forward; the next research-model question is how source artefacts, row/case judgement, manual evals, lane summaries, and repeated lane signal can carry claims.
• Co-reasoning is the first promoted non-OCR lane, supported by tracked style and soak evidence.
• Retrieval, response behaviour, uncertainty boundary, and hallucination boundary are operationalised support surfaces.
• Operator burden is the active thin lane because it is still producing distinct evidence pressure.
• The research surface is open: current lane status is explicit, but the method claim is still under pressure.

For the maintained research map, start with docs/research/README.md.

Start Here

Use the public path when you want the shortest reviewer-facing read:

• Polinko in Brief
• Method & Authorship
• Hypothesis
• Evidence
• Diagrams

Use the operator path when you need to run, inspect, or change the system:

• Docs Map
• Runbook
• Architecture
• Current State
• Decisions

What Lives Here

• FastAPI API and CLI runtime
• Manual eval workbench: notebooks, local evidence databases, chat artefacts, feedback, checkpoints, and exports
• Fail-first eval surfaces
• OCR and non-OCR method lanes
• Export-backed behaviour backlog mining
• Tracked research docs, diagrams, and eval context
• Repo-local engineering and validation workflow

Quick Start

make deps-install
cp .env.example .env
# set OPENAI_API_KEY in .env
make doctor-env
make docs

This prints the local API docs URL. Use make docs-open only when you want to launch the system browser.

Repo Map

• src/polinko/cli.py contains the packaged CLI chat implementation; make chat, polinko-chat, and root main.py launch it.
• src/polinko/asgi.py constructs the FastAPI ASGI app and chat-facing manual eval workbench endpoints; root server.py preserves uvicorn server:app.
• pyproject.toml and src/polinko/ provide the editable-install rail for the runtime package.
• src/polinko/config.py contains the canonical config implementation; the legacy root config.py shim is retired.
• src/polinko/api/ contains the canonical API implementation; legacy root api/ shims are retired.
• src/polinko/core/ contains canonical runtime logic; legacy root core/ shims are retired.
• tools/ contains eval and maintenance scripts.
• tests/ contains the test suite.
• docs/public/ contains the curated public reading path.
• docs/research/ contains the compact research surface.
• docs/eval/ contains eval evidence and phase context.
• docs/governance/ contains charter, state, and decisions.
• docs/runtime/ contains runbook and architecture.

Licence

Apache-2.0. See licence.