# 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 - Provenance Fields - Fidelity (Multi-Resolution) - Security Classification - Trust Computation - Validation Rules - Integrity Hashing - Secure Defaults - 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 | | `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 | ### 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 --- ## 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:` - **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. --- ## 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`) | `