Metadata-Version: 2.4
Name: krail
Version: 1.0.0
Summary: Local-first memory and workflows for serious AI agent projects
Author: AkeBoss Tech
License-Expression: MIT
Project-URL: Homepage, https://github.com/AkeBoss-tech/knowledge
Project-URL: Documentation, https://github.com/AkeBoss-tech/knowledge/tree/main/docs
Project-URL: Repository, https://github.com/AkeBoss-tech/knowledge
Project-URL: Issues, https://github.com/AkeBoss-tech/knowledge/issues
Keywords: knowledge,agents,local-first,mcp,research,workflows,rag
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Provides-Extra: analysis
Requires-Dist: numpy; extra == "analysis"
Requires-Dist: pandas; extra == "analysis"
Requires-Dist: statsmodels; extra == "analysis"
Requires-Dist: matplotlib; extra == "analysis"
Provides-Extra: local
Requires-Dist: owlready2; extra == "local"
Requires-Dist: duckdb; extra == "local"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.7; extra == "embeddings"

# KRAIL

KRAIL is a local-first, repo-backed knowledge runtime for projects where agents
need durable context, not just chat history. It gives a project folder a
repeatable structure for captures, topic pages, source dependencies, lightweight
graphs, vector search, evidence-backed synthesis, workflow tasks, and integrity
records.

The PyPI distribution is named `krail`. The Python import namespace remains
`rail` for compatibility with earlier RAIL/KRAIL code.

```bash
pip install krail
```

```python
import rail

project = rail.local("./my-knowledge-project")
print(project.doctor())
```

## Documentation And DeepWiki

For a browsable, code-indexed guide to the full repository, use the generated
DeepWiki:

https://deepwiki.com/AkeBoss-tech/knowledge

DeepWiki is useful when you want to understand how the pieces of KRAIL fit
together beyond the package-level quick start. It indexes the repository and
organizes the codebase into guided sections such as:

- Overview and local-first philosophy
- Getting Started
- Repository layout and package structure
- Core concepts and data model
- The `rail.yaml` project manifest
- Project lifecycle phases
- Research integrity and provenance
- Knowledge packs and project templates
- `rail-py` SDK and CLI
- `KnowledgeRuntime` and the `krail` CLI
- Markdown graph engine
- Vector store and hybrid search
- Hydration engine and pipeline runner
- Autonomous agent system
- Planner runtime and brief ingestion
- Runner infrastructure and session lifecycle
- API layer and endpoint groups
- MCP server, tool reference, and deployment
- CI/CD workflows, testing strategy, and local development

Use this README when you need the package install path and day-one workflows.
Use DeepWiki when you want to navigate the implementation, trace a feature to
the source files, or understand the broader monorepo architecture.

## V1 Contract

`krail` 1.0.0 defines an honest local-runtime contract. It is not a claim that
every KRAIL surface is stable: the hosted API and engine packages, along with
the experimental capabilities called out below, remain outside this contract.

KRAIL v1 is the local-runtime contract, not a promise that every experimental
surface is finished.

The v1 contract covers:

- local project scaffolding with `krail init`
- `rail.yaml`-backed local projects
- capture inbox triage and durable topic promotion
- deterministic `search`, typed `find`, and optional local vector retrieval
- deterministic `think` envelopes with citations, freshness, gaps, conflicts,
  and next actions
- repo-backed tasks, workflow records, dry-run dispatch, and materialized
  workflow execution
- integrity status and related local trust/readiness views
- MCP access to the stable local project subset

The v1 contract does not promise hosted platform behavior, OS-level sandboxing,
default model-backed synthesis, mature external pack registries, or perfect
semantic retrieval.

## Why KRAIL?

Most retrieval tools stop at "here are the matching documents." KRAIL is built
around a fuller project loop:

```text
capture -> promote -> search -> think -> dispatch -> verify -> preserve
```

Use KRAIL when you want a local knowledge workspace that can:

- capture raw notes, files, URLs, and stdin into a predictable inbox
- promote useful captures into stable topic pages
- keep project knowledge in ordinary repo-backed markdown and YAML files
- build a markdown-frontmatter graph of topics, entities, claims, and links
- search local evidence deterministically
- build a local SQLite vector index for RAG-style retrieval
- synthesize answers with citations, gaps, conflicts, and next actions
- manage repo-backed tasks, work orders, workflows, and session records
- run local CLI agents such as Codex, Claude Code, Gemini, Cursor, or Copilot
- track source freshness, affected documents, claims, assumptions, and artifacts
- expose the same local project to MCP-compatible agent clients

KRAIL is intentionally headless. It does not require a hosted database, SaaS
control plane, frontend, or remote runner. A project folder plus the CLI is the
source of truth.

## Install

KRAIL requires Python 3.11 or newer.

```bash
pip install krail
```

Optional extras:

```bash
pip install "krail[local]"
pip install "krail[analysis]"
pip install "krail[embeddings]"
```

The extras enable heavier local capabilities:

- `local`: ontology and DuckDB helpers
- `analysis`: numerical and plotting dependencies
- `embeddings`: sentence-transformer embedding support

After installation, both commands point to the same CLI:

```bash
krail --version
rail --version
```

`krail` is the preferred command name. `rail` remains available for
compatibility.

## Quick Start

Create a new local knowledge project:

```bash
krail init robotics-kb --pack research-intelligence --mode markdown_graph
cd robotics-kb
krail --local doctor
```

Capture raw material:

```bash
krail --local capture "GCS may be useful as a feasibility layer for task plans"
krail --local capture --file ./paper-notes/gcs.md --type paper-note
echo "quick thought from stdin" | krail --local capture --stdin
```

Review the inbox:

```bash
krail --local inbox list
```

Promote useful material into durable topic pages:

```bash
krail --local inbox promote topics/inbox/<capture>.md \
  --topic task-and-motion-planning \
  --type method

krail --local topic upsert task-and-motion-planning \
  --content "Reviewed update with evidence."
```

Trusted knowledge stays explicit and repo-backed:

```bash
krail --local integrity status
krail --local evidence candidates
krail --local evidence promote-source <candidate_key> --source-type dataset
krail --local evidence promote-claim <candidate_key> --status supported
```

Promoted topics preserve capture/source provenance in frontmatter and register
candidate claims or sources under `research_plan/state/`. Candidates remain
gaps until they are reviewed and promoted; they are not treated as trusted
claims automatically.

Search local evidence:

```bash
krail --local search "GCS feasibility" --explain
```

Find typed records across documents, graph entities, integrity records,
artifacts, workflow sessions, and ingestion queues:

```bash
krail --local find "repo intake" --type workflow_run --status failed --json
```

Inspect permission metadata. Existing projects are public by default; records
become restricted only when they opt in with metadata such as
`visibility: private`, `allowed_roles`, or `allowed_agents`.

```bash
krail --local permissions doctor
```

Build and inspect the markdown graph:

```bash
krail --local graph build
krail --local graph entities --type Package
krail --local graph edges --entity PDDLStream
krail --local graph docs --topic task-and-motion-planning
```

Build a local vector index:

```bash
krail --local vector build
krail --local vector search "dual-arm planning benchmark"
krail --local search "dual-arm planning benchmark" --rag --explain
```

Ask KRAIL to synthesize from project evidence:

```bash
krail --local think "What changed in task and motion planning?"
```

The `think` command returns an answer envelope that can include citations,
supporting evidence, gaps, conflicts, source freshness, affected documents, graph
context, vector hits, and suggested next actions.

The stable v1 contract is `krail.think.v1`:

- `deterministic` returns an honest evidence envelope and does not pretend a
  model synthesized new claims.
- `runner` prepares or executes a local CLI synthesis session and writes prompt,
  evidence packet, result envelope, and any failure state under
  `research_plan/sessions/think_*`.
- `hybrid` uses the same session traces as `runner`, but keeps
  `answer_source: deterministic_evidence_envelope` whenever runner synthesis is
  unavailable or invalid.

Review a runner-backed session without launching a model:

```bash
krail --local think "What changed in task and motion planning?" --mode runner --runner codex_cli --dry-run
krail --local think-session status think_<session_id>
```

## Local Project Layout

A KRAIL project is just a directory with repo-backed knowledge files. Typical
projects contain:

```text
rail.yaml
.ontology/
topics/
topics/inbox/
sources/
research_plan/
research_plan/state/
artifacts/
.krail/
```

The important distinction is:

- `topics/inbox/` stores raw captures that still need triage
- `topics/` stores durable topic pages and reviewed knowledge
- `sources/` stores source records and dependency metadata
- `research_plan/` stores tasks, work orders, workflows, decisions, and sessions
- `artifacts/` stores outputs that can be checked or promoted
- `.krail/` stores local runtime state such as pack selection and vector indexes

Raw captures are not treated as trusted knowledge by default. Promote material
only after it is useful, supported, and shaped into stable project records.

## Knowledge Modes And Packs

KRAIL supports project modes that tune the ontology, workflow defaults, and
agent prompts for different kinds of knowledge work.

Inspect the active mode and pack:

```bash
krail --local mode active
krail --local mode list
krail --local pack active
krail --local pack validate
```

Built-in modes include:

- `research`: papers, methods, datasets, experiments, claims, evidence, and open questions
- `company`: teams, systems, policies, workflows, owners, metrics, decisions, and stale docs
- `personal`: projects, areas, resources, ideas, documents, and notes
- `software`: services, modules, APIs, dependencies, decisions, incidents, and risks
- `project`: milestones, decisions, artifacts, risks, blockers, and closeout

## CLI Overview

The CLI has two operating styles:

- local mode, using files from a project directory
- API mode, connecting to a KRAIL-compatible local API runtime

Most local commands look like this:

```bash
krail --local --path /path/to/project <command>
```

If you are running from this repository root, point `--path` at
`examples/minimal-project` for a source-build smoke test:

```bash
PYTHONPATH=packages/rail-py python -m rail.cli --local --path examples/minimal-project doctor
```

If you are already inside the project directory, this is enough:

```bash
krail --local <command>
```

Common commands:

```bash
krail init <directory>
krail --local doctor
krail --local capture "note"
krail --local inbox list
krail --local topic upsert <topic> --content "<reviewed update>"
krail --local search "query" --explain
krail --local think "question"
krail --local graph build
krail --local graph check
krail --local vector build
krail --local sources validate
krail --local sources check
krail --local integrity status
```

Agent and workflow commands:

```bash
krail --local agent list
krail --local agent run "summarize new captures" --runner codex_cli --dry-run
krail --local task create "Audit sources" --description "Check stale docs"
krail --local task list
krail --local task dispatch <task_id> --dry-run
krail --local workflow list
krail --local workflow init weekly_literature_refresh
krail --local workflow execute source_refresh --dry-run
krail --local workflow execute weekly_literature_refresh --dry-run
```

Prefer dry runs when dispatching agents or workflows. Dry runs write the work
order and session command files without launching a second agent process.

## Agent And Runner Integration

KRAIL can connect local knowledge projects to agent CLIs and MCP-compatible
agent clients. The goal is not to hide the agent behind an opaque service; the
goal is to give agents a durable, auditable workspace with evidence, tasks,
workflow state, and project-specific instructions.

There are two integration paths:

- CLI runner dispatch for local tools such as Codex CLI, Claude Code, Gemini CLI,
  Cursor CLI, and GitHub Copilot CLI
- MCP server tools for clients that can call KRAIL capabilities directly

### Local CLI runners

KRAIL can discover configured local runners:

```bash
krail --local agent list
```

It can then create dry-run or executable work orders for a selected runner:

```bash
krail --local agent run "summarize new captures" \
  --runner codex_cli \
  --dry-run
```

The same runner model works through tasks and workflows:

```bash
krail --local task create "Audit stale sources" \
  --description "Check source freshness and list affected topic pages." \
  --runner claude_code

krail --local task dispatch <task_id> --dry-run

krail --local workflow execute weekly_research_review \
  --dry-run
```

Dry runs are the recommended first step. They materialize the prompt, work order,
session command, and project context without launching another process. Full
dispatch can then run the selected local CLI once the work order looks right.

### Workflow Readiness

Use `workflow list` as the readiness check:

- `materialized`: a repo-backed spec already exists under `research_plan/workflows/` and is ready for `workflow execute`.
- `template_available`: KRAIL knows the built-in template, but you still need `workflow init` to write a reviewable local spec.
- `invalid`: a local spec exists, but it failed validation and needs repair before execution.

Happy path:

```bash
krail --local workflow list
krail --local workflow init weekly_literature_refresh
krail --local workflow execute weekly_literature_refresh --dry-run
krail --local workflow execute weekly_literature_refresh
```

Repair path:

```bash
krail --local workflow execute weekly_literature_refresh --dry-run
# returns status=not_materialized with:
#   next_action: krail --local workflow init weekly_literature_refresh

krail --local workflow init weekly_literature_refresh
krail --local workflow validate weekly_literature_refresh
krail --local workflow execute weekly_literature_refresh --dry-run
```

`workflow run` follows the same readiness rules and now points you at
`workflow init` when only a template is available.

New work orders keep the older compatibility fields and also carry a structured
session-scope record:

```json
{
  "capabilities_required": ["run_shell", "write_structured_output"],
  "allowed_paths": ["research_plan", "artifacts"],
  "capability_envelope": {
    "version": "v1alpha1",
    "scope_rule": "intersection_with_repo_policy",
    "required_capabilities": ["run_shell", "write_structured_output"],
    "paths": {
      "write": ["research_plan", "artifacts"]
    }
  }
}
```

The envelope is intentionally incremental. It gives runners and audits one
machine-readable place to inspect session scope, but it does not widen repo
permissions or create an OS-level sandbox. KRAIL still relies on its own
adapters and tool surfaces to enforce the declared scope.

This makes KRAIL useful as a coordination layer for agents:

- the repository remains the source of truth
- task instructions are captured as files
- agent outputs can be reviewed before promotion
- workflow runs can be repeated or audited
- project-specific packs and modes shape the work
- `doctor`, `sources`, `graph`, `vector`, and `integrity` checks can gate progress

### MCP-compatible clients

For tools that support the Model Context Protocol, run the KRAIL MCP server
against a local project:

```bash
RAIL_LOCAL=1 RAIL_PATH=/path/to/project rail-mcp
```

MCP clients can then call KRAIL tools for search, think, capture, inbox triage,
topic updates, task creation, workflow dispatch, mode inspection, pack
inspection, project health checks, graph queries, and integrity status.

Those broader MCP families are available in 1.0.0, but only the stable subset
documented in `packages/mcp-server/README.md` is part of the v1 compatibility
promise.

In practice, this means an agent can ask KRAIL for evidence before answering,
capture useful notes into the project inbox, create a repo-backed task, or run a
workflow without inventing its own memory system.

## Python API

KRAIL can be used directly from Python.

### Local project mode

```python
import rail

project = rail.local("./robotics-kb")

health = project.doctor()
print(health["status"])

results = project.search("graph of convex sets", explain=True)
for hit in results["results"]:
    print(hit["path"], hit.get("score"))

answer = project.think("What evidence do we have about GCS feasibility?")
print(answer["answer"])
```

### API mode

The hosted API adapter and `packages/api/` are experimental and are not part of
the 1.0.0 local-runtime compatibility promise. The following example is kept
for development and evaluation of that separate surface.

```python
import rail

project = rail.connect(
    "nj-economics",
    api_url="http://localhost:8000/api/v1",
)

df = project.query(
    "SELECT county_name, unemployment_rate "
    "FROM County "
    "ORDER BY unemployment_rate DESC "
    "LIMIT 10"
)

print(df)
```

### Streaming agent responses

```python
import rail

project = rail.connect("nj-economics")

for event in project.agent.ask(
    "Compare Hudson and Bergen County unemployment trends",
    stream=True,
):
    if event["type"] == "text_delta":
        print(event["text"], end="", flush=True)
```

## Search Versus Think

Use `search` when you need raw document evidence.

```bash
krail --local search "customer onboarding workflow" --explain
```

Use `find` when you need typed operational and knowledge records in one result
envelope, including documents, entities, claims, candidate evidence, artifacts,
workflow runs, and queue items.

```bash
krail --local find "customer onboarding workflow" --type claim --type workflow_run
```

Use `think` when you need a cited answer shape with explicit gaps, conflicts,
and next actions.

```bash
krail --local think "what changed in onboarding this week?"
```

`think` results always declare `contract_version`, `status`, and
`answer_source` so you can tell whether you are looking at a deterministic
evidence envelope, a completed runner synthesis, or a deterministic fallback
from hybrid/failed runner execution.

Do not promote generated statements into trusted project state until they are
registered as claims with evidence and pass the project integrity checks.

## Permissions

KRAIL permissions are local-first and backward-compatible. Missing permission
metadata means public/project-readable through KRAIL surfaces. Add restrictions
only where needed:

```yaml
visibility: private
owner: akash
sensitivity:
  - confidential
allowed_roles:
  - reviewer
allowed_agents:
  - codex_cli
```

Current repo-mediated protection is intentionally narrow and honest:

- `search`, `find`, `think`, MCP retrieval, and workflow execution consult the
  same record metadata model
- denied access and allowed access to restricted or sensitive repo records are
  appended to
  `research_plan/audit/access.jsonl`
- runner work orders can further narrow a session with `allowed_paths` and
  `capability_envelope`, but that scope is still KRAIL-mediated

If someone already has direct shell or filesystem access to the project, KRAIL
does not stop them from bypassing these checks outside the KRAIL CLI, SDK, API,
or MCP server.

## Workflow DAGs

Workflows can remain sequential, or they can opt into dependency-aware execution
with `needs`:

```yaml
id: repo_intake
dag:
  max_concurrency: 4
steps:
  - id: inspect_manifests
    kind: command
    run: python scripts/inspect.py

  - id: map_dependencies
    kind: command
    run: python scripts/deps.py

  - id: review
    kind: think
    needs: [inspect_manifests, map_dependencies]
    mode: hybrid
    query: summarize repo architecture evidence
```

Command steps support both `retry: 2` and richer retry policies:

```yaml
retry:
  max_attempts: 3
  backoff_seconds: 10
timeout_seconds: 300
```

## MCP Server

KRAIL projects can be exposed to MCP-compatible clients with the companion MCP
server package.

Install from the monorepo during development:

```bash
pip install -e 'packages/rail-py[local]'
pip install -e packages/mcp-server
```

Run against a local project:

```bash
RAIL_LOCAL=1 RAIL_PATH=/path/to/project rail-mcp
```

Useful MCP tool families include:

- `find`: retrieve typed records across docs, graph, integrity, sessions, queues, and artifacts
- `search`: retrieve document evidence
- `think`: synthesize evidence with gaps and conflicts
- `capture`: add local notes or source pointers
- `mode_active` and `mode_list`: inspect operating mode
- `inbox_list` and `inbox_promote`: triage captures
- `topic_list` and `topic_upsert`: manage durable topic pages
- `doctor`: inspect local project health
- `pack_active`: inspect the active knowledge pack
- `create_task`, `list_tasks`, and `dispatch_task`: manage worker tasks
- `list_workflows` and `run_workflow`: create workflow tasks from the active pack

Sensitive MCP operations should be treated the same way as any other KRAIL
surface: repo policy can deny them, and per-session work-order scope can narrow
what a launched runner is supposed to touch. That scope is declarative and
auditable, not a substitute for host-level sandboxing.

## Source Freshness And Integrity

KRAIL includes local checks for source dependency freshness and research
integrity records.

```bash
krail --local sources validate
krail --local sources check
krail --local sources affected
krail --local integrity status
krail --local integrity sources
krail --local integrity claims
```

These commands help separate raw notes from trusted project state. The intended
workflow is to capture freely, promote carefully, and keep claims tied to
evidence.

Use `integrity status` as the pre-promotion and pre-release gate. The status
payload is the concise readiness answer: what can be trusted now, what is
stale, what still lacks evidence, and the next KRAIL command to run. Drill into
the exact record with the detail commands:

```bash
krail --local integrity source <source_key>
krail --local integrity claim <claim_key>
krail --local integrity artifact <artifact_path>
krail --local integrity stale-graph
krail --local integrity verification-runs
```

## Current Status

KRAIL's current stable promise is the local-runtime loop documented above.

Covered by the current CLI tests, MCP tests, or fixture smoke commands:

- local project scaffolding
- capture inbox and topic promotion
- deterministic local search
- typed `find`
- markdown-frontmatter graph build/query/export
- local SQLite vector database with deterministic local-hash embeddings by default
- deterministic `think` evidence envelopes
- project health checks
- source dependency checks
- repo-backed tasks, work orders, workflows, and session state
- local CLI runner discovery and dry-run dispatch
- local workflow template listing and materialized workflow execution
- Python client for local and API-backed projects

Explicitly outside the v1 promise for now:

- model-backed synthesis and reranking as the default path
- external pack installation
- host-level isolation beyond KRAIL-mediated enforcement
- remote permission scopes
- hosted UI and managed deployments

## Development

From the repository root:

```bash
pip install -e 'packages/rail-py[local]' -e packages/mcp-server
PYTHONPATH=packages/rail-py:packages/mcp-server pytest -q packages/rail-py/tests
```

Build the PyPI package:

```bash
python -m pip install --upgrade build twine
python -m build packages/rail-py
python -m build packages/mcp-server
python -m twine check packages/rail-py/dist/* packages/mcp-server/dist/*
```

Smoke-test a fresh wheel install:

```bash
python -m venv .venv-release
. .venv-release/bin/activate
python -m pip install --upgrade pip
pip install packages/rail-py/dist/*.whl
krail --version
pip install --find-links packages/rail-py/dist packages/mcp-server/dist/*.whl
rail-mcp --help
deactivate
```

## Links

- Repository: https://github.com/AkeBoss-tech/knowledge
- DeepWiki: https://deepwiki.com/AkeBoss-tech/knowledge
- Issues: https://github.com/AkeBoss-tech/knowledge/issues
- PyPI: https://pypi.org/project/krail/

## License

MIT
