runform-akc 0.1.0

Agentic Knowledge Compiler — turn messy real-world information into executable knowledge

Agentic Knowledge Compiler (AKC)

AKC is an AI-native software factory for turning project knowledge into buildable software.

It grounds software generation in real project context: docs, codebases, OpenAPI specs, messaging exports, and MCP resources. Instead of stopping at a one-shot AI answer, AKC moves work through structured stages that can generate code and other artifacts, verify results, track evidence, and support runtime, delivery, and control-plane workflows.

What’s missing to ship?

Run:

akc deliver preflight

AKC will tell you exactly what prerequisites are missing (repo, environment, operator inputs) to ship via execute-mode delivery and store lanes.

The core loop is:

Plan -> Retrieve -> Generate -> Execute -> Repair

AKC defaults to an offline-friendly path for local demos:

• ingest can use --embedder hash for deterministic, key-free indexing
• compile uses an offline backend by default
• verify, view, and most control-plane flows run locally
• validation can stay evidence-first through operator-side validator bindings plus exported artifacts

Status

Alpha. The repository is active and broad in scope, but interfaces are still moving.

What AKC Does

• Ground software work in context: ingest docs, codebase, openapi, slack, discord, telegram, whatsapp, and mcp
• Generate more than answers: produce code and other structured artifacts through compile and verification stages
• Keep work inspectable: record replayable evidence, policy decisions, and validation results
• Support operator workflows: expose assistant, runtime, living-recompile, control-plane, and fleet surfaces
• Move toward delivery: support named-recipient delivery sessions and packaging/distribution workflows for web, iOS, and Android targets
• Preserve local inspection: provide TUI, static web, and export viewer modes for emitted artifacts

Quick Start

Requirements

• Python 3.11+
• uv

Install

Operator-friendly installs (one command, predictable upgrades):

# Preferred (isolated tool install)
uv tool install runform-akc

# Upgrade later
uv tool upgrade runform-akc

# Alternative (also isolated)
pipx install runform-akc

# Upgrade later
pipx upgrade runform-akc

Optional: install a prebuilt standalone binary from GitHub Releases (no Python env):

curl -fsSL https://raw.githubusercontent.com/nonameuserd/runform/main/scripts/install-akc.sh | sh
~/.local/bin/akc --help

From source (contributors / editable dev):

git clone https://github.com/nonameuserd/runform.git
cd runform
uv sync
uv sync --extra dev

source .venv/bin/activate   # Windows: .venv\Scripts\activate
akc --help

Useful optional extras:

• uv sync --extra ingest-all for docs/OpenAPI/embedding/vector/messaging/MCP ingest extras
• uv sync --extra mcp-serve for akc mcp
• uv sync --extra vectorstore-pg for the pgvector index backend
• uv sync --extra delivery-providers for store-signing/provider integrations used by akc deliver

Safe Local Demo

This path stays local and avoids working-tree writes by using --artifact-only.

# Optional: create .akc/project.json and a local policy stub
akc init

# Ingest local docs into a persistent sqlite index
akc ingest \
  --tenant-id demo \
  --connector docs \
  --input ./docs \
  --embedder hash \
  --index-backend sqlite

# Compile into reviewable artifacts only
akc compile \
  --tenant-id demo \
  --repo-id runform \
  --outputs-root ./out \
  --artifact-only

# Verify emitted artifacts
akc verify \
  --tenant-id demo \
  --repo-id runform \
  --outputs-root ./out

# Generate a static HTML viewer bundle
akc view \
  --tenant-id demo \
  --repo-id runform \
  --outputs-root ./out \
  web

If you want weighted memory during compile or assistant sessions:

export AKC_WEIGHTED_MEMORY_ENABLED=1

Common Workflows

Ingest

Index repository or external knowledge sources for later retrieval. Supported connectors: docs, codebase, openapi, slack, discord, telegram, whatsapp, mcp (see akc ingest --help and examples/README.md for one recipe per connector).

# Local docs tree (tiny sample under examples/)
akc ingest --tenant-id demo --connector docs --input ./examples/docs-sample --embedder hash --index-backend sqlite

# Repository code
akc ingest --tenant-id demo --connector codebase --input . --embedder hash --index-backend sqlite

# OpenAPI 3.x (JSON path or URL; YAML specs need akc[ingest-openapi])
akc ingest --tenant-id demo --connector openapi --input ./examples/openapi/petstore.json --embedder hash --index-backend sqlite

# Messaging / MCP need tokens or payload paths—see examples/messaging and examples/mcp

Compile and Verify

Generate artifacts under <outputs-root>/<tenant>/<repo>/ and verify them:

akc compile --tenant-id demo --repo-id runform --outputs-root ./out --artifact-only
akc verify --tenant-id demo --repo-id runform --outputs-root ./out

akc compile defaults to scoped_apply, so use --artifact-only when you want a non-mutating run.

For backend execution-workspace generation, mixed and polyglot repositories are valid inputs, but v1 built-in authoritative backend materializers are limited to typescript_node and python_fastapi. Other requested runtimes such as go, rust, or java require an external generator manifest under .akc/backend_generators/; otherwise AKC fails closed for authoritative materialization and emits fallback diagnostic workspaces.

To execute observability or mobile validators before operational verification:

akc verify \
  --tenant-id demo \
  --repo-id runform \
  --outputs-root ./out \
  --execute-validators

Assistant

Run a single planning turn:

akc assistant --mode plan -p "show me the next command to verify the latest compile outputs"

Run an interactive session:

akc assistant

View Artifacts

akc view --tenant-id demo --repo-id runform --outputs-root ./out tui
akc view --tenant-id demo --repo-id runform --outputs-root ./out web
akc view --tenant-id demo --repo-id runform --outputs-root ./out export

Runtime, Control, Delivery, and Fleet

The CLI also exposes:

• runtime for start/stop/status, reconcile, replay, checkpoint, coordination planning, and autopilot
• control and policy for operational indexes, replay forensics, policy bundles, and explainability
• control-bot for the standalone multi-channel operator gateway
• deliver for named-recipient delivery sessions
• fleet for aggregated read-only control-plane views across many outputs roots

Repository Map

Path	Purpose
src/akc/	Main Python package: CLI, ingest, compile, runtime, control, delivery, memory, assistant, viewer
tests/	Unit, integration, and end-to-end coverage
docs/	Getting started, CLI reference, architecture, runtime, delivery, viewer, ops
configs/	Example policy, eval, and SLO configuration
deploy/	Deployment references for systemd, Compose, Kubernetes, and CI
examples/	Ingest recipes for every connector, sample OpenAPI/docs/WASM, LLM backend wiring, golden viewer snapshot
rust/	Optional Rust crates for ingest, executor, and protocol surfaces
scripts/	CI and quality gate helpers
packaging/, tools/nuitka/	Packaging and standalone binary build helpers

Documentation

Published site (GitHub Pages): https://nonameuserd.github.io/runform/

The site is built with MkDocs Material (mkdocs.yml) and deployed from main when documentation-related paths change (see .github/workflows/docs.yml). Pull requests run a strict build check via .github/workflows/docs-verify.yml. Maintainer setup (once): in the GitHub repo, open Settings → Pages → Build and deployment and set Source to GitHub Actions (not “Deploy from branch”).

Repository Markdown:

• Docs index
• Getting started
• CLI command reference
• Architecture
• Compile-time skills
• Validation
• Runtime execution
• Delivery architecture
• Viewer
• Ops runbook
• Artifact contracts

Development

Local checks:

uv run ruff check .
uv run ruff format .
uv run mypy src/akc
uv run pytest

Contributor docs:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• GOVERNANCE.md

License

Licensed under the Apache-2.0 license.