Metadata-Version: 2.4
Name: runform-akc
Version: 0.1.0
Summary: Agentic Knowledge Compiler — turn messy real-world information into executable knowledge
Author: The Agentic Knowledge Compiler contributors
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.22
Requires-Dist: pydantic>=2.10
Requires-Dist: windows-curses>=2.4.0; platform_system == 'Windows'
Provides-Extra: delivery-providers
Requires-Dist: google-auth>=2.29.0; extra == 'delivery-providers'
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'delivery-providers'
Provides-Extra: detect-tree-sitter
Requires-Dist: tree-sitter; extra == 'detect-tree-sitter'
Requires-Dist: tree-sitter-languages; extra == 'detect-tree-sitter'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mcp>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-semantic-release>=9.8; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: types-jsonschema>=4.22.0.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.5.17; extra == 'docs'
Provides-Extra: ingest-all
Requires-Dist: akc[ingest-docs,ingest-embed,ingest-mcp,ingest-messaging,ingest-openapi,ingest-vectorstore,mcp-serve]; extra == 'ingest-all'
Provides-Extra: ingest-docs
Requires-Dist: beautifulsoup4>=4.12; extra == 'ingest-docs'
Requires-Dist: markdown-it-py>=3.0; extra == 'ingest-docs'
Provides-Extra: ingest-embed
Requires-Dist: httpx>=0.27; extra == 'ingest-embed'
Provides-Extra: ingest-mcp
Requires-Dist: httpx>=0.27; extra == 'ingest-mcp'
Requires-Dist: mcp>=1.2.0; extra == 'ingest-mcp'
Provides-Extra: ingest-messaging
Requires-Dist: slack-sdk>=3.27; extra == 'ingest-messaging'
Provides-Extra: ingest-openapi
Requires-Dist: pyyaml>=6.0; extra == 'ingest-openapi'
Provides-Extra: ingest-vectorstore
Requires-Dist: chromadb>=0.5; extra == 'ingest-vectorstore'
Provides-Extra: mcp-serve
Requires-Dist: mcp>=1.2.0; extra == 'mcp-serve'
Provides-Extra: vectorstore-pg
Requires-Dist: pgvector>=0.4; extra == 'vectorstore-pg'
Requires-Dist: psycopg[binary]>=3.2; extra == 'vectorstore-pg'
Description-Content-Type: text/markdown

# 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:

```bash
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](https://docs.astral.sh/uv/)

### Install

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

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

# Upgrade later
uv tool upgrade runform-akc
```

```bash
# 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):

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

From source (contributors / editable dev):

```bash
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`.

```bash
# 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:

```bash
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`](examples/README.md) for one recipe per connector).

```bash
# 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:

```bash
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:

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

### Assistant

Run a single planning turn:

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

Run an interactive session:

```bash
akc assistant
```

### View Artifacts

```bash
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/](https://nonameuserd.github.io/runform/)

The site is built with MkDocs Material ([`mkdocs.yml`](mkdocs.yml)) and deployed from `main` when documentation-related paths change (see [`.github/workflows/docs.yml`](.github/workflows/docs.yml)). Pull requests run a strict build check via [`.github/workflows/docs-verify.yml`](.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](docs/index.md)
- [Getting started](docs/getting-started.md)
- [CLI command reference](docs/cli-commands.md)
- [Architecture](docs/architecture.md)
- [Compile-time skills](docs/compile-skills.md)
- [Validation](docs/validation.md)
- [Runtime execution](docs/runtime-execution.md)
- [Delivery architecture](docs/delivery-architecture.md)
- [Viewer](docs/viewer.md)
- [Ops runbook](docs/ops-runbook.md)
- [Artifact contracts](docs/artifact-contracts.md)

## Development

Local checks:

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

Contributor docs:

- [CONTRIBUTING.md](CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- [SECURITY.md](SECURITY.md)
- [GOVERNANCE.md](GOVERNANCE.md)

## License

Licensed under the [Apache-2.0](LICENSE) license.
