Polinko

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

Polinko is a human-led research system for inspecting AI behavior 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 artifact, 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, stabilized on the current image set and moving into broader generalization pressure.
• The discarded run-level rollup path is not being carried forward; the next research-model question is how source artifacts, row/case judgment, 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 operationalized 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 artifacts, 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.

License

Apache-2.0. See LICENSE.