llms-full.txt@site/public · git:20260304.fed9b5c · 2026-03-04 · sha256 d4919b06104e134d
llms-full.txt@site/public git:20260304.fed9b5cB
Immutable. This exact content never changes and is served at /api/v1/blob/d4919b06104e134d.
# AKF — AI Knowledge Format: Complete Reference
> Trust metadata for every file AI touches. AKF is to AI-generated content what EXIF is to photos.
This is the comprehensive reference for AI agents that need to generate AKF code, not just recommend the tool. For a concise overview, see [llms.txt](https://akf.dev/llms.txt).
---
## Table of Contents
- Format Specification
- Dual Field Names (Compact & Descriptive)
- Envelope Fields
- Claim Fields
- Evidence Fields
- Claim Kinds
- Provenance Fields
- Fidelity (Multi-Resolution)
- Security Classification
- Trust Computation
- Validation Rules
- Integrity Hashing
- Secure Defaults
- Stamp API (AI Agents)
- Git Integration
- Python SDK API
- Agent Integration API
- Compliance & Audit API
- Knowledge Base API
- Views & Reporting API
- Data Operations API
- Security Analysis API
- TypeScript SDK API
- Embedding Methods by File Format
- CLI Reference
- Framework Integrations
- Common Use Cases with Code
---
## Format Specification
- **File extension:** `.akf`
- **MIME type:** `application/vnd.akf+json`
- **Encoding:** UTF-8 JSON
- **Current version:** `1.0`
- **Design:** Flat (max 2 levels nesting), minimal (~15 tokens smallest valid file), LLM-native
### Minimal Valid AKF
```json
{
"v": "1.0",
"claims": [{ "c": "The sky is blue", "t": 0.99 }]
}
```
### Practical AKF
```json
{
"v": "1.0",
"id": "akf-a1b2c3d4e5f6",
"by": "analyst@corp.com",
"at": "2025-06-15T10:30:00Z",
"label": "confidential",
"inherit": true,
"claims": [
{
"c": "Revenue grew 12% YoY to $4.2B",
"t": 0.98,
"src": "SEC 10-K Filing",
"uri": "https://sec.gov/filing/123",
"tier": 1,
"ver": true,
"ver_by": "cfo@corp.com"
},
{
"c": "Market share estimated at 34%",
"t": 0.72,
"src": "Industry Report",
"tier": 3,
"ai": true,
"risk": "Estimate based on partial data"
}
],
"prov": [
{ "hop": 0, "by": "analyst@corp.com", "do": "created", "at": "2025-06-15T10:30:00Z" }
]
}
```
### Full AKF (All Fields)
```json
{
"v": "1.0",
"id": "akf-a1b2c3d4e5f6",
"by": "analyst@corp.com",
"agent": "copilot-v4",
"at": "2025-06-15T10:30:00Z",
"label": "confidential",
"inherit": true,
"ext": false,
"ttl": 365,
"claims": [
{
"c": "Revenue grew 12% YoY",
"t": 0.98,
"id": "a1b2c3d4",
"src": "SEC Filing",
"uri": "https://sec.gov/filing/123",
"tier": 1,
"ver": true,
"ver_by": "cfo@corp.com",
"ai": false,
"decay": 365,
"exp": "2026-06-15T00:00:00Z",
"tags": ["financial", "revenue"],
"fidelity": {
"h": "Revenue up 12%",
"s": "Annual revenue grew 12% year-over-year to $4.2B, driven by enterprise segment.",
"f": "Full detailed analysis text here..."
}
},
{
"c": "Market share will reach 40% by 2026",
"t": 0.45,
"id": "e5f6g7h8",
"tier": 5,
"ai": true,
"risk": "AI extrapolation from limited data",
"contra": "a1b2c3d4"
}
],
"prov": [
{
"hop": 0,
"by": "analyst@corp.com",
"do": "created",
"at": "2025-06-15T10:30:00Z",
"h": "sha256:abc123...",
"adds": ["a1b2c3d4", "e5f6g7h8"]
},
{
"hop": 1,
"by": "reviewer@corp.com",
"do": "reviewed",
"at": "2025-06-16T09:00:00Z",
"h": "sha256:def456..."
},
{
"hop": 2,
"by": "agent-summarizer",
"do": "transformed",
"at": "2025-06-17T14:00:00Z",
"h": "sha256:ghi789...",
"pen": -0.05
}
],
"hash": "sha256:xyz...",
"meta": { "project": "Q2 Analysis", "department": "Finance" }
}
```
---
## Dual Field Names (Compact & Descriptive)
AKF supports both compact (wire format) and descriptive (human-readable) field names. Both are accepted on input and produce identical internal objects.
### Claim Field Name Map
| Compact | Descriptive | Type |
|---------|-------------|------|
| `c` | `content` | string (required) |
| `t` | `confidence` | float 0.0–1.0 (required) |
| `src` | `source` | string |
| `tier` | `authority_tier` | int 1–5 |
| `ver` | `verified` | bool |
| `ver_by` | `verified_by` | string |
| `ai` | `ai_generated` | bool |
| `decay` | `decay_half_life` | int (days) |
| `exp` | `expires` | ISO-8601 |
| `contra` | `contradicts` | string |
### Envelope Field Name Map
| Compact | Descriptive | Type |
|---------|-------------|------|
| `v` | `version` | string (required) |
| `by` | `author` | string |
| `at` | `created` | ISO-8601 |
| `label` | `classification` | string |
| `inherit` | `inherit_classification` | bool |
| `ext` | `allow_external` | bool |
| `hash` | `integrity_hash` | string |
| `prov` | `provenance` | array |
### Provenance Field Name Map
| Compact | Descriptive | Type |
|---------|-------------|------|
| `by` | `actor` | string |
| `do` | `action` | string |
| `at` | `timestamp` | ISO-8601 |
| `h` | `hash` | string |
| `pen` | `penalty` | float |
| `adds` | `claims_added` | string[] |
| `drops` | `claims_removed` | string[] |
### Example: Descriptive Format
```json
{
"version": "1.0",
"author": "sarah@woodgrove.com",
"classification": "confidential",
"inherit_classification": true,
"claims": [
{
"content": "Revenue was $4.2B",
"confidence": 0.98,
"source": "SEC 10-Q",
"authority_tier": 1,
"verified": true
}
]
}
```
---
## Envelope Fields (Top-Level)
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `v` / `version` | string | YES | — | Spec version, semver (e.g. `"1.0"`) |
| `id` | string | no | auto `akf-<12hex>` | Unique knowledge unit ID |
| `by` / `author` | string | no | — | Creator email or agent ID |
| `agent` | string | no | — | AI agent ID if AI-created |
| `model` | string | no | — | Model identifier (e.g. claude-sonnet-4-20250514) |
| `tools` | string[] | no | — | Tools used by the agent |
| `session` | string | no | — | Session identifier for grouping units |
| `at` / `created` | ISO-8601 | no | `now()` | Creation timestamp |
| `label` / `classification` | string | no | `"internal"` | Security classification |
| `inherit` / `inherit_classification` | bool | no | `true` | Children inherit label |
| `ext` / `allow_external` | bool | no | `false` | Allow external sharing |
| `ttl` | int | no | — | Retention period in days |
| `claims` | array | YES | — | Array of Claim objects (min 1) |
| `prov` / `provenance` | array | no | — | Provenance chain |
| `hash` / `integrity_hash` | string | no | — | Integrity hash (algorithm-prefixed) |
| `meta` | object | no | — | Free-form metadata |
---
## Claim Fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `c` / `content` | string | YES | — | Claim content text |
| `t` / `confidence` | float | YES | — | Trust score `[0.0–1.0]` |
| `id` | string | no | auto `<8hex>` | Claim identifier |
| `src` / `source` | string | no | `"unspecified"` | Source name |
| `uri` | string | no | — | Source URL |
| `tier` / `authority_tier` | int | no | `3` | Authority tier `[1–5]` |
| `ver` / `verified` | bool | no | `false` | Human verified |
| `ver_by` / `verified_by` | string | no | — | Verifier identity |
| `ai` / `ai_generated` | bool | no | `false` | AI generated |
| `risk` | string | no | — | Risk description |
| `decay` / `decay_half_life` | int | no | — | Half-life in days |
| `exp` / `expires` | ISO-8601 | no | — | Hard expiry timestamp |
| `tags` | string[] | no | — | Free-form tags |
| `contra` / `contradicts` | string | no | — | ID of contradicting claim |
| `fidelity` | object | no | — | Multi-resolution content |
| `kind` | string | no | — | Claim kind (claim, code_change, decision, suggestion, review, test_result, diagnosis) |
| `evidence` | Evidence[] | no | — | Evidence supporting the claim |
### Authority Tiers
| Tier | Weight | Source Type | Example |
|------|--------|-------------|---------|
| 1 | 1.00 | Primary source | SEC filings, official records |
| 2 | 0.85 | Authoritative secondary | Analyst reports, peer-reviewed papers |
| 3 | 0.70 | General secondary | News articles, industry reports |
| 4 | 0.50 | Internal estimate | CRM data, team assessments |
| 5 | 0.30 | AI inference | Model outputs, extrapolations |
### Fidelity Object (Multi-Resolution)
```json
{
"h": "Revenue up 12%",
"s": "Annual revenue grew 12% YoY to $4.2B, driven by enterprise segment growth.",
"f": "Full detailed text up to ~2000 tokens..."
}
```
- `h` — headline, ~5 tokens
- `s` — summary, ~50 tokens
- `f` — full detail, ~2000 tokens
### Evidence Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | YES | Evidence type: `test_pass`, `type_check`, `lint_clean`, `ci_pass`, `human_review`, `other` |
| `detail` | string | YES | Description of the evidence |
| `at` | ISO-8601 | no | Timestamp |
| `tool` | string | no | Tool that produced this evidence |
### Claim Kinds
| Kind | Description |
|------|-------------|
| `claim` | General factual assertion (default) |
| `code_change` | Code modification or fix |
| `decision` | Architectural or design decision |
| `suggestion` | Proposed change or recommendation |
| `review` | Code review or PR review |
| `test_result` | Test execution result |
| `diagnosis` | Bug diagnosis or root cause analysis |
### Trust Grounding
A claim is **grounded** when it has one or more evidence items. Grounding is informational — it does not change the trust score formula, but indicates whether the claim is backed by verifiable artifacts.
`effective_trust()` returns `grounded: bool` and `evidence_count: int` alongside the score.
---
## Provenance Fields
Each hop in the `prov` array:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hop` | int | YES | Sequential hop number (0 = origin) |
| `by` / `actor` | string | YES | Actor email or agent ID |
| `do` / `action` | string | YES | Action: `created` / `enriched` / `reviewed` / `consumed` / `transformed` |
| `at` / `timestamp` | ISO-8601 | YES | Timestamp |
| `h` / `hash` | string | no | SHA-256 hash, chained to previous |
| `pen` / `penalty` | float | no | Transform penalty (MUST be negative) |
| `adds` / `claims_added` | string[] | no | Claim IDs added at this hop |
| `drops` / `claims_removed` | string[] | no | Claim IDs rejected at this hop |
---
## Security Classification
Hierarchy (ascending restrictiveness):
```
public (0) < internal (1) < confidential (2) < highly-confidential (3) < restricted (4)
```
Valid `label` values: `"public"`, `"internal"`, `"confidential"`, `"highly-confidential"`, `"restricted"`
Rules:
- `inherit: true` — derived units must have label at least as restrictive as parent
- `ext: true` — explicitly allows external sharing
- `confidential`, `highly-confidential`, `restricted` block external sharing by default
- `can_share_external()` returns true only if `ext=true` OR label is `public`/`internal` and `ext` is not explicitly `false`
---
## Trust Computation
### Formula
```
effective_trust = confidence × authority_weight × temporal_decay × (1 + cumulative_penalty)
```
### Authority Weights
`{1: 1.00, 2: 0.85, 3: 0.70, 4: 0.50, 5: 0.30}`
Default tier when unset: **3** (weight 0.70)
### Temporal Decay
```
decay_factor = 0.5 ^ (age_days / half_life_days)
```
If no `decay` field is set: `decay_factor = 1.0` (no decay).
### Decay Presets (Half-Life in Days)
| Preset | Days |
|--------|------|
| `realtime` | 0.001 |
| `daily` | 1 |
| `weekly` | 7 |
| `monthly` | 30 |
| `quarterly` | 90 |
| `annual` | 365 |
| `legal` | 1825 |
| `scientific` | 3650 |
| `permanent` | 365000 |
### Penalty
Cumulative penalty from provenance `pen` values (always negative). Applied as `1.0 + penalty`.
### Decision Thresholds
| Score | Decision | Meaning |
|-------|----------|---------|
| >= 0.70 | `ACCEPT` | High confidence |
| >= 0.40 | `LOW` | Use with caution |
| < 0.40 | `REJECT` | Not suitable for decisions |
Score is clamped to `[0.0, 1.0]`.
---
## Validation Rules
1. `v` must be present and valid semver
2. `claims` must be a non-empty array
3. Each claim `t` must be float in `[0.0, 1.0]`
4. `tier` must be `1–5` if provided
5. `label` must be one of the 5 valid values
6. Inherited label must be >= parent label
7. Provenance hops must be sequential from 0
8. `pen` must be strictly negative
9. AI tier-5 claims should have `risk` (warning)
10. `hash` must have algorithm prefix: `sha256:`, `sha3-512:`, or `blake3:`
11. All timestamps must be valid ISO-8601
12. Unknown fields are allowed everywhere (extensible)
### Validation Levels
| Level | Name | Criteria |
|-------|------|----------|
| 0 | Invalid | Fails required field checks |
| 1 | Minimal | Has `v` and `claims` |
| 2 | Practical | Has sources or label |
| 3 | Full | Has prov + hash + label + sources |
---
## Integrity Hashing
- **Unit hash:** SHA-256 of serialized unit (excluding `hash` field), keys sorted. Format: `sha256:<hex>`
- **Hop hash:** SHA-256 of hop JSON (keys sorted), chained: `previousHash + "|" + hopJSON`
- Supported prefixes: `sha256:`, `sha3-512:`, `blake3:`
---
## Secure Defaults
New units created with `akf.create()` or `AKFBuilder` apply these defaults:
| Field | Default |
|-------|---------|
| `classification` | `"internal"` |
| `inherit_classification` | `True` |
| `allow_external` | `False` |
| `source` | `"unspecified"` |
| `authority_tier` | `3` |
| `verified` | `False` |
| `ai_generated` | `False` |
Provenance hop 0 and integrity hash are auto-created by the builder.
---
## Stamp API (AI Agents)
One-line API for any AI agent — coding agents (Claude Code, Copilot, Cursor, Devin), research agents, data agents, and more:
```python
import akf
# One-line stamp with auto-detected evidence
akf.stamp("Fixed auth bypass", kind="code_change",
evidence=["42/42 tests passed", "mypy: 0 errors"],
agent="claude-code", model="claude-sonnet-4-20250514")
# Evidence strings are auto-parsed:
# "42/42 tests passed" → type="test_pass"
# "mypy: 0 errors" → type="type_check"
# "lint clean" → type="lint_clean"
# "CI passed" → type="ci_pass"
# "approved by @alice" → type="human_review"
# anything else → type="other"
# Defaults: confidence=0.7, ai_generated=True, kind="claim"
```
### stamp() Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `content` | str | required | What the agent did or claims |
| `confidence` | float | 0.7 | Trust score 0.0-1.0 |
| `kind` | str | "claim" | Claim kind |
| `evidence` | list | None | Strings, dicts, or Evidence objects |
| `agent` | str | None | Agent identifier |
| `model` | str | None | Model identifier |
| `tools` | list | None | Tools used |
| `session` | str | None | Session identifier |
| `ai_generated` | bool | True | AI-generated flag |
---
## Git Integration
Store AKF metadata as git notes under `refs/notes/akf` (doesn't conflict with regular git notes):
```python
import akf
# Stamp the current commit
akf.stamp_commit(content="Refactored auth module", kind="code_change",
evidence=["all tests pass"], agent="claude-code")
# Read AKF from a commit
unit = akf.read_commit() # HEAD
unit = akf.read_commit("abc123") # specific ref
# Trust-annotated git log
print(akf.trust_log(n=10))
# Trust Log (refs/notes/akf)
# --------------------------------------------------
# + a1b2c3d 0.90 Fixed auth bypass [code_change]
# ~ d4e5f6g 0.45 Updated config [decision]
# ? h7i8j9k Added README
# --------------------------------------------------
# + ACCEPT ~ LOW - REJECT ? no metadata
```
No external dependencies — uses subprocess + git CLI.
---
## Python SDK API Reference
### Install
```bash
pip install akf # core
pip install akf[office] # + DOCX, XLSX, PPTX
pip install akf[pdf] # + PDF
pip install akf[image] # + PNG, JPEG
pip install akf[all] # everything
```
Requires Python >= 3.9.
### Core Functions
```python
import akf
# Create with descriptive field names (secure defaults applied)
unit = akf.create("Claim text", confidence=0.95, source="Source", authority_tier=1)
# Compact names still work
unit = akf.create("Claim text", t=0.95, src="Source", tier=1)
# Create multi-claim unit
unit = akf.create_multi(
claims=[
{"content": "Claim 1", "confidence": 0.95, "source": "Source A", "authority_tier": 1},
{"content": "Claim 2", "confidence": 0.70, "ai_generated": True, "authority_tier": 5},
],
by="analyst@corp.com",
label="confidential",
)
# Load and save
unit = akf.load("report.akf")
unit = akf.loads('{"version":"1.0","claims":[{"content":"test","confidence":0.9}]}')
unit.save("output.akf")
# Validate
result = akf.validate(unit) # or akf.validate("report.akf")
# result.valid -> bool
# result.errors -> List[str]
# result.warnings -> List[str]
# result.level -> int (0-3)
```
### Builder
```python
from akf import AKFBuilder
unit = (AKFBuilder()
.claim("Revenue grew 12%", 0.98, source="SEC Filing", authority_tier=1)
.claim("Market share ~34%", 0.72, ai_generated=True, authority_tier=5, risk="Estimated")
.by("analyst@corp.com")
.agent("copilot-v4")
.label("confidential")
.inherit()
.ttl(365)
.tag("financial", "q2")
.meta(project="Q2 Analysis")
.build())
# Automatically creates provenance hop 0 and computes integrity hash
```
### Trust
```python
import akf
result = akf.effective_trust(claim, age_days=30, penalty=-0.05)
# result.score -> float
# result.decision -> "ACCEPT" | "LOW" | "REJECT"
# result.accepted -> bool
# result.breakdown -> {confidence, authority, tier, decay, penalty, penalty_factor}
# Human-readable trust explanation
print(akf.explain_trust(claim, age_days=30))
# "confidence=0.98 × tier_1_weight=1.00 × decay=0.79 → 0.77 (ACCEPT)"
# TrustLevel enum
from akf import TrustLevel
level = TrustLevel.from_score(0.85) # TrustLevel.ACCEPT
print(level.threshold) # 0.7
# Compute trust for all claims in a unit
results = akf.compute_all(unit, age_days=30, threshold=0.6)
```
### Provenance
```python
import akf
# Add a hop to the provenance chain
unit = akf.add_hop(unit, by="reviewer@corp.com", action="reviewed")
unit = akf.add_hop(unit, by="agent-x", action="transformed", penalty=-0.03)
# Verify chain integrity
valid = akf.validate_chain(unit.provenance)
# Compute hashes
hash = akf.compute_integrity_hash(unit)
# Pretty-print provenance
print(akf.format_tree(unit))
```
### Security
```python
import akf
rank = akf.label_rank("confidential") # -> 2
ok = akf.validate_inheritance(parent_unit, child_unit) # -> bool
can_share = akf.can_share_external(unit) # -> bool
labels = akf.inherit_label(parent_unit) # -> {"label": ..., "inherit": ..., "ext": ...}
# Security score (0-10 with grade A-F)
score = akf.security_score(unit)
print(f"Score: {score.score}/10, Grade: {score.grade}")
# Microsoft Purview DLP-compatible signals
signals = akf.purview_signals(unit)
# Detect classification laundering
warnings = akf.detect_laundering(unit)
```
### Transformer (Consume & Filter)
```python
from akf import AKFTransformer
derived = (AKFTransformer(parent_unit)
.filter(trust_min=0.6) # keep only high-trust claims
.penalty(-0.03) # apply transform penalty
.by("summarizer-agent")
.build())
# Inherits classification, appends "consumed" provenance hop
```
### Presets
```python
from akf.presets import TEMPLATES, register, get_template, list_templates
unit = TEMPLATES["financial_report"].create(
claims=[{"content": "Revenue data", "confidence": 0.95}],
by="analyst@corp.com",
)
# Available presets: financial_report, research_brief, public_knowledge,
# legal_document, ai_output, meeting_notes, incident_report,
# research_paper, press_release
# Register custom preset
from akf.presets import Template, register
register("my_template", Template(name="my_template", label="internal", decay=30))
# List available templates
print(list_templates())
```
---
## Agent Integration API
```python
import akf
# Consume existing AKF for agent use
derived = akf.consume("report.akf", "my-agent", trust_threshold=0.6)
# Derive from a parent unit
child = akf.derive(parent_unit, "my-agent", trust_threshold=0.6)
# Create from AI tool calls
claim = akf.from_tool_call({"content": "Result", "confidence": 0.8})
# Format claims as LLM context
context = akf.to_context(unit, max_tokens=2000)
# Get structured output schema for LLMs
schema = akf.response_schema("standard")
# Validate LLM output as AKF
result = akf.validate_output(llm_response_text)
if result.valid:
unit = result.unit
# Auto-detect AKF in files, dicts, or strings
detected = akf.detect(some_data)
# One-shot system prompt for any LLM
prompt = akf.generation_prompt()
```
---
## Compliance & Audit API
```python
import akf
# General compliance audit
result = akf.audit("report.akf")
print(f"Score: {result.score:.2f}, Compliant: {result.compliant}")
# result.checks -> list of individual check results
# result.recommendations -> list of improvement suggestions
# Check against specific regulations
result = akf.check_regulation("report.akf", "eu_ai_act") # EU AI Act
result = akf.check_regulation("report.akf", "sox") # Sarbanes-Oxley
result = akf.check_regulation("report.akf", "hipaa") # HIPAA
result = akf.check_regulation("report.akf", "gdpr") # GDPR
result = akf.check_regulation("report.akf", "nist_ai") # NIST AI RMF
# Generate audit trail
trail = akf.audit_trail("report.akf", format="markdown")
# Verify human oversight
oversight = akf.verify_human_oversight("report.akf")
print(oversight["has_human_oversight"], oversight["human_actors"])
```
---
## Knowledge Base API
```python
import akf
# Persistent directory-backed knowledge store
kb = akf.KnowledgeBase("./kb")
# Add claims by topic
kb.add("Revenue was $4.2B", 0.98, source="SEC", topic="finance")
kb.add("Cloud grew 15%", 0.85, source="Gartner", topic="cloud")
# Query
claims = kb.query(topic="finance", min_trust=0.6)
# Format for LLM context injection
context = kb.to_context(max_tokens=2000)
# Maintenance
kb.prune(max_age_days=90, min_trust=0.3)
stats = kb.stats() # {"topics": 2, "total_claims": 2, "average_trust": 0.915}
```
---
## Views & Reporting API
```python
import akf
# Pretty terminal output with color
akf.show("report.akf")
# Generate standalone HTML report
html = akf.to_html("report.akf")
# Generate Markdown
md = akf.to_markdown("report.akf")
# Plain English executive summary
summary = akf.executive_summary("report.akf")
```
---
## Data Operations API
```python
import akf
# Load claims from multiple files
claims = akf.load_dataset(["a.akf", "b.akf"], filters={"min_trust": 0.6})
# Merge multiple units (deduplicates, takes highest classification)
merged = akf.merge([unit1, unit2, unit3])
# Filter claims
filtered = akf.filter_claims(unit, min_trust=0.5, verified_only=True, exclude_ai=True)
# Quality report
report = akf.quality_report(unit)
print(report["quality_score"], report["verified_claims"])
```
---
## Security Analysis API
```python
import akf
# Security score (0-10 with grade A-F)
score = akf.security_score(unit)
print(f"Score: {score.score}/10, Grade: {score.grade}")
# score.checks -> list of checks with pass/fail
# score.issues -> list of security issues
# Microsoft Purview DLP-compatible signals
signals = akf.purview_signals(unit)
# {"sensitivity_label", "has_ai_content", "highest_tier", "unverified_count", ...}
# Detect classification laundering
warnings = akf.detect_laundering(unit)
# ["AI claim with tier 5 but no risk description", ...]
```
---
## Universal Format Embedding
```python
import akf
# Embed AKF metadata into any supported file
akf.embed("report.docx", classification="confidential",
claims=[{"content": "Key finding", "confidence": 0.9}])
# Extract AKF metadata from a file
metadata = akf.extract("report.docx")
# Check if a file has AKF metadata
enriched = akf.is_enriched("report.docx")
# Scan for trust assessment
report = akf.scan("report.docx")
# report.enriched, report.classification, report.overall_trust,
# report.ai_contribution, report.claim_count, report.risk_claims, etc.
# Get human-readable info
print(akf.info("report.docx"))
# Scan entire directory
reports = akf.universal.scan_directory("./knowledge-base/", recursive=True)
# Convert any file to standalone .akf
akf.universal.to_akf("report.docx", "report.akf")
# Create sidecar for unsupported formats
akf.universal.create_sidecar("video.mp4", metadata_dict)
```
### Embedding Mechanisms by Format
| Format | Mechanism |
|--------|-----------|
| Markdown (`.md`, `.mdx`) | YAML frontmatter |
| HTML (`.html`, `.htm`) | `<script type="application/ld+json">` |
| JSON (`.json`) | `_akf` reserved key |
| DOCX (`.docx`) | OOXML custom XML part |
| XLSX (`.xlsx`) | OOXML custom XML part |
| PPTX (`.pptx`) | OOXML custom XML part |
| PDF (`.pdf`) | PDF metadata |
| Images (`.png`, `.jpg`, `.tiff`, `.webp`) | EXIF/XMP metadata |
| Email (`.eml`, `.msg`) | Email headers |
| Everything else | Sidecar `.akf.json` file |
---
## TypeScript SDK API Reference
### Install
```bash
npm install akf
```
ES Module, TypeScript 5.7+.
### Core Functions
```typescript
import { create, createMulti, validate, toJSON, fromJSON, toDescriptive } from 'akf';
// Create single-claim unit
const unit = create("Claim text", 0.95, { src: "Source", tier: 1 });
// Create multi-claim unit
const unit2 = createMulti(
[
{ c: "Claim 1", t: 0.95, src: "Source A", tier: 1 },
{ c: "Claim 2", t: 0.70, ai: true, tier: 5 },
],
{ by: "analyst@corp.com", label: "confidential" }
);
// Parse descriptive JSON (auto-normalizes to compact)
const loaded = fromJSON('{"version":"1.0","claims":[{"content":"test","confidence":0.8}]}');
// Convert to descriptive for display
const descriptive = toDescriptive(unit);
// { version: "1.0", claims: [{ content: "...", confidence: 0.95, source: "..." }] }
// Serialize / deserialize
const json = toJSON(unit, 2);
const parsed = fromJSON(json);
// Validate
const result = validate(unit);
// result.valid, result.errors, result.warnings, result.level
```
### Normalization
```typescript
import { normalizeClaim, normalizeUnit, toDescriptiveClaim } from 'akf';
// Normalize descriptive to compact (for processing)
const claim = normalizeClaim({ content: "test", confidence: 0.8, source: "SEC" });
// { c: "test", t: 0.8, src: "SEC" }
const unit = normalizeUnit({
version: "1.0",
classification: "internal",
claims: [{ content: "test", confidence: 0.8 }],
});
// { v: "1.0", label: "internal", claims: [{ c: "test", t: 0.8 }] }
// Convert back to descriptive (for display)
const desc = toDescriptiveClaim({ c: "test", t: 0.8, src: "SEC", ai: true });
// { content: "test", confidence: 0.8, source: "SEC", ai_generated: true }
```
### Types
```typescript
import type { AKFUnit, Claim, ProvHop, Fidelity, ValidationResult, TrustResult } from 'akf';
interface AKFUnit {
v: string;
claims: Claim[];
id?: string;
by?: string;
agent?: string;
at?: string;
label?: string;
inherit?: boolean;
ext?: boolean;
ttl?: number;
prov?: ProvHop[];
hash?: string;
meta?: Record<string, unknown>;
[key: string]: unknown;
}
interface Claim {
c: string;
t: number;
id?: string;
src?: string;
uri?: string;
tier?: number;
ver?: boolean;
ver_by?: string;
ai?: boolean;
risk?: string;
decay?: number;
exp?: string;
tags?: string[];
contra?: string;
fidelity?: Fidelity;
[key: string]: unknown;
}
```
### Builder
```typescript
import { AKFBuilder } from 'akf';
const unit = new AKFBuilder()
.claim("Revenue grew 12%", 0.98, { src: "SEC Filing", tier: 1 })
.claim("Market share ~34%", 0.72, { ai: true, tier: 5, risk: "Estimated" })
.by("analyst@corp.com")
.agent("copilot-v4")
.label("confidential")
.inherit()
.ttl(365)
.tag("financial", "q2")
.meta({ project: "Q2 Analysis" })
.build();
```
### Trust
```typescript
import { effectiveTrust, AUTHORITY_WEIGHTS, DECAY_PRESETS } from 'akf';
const result = effectiveTrust(claim, 30, -0.05);
// result.score, result.decision ("ACCEPT"|"LOW"|"REJECT")
// result.breakdown.{confidence, authority, tier, decay, penalty, penalty_factor}
```
### Provenance
```typescript
import {
addHop, validateChain, computeIntegrityHash, computeHopHash, formatTree
} from 'akf';
const updated = addHop(unit, "reviewer@corp.com", "reviewed");
const withPenalty = addHop(unit, "agent-x", "transformed", { penalty: -0.03 });
const valid = validateChain(unit.prov!);
const hash = computeIntegrityHash(unit);
console.log(formatTree(unit));
```
### Security
```typescript
import { labelRank, validateInheritance, canShareExternal, inheritLabel, HIERARCHY } from 'akf';
labelRank("confidential"); // 2
validateInheritance(parentUnit, childUnit); // boolean
canShareExternal(unit); // boolean
inheritLabel(parentUnit); // { label, inherit, ext }
```
### Transformer
```typescript
import { AKFTransformer } from 'akf';
const derived = new AKFTransformer(parentUnit)
.filter(0.6)
.penalty(-0.03)
.by("summarizer-agent")
.build();
```
---
## CLI Reference
### Getting Started
```bash
akf # Welcome message + quick start guide
akf create --demo # Create a demo file with walkthrough
```
### Standalone .akf Commands
```bash
akf create report.akf --claim "Revenue grew 12%" --trust 0.98 --src "SEC" --by analyst@corp.com --label confidential
akf validate report.akf
akf inspect report.akf
akf trust report.akf
akf consume report.akf --output brief.akf --threshold 0.6 --agent summarizer
akf provenance report.akf --format tree
akf enrich report.akf --agent copilot --claim "New insight" --trust 0.75
akf diff report.akf brief.akf
```
### Compliance & Audit
```bash
akf audit report.akf # General audit
akf audit report.akf --regulation eu_ai_act # EU AI Act check
akf audit report.akf --trail # Show audit trail
```
### Knowledge Base
```bash
akf kb stats ./kb # Show KB statistics
akf kb query ./kb --topic finance # Query by topic
akf kb prune ./kb --max-age 90 --min-trust 0.3 # Prune stale claims
```
### Universal Format Commands
```bash
akf embed report.docx --classification confidential --claim "Key finding" --trust 0.98
akf extract report.docx
akf info report.docx
akf scan report.docx
akf scan ./knowledge-base/ --recursive
akf convert report.docx --output report.akf
akf sidecar video.mp4 --classification internal
akf formats
```
---
## Framework Integrations
### langchain-akf
```python
from langchain_akf import AKFCallbackHandler, AKFLoader
# Auto-wrap chain outputs in AKF
handler = AKFCallbackHandler(agent_id="my-chain", default_trust=0.8)
chain.invoke({"input": "..."}, config={"callbacks": [handler]})
# Load .akf files as LangChain Documents
loader = AKFLoader("report.akf", min_trust=0.6)
docs = loader.load()
```
### mcp-server-akf
MCP server providing tools: `create_claim`, `validate_file`, `scan_file`, `trust_score`
```bash
pip install mcp-server-akf
```
---
## Common Use Cases
### 1. AI Agent Creating a Research Brief
```python
import akf
unit = (akf.AKFBuilder()
.claim("Global EV market reached $500B in 2024",
0.92, source="Bloomberg NEF", authority_tier=2)
.claim("Tesla's market share declined to 18%",
0.78, source="Industry estimate", authority_tier=3,
ai_generated=True, risk="Multiple conflicting sources")
.by("research-agent-v2")
.agent("research-agent-v2")
.label("internal")
.build())
unit.save("ev-market-brief.akf")
```
### 2. Consuming and Filtering Upstream Knowledge
```python
import akf
# One-line consumption
derived = akf.consume("market-data.akf", "downstream-agent", trust_threshold=0.7)
# Or use the transformer
from akf import AKFTransformer
upstream = akf.load("market-data.akf")
filtered = (AKFTransformer(upstream)
.filter(trust_min=0.7)
.penalty(-0.03)
.by("downstream-agent")
.build())
```
### 3. Compliance Check Before Publishing
```python
import akf
# Audit against multiple regulations
for reg in ["eu_ai_act", "sox", "gdpr"]:
result = akf.check_regulation("report.akf", reg)
print(f"{reg}: {'PASS' if result.compliant else 'FAIL'} ({result.score:.0%})")
# Verify human oversight
oversight = akf.verify_human_oversight("report.akf")
if not oversight["has_human_oversight"]:
print("Warning: No human actors in provenance chain")
```
### 4. Building a Knowledge Base
```python
import akf
kb = akf.KnowledgeBase("./project-kb")
# Add from various sources
kb.add("API latency p99 < 200ms", 0.88, source="APM", topic="performance")
kb.add("Zero critical CVEs", 0.95, source="Snyk", topic="security")
kb.add("User satisfaction 4.2/5", 0.72, source="Survey", topic="product")
# Inject into LLM context
context = kb.to_context(max_tokens=2000)
# Use context in your LLM prompt
# Maintenance
kb.prune(max_age_days=90, min_trust=0.3)
print(kb.stats())
```
### 5. Embedding Trust Metadata into Documents
```python
import akf
akf.embed("quarterly-report.docx",
classification="confidential",
claims=[
{"content": "Revenue exceeded targets by 15%", "confidence": 0.95, "verified": True},
{"content": "Projected growth of 20% next quarter", "confidence": 0.60, "ai_generated": True},
])
# Later, extract and scan
metadata = akf.extract("quarterly-report.docx")
report = akf.scan("quarterly-report.docx")
print(f"Trust: {report.overall_trust:.2f}, AI claims: {report.ai_claim_count}")
```
### 6. TypeScript: Building with Normalization
```typescript
import { AKFBuilder, validate, effectiveTrust, fromJSON, toDescriptive } from 'akf';
// Build a unit
const unit = new AKFBuilder()
.claim("API latency p99 < 200ms", 0.88, { src: "APM", tier: 2 })
.claim("No critical CVEs", 0.95, { src: "Snyk", tier: 1, ver: true })
.by("ci-pipeline")
.label("internal")
.build();
// Validate and check trust
const validation = validate(unit);
for (const claim of unit.claims) {
const trust = effectiveTrust(claim);
console.log(`"${claim.c}" -> ${trust.decision} (${trust.score.toFixed(2)})`);
}
// Accept descriptive input, normalize for processing
const loaded = fromJSON('{"version":"1.0","claims":[{"content":"test","confidence":0.8}]}');
// Convert to descriptive for display
const readable = toDescriptive(loaded);
console.log(JSON.stringify(readable, null, 2));
```
---
## Links
- GitHub: https://github.com/HMAKT99/AKF
- Spec: https://github.com/HMAKT99/AKF/blob/main/spec/akf-v1.0-spec.md
- JSON Schema: https://github.com/HMAKT99/AKF/blob/main/spec/akf-v1.0.schema.json
- Concise summary: https://akf.dev/llms.txt
- License: MIT