Grant Capability

Overview

Award a verified skill or capability to a human or agent based on demonstrated evidence. Every capability grant is cryptographically signed, provenance-tracked, and backed by evidence—making it verifiable and unforgeable.

Why Grant Capabilities?

• Verifiable Skills: Not self-reported—capabilities require evidence
• Routing: HumanOS uses capabilities to match tasks to qualified humans/agents
• Meritocratic: Capabilities are earned through demonstrations, not claims
• Dynamic: Capabilities evolve as humans/agents gain experience
• Portable: Capabilities are owned by the individual, not by any platform

Think of it like: Earning a certification, but it's backed by real work you've done, cryptographically verified, and follows you everywhere.

SDK Examples

typescript:TypeScript
```typescript
import { HumanOS } from '@human/sdk';

async function grantCapability(
  recipientPassportDid: string,
  capabilityName: string,
  evidence: CapabilityEvidence
) {
  try {
    const grant = await HumanOS.CapabilityGraph.grantCapability({
      recipientDid: recipientPassportDid,
      capability: {
        name: capabilityName,
        category: 'ai_safety', // Category for organization
        weight: 0.8, // 0.0 to 1.0 (confidence level)
      },
      evidence: {
        type: 'task_completion', // 'training', 'credential', 'peer_review'
        description: 'Successfully completed 15 AI safety evaluations with 95% accuracy',
        metadata: {
          taskType: 'safety_evaluation',
          tasksCompleted: 15,
          accuracyRate: 0.95,
          startDate: '2026-01-01',
          endDate: '2026-01-10',
        },
        signedBy: 'did:human:supervisor-bob', // Attestor's DID
      },
    });
    
    console.log(`✓ Capability granted: ${capabilityName}`);
    console.log(`  Recipient: ${recipientPassportDid}`);
    console.log(`  Weight: ${grant.weight}`);
    console.log(`  Evidence: ${grant.evidenceCount} supporting records`);
    console.log(`  Ledger proof: ${grant.ledgerProof}`);
    
    return grant;
  } catch (error) {
    console.error("Failed to grant capability:", error);
    throw error;
  }
}

// Example usage:
await grantCapability(
  "did:human:alice-smith",
  "ai_safety_evaluation",
  {
    type: 'task_completion',
    description: 'Completed safety eval training + 15 live evaluations',
    metadata: { tasksCompleted: 15, accuracyRate: 0.95 },
    signedBy: 'did:human:supervisor-bob'
  }
);
```

python:Python
```python
from human_sdk import HumanOS

async def grant_capability(
    recipient_passport_did: str,
    capability_name: str,
    evidence: dict
):
    try:
        grant = await HumanOS.CapabilityGraph.grant_capability(
            recipient_did=recipient_passport_did,
            capability={
                'name': capability_name,
                'category': 'ai_safety',  # Category for organization
                'weight': 0.8  # 0.0 to 1.0 (confidence level)
            },
            evidence={
                'type': 'task_completion',  # 'training', 'credential', 'peer_review'
                'description': 'Successfully completed 15 AI safety evaluations with 95% accuracy',
                'metadata': {
                    'task_type': 'safety_evaluation',
                    'tasks_completed': 15,
                    'accuracy_rate': 0.95,
                    'start_date': '2026-01-01',
                    'end_date': '2026-01-10'
                },
                'signed_by': 'did:human:supervisor-bob'  # Attestor's DID
            }
        )
        
        print(f"✓ Capability granted: {capability_name}")
        print(f"  Recipient: {recipient_passport_did}")
        print(f"  Weight: {grant.weight}")
        print(f"  Evidence: {grant.evidence_count} supporting records")
        print(f"  Ledger proof: {grant.ledger_proof}")
        
        return grant
    except Exception as error:
        print(f"Failed to grant capability: {error}")
        raise

# Example usage:
# await grant_capability(
#     "did:human:alice-smith",
#     "ai_safety_evaluation",
#     {
#         'type': 'task_completion',
#         'description': 'Completed safety eval training + 15 live evaluations',
#         'metadata': {'tasks_completed': 15, 'accuracy_rate': 0.95},
#         'signed_by': 'did:human:supervisor-bob'
#     }
# )
```

go:Go
```go
package main

import (
    "fmt"
    "github.com/human/sdk-go/humanos"
)

func grantCapability(recipientDID, capabilityName string, evidence humanos.Evidence) (*humanos.CapabilityGrant, error) {
    grant, err := humanos.CapabilityGraph.GrantCapability(&humanos.GrantRequest{
        RecipientDID: recipientDID,
        Capability: &humanos.Capability{
            Name: capabilityName,
            Category: "ai_safety",
            Weight: 0.8,
        },
        Evidence: &evidence,
    })
    if err != nil {
        return nil, fmt.Errorf("failed to grant capability: %w", err)
    }
    
    fmt.Printf("✓ Capability granted: %s\n", capabilityName)
    fmt.Printf("  Recipient: %s\n", recipientDID)
    fmt.Printf("  Weight: %.2f\n", grant.Weight)
    fmt.Printf("  Evidence: %d supporting records\n", grant.EvidenceCount)
    fmt.Printf("  Ledger proof: %s\n", grant.LedgerProof)
    
    return grant, nil
}

// Example usage:
// grant, err := grantCapability(
//     "did:human:alice-smith",
//     "ai_safety_evaluation",
//     humanos.Evidence{
//         Type: "task_completion",
//         Description: "Completed safety eval training + 15 live evaluations",
//         Metadata: map[string]interface{}{
//             "tasks_completed": 15,
//             "accuracy_rate": 0.95,
//         },
//         SignedBy: "did:human:supervisor-bob",
//     },
// )
```

REST API Example

POST /v1/capability-graph/grant
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY_OR_OAUTH_TOKEN>

{
  "recipientDid": "did:human:alice-smith",
  "capability": {
    "name": "ai_safety_evaluation",
    "category": "ai_safety",
    "weight": 0.8
  },
  "evidence": {
    "type": "task_completion",
    "description": "Successfully completed 15 AI safety evaluations with 95% accuracy",
    "metadata": {
      "taskType": "safety_evaluation",
      "tasksCompleted": 15,
      "accuracyRate": 0.95,
      "startDate": "2026-01-01",
      "endDate": "2026-01-10"
    },
    "signedBy": "did:human:supervisor-bob"
  }
}

Response (201 Created):

{
  "capabilityId": "capability:human:a1b2c3d4...",
  "recipientDid": "did:human:alice-smith",
  "name": "ai_safety_evaluation",
  "weight": 0.8,
  "evidenceCount": 1,
  "ledgerProof": "0x7b3f9a2c...",
  "createdAt": "2026-01-10T12:00:00Z"
}

Types of Evidence

Capabilities require evidence to be granted. Here are the supported types:

Evidence Type	Description	Example
task_completion	Demonstrated through work	50 data labeling tasks completed with 98% accuracy
training	Academy courses or certifications	Completed "AI Safety Fundamentals" course
credential	External credentials imported	AWS Solutions Architect certification
peer_review	Endorsed by another human	5 engineers vouch for your Python expertise
manual	Admin/supervisor manual attestation	Manager attests to leadership capability

users:Skill Certification|Automatically grant a "Certified AI Safety Evaluator" capability upon successful completion of a HUMAN Academy course.
building:Enterprise Talent Management|Managers grant "Project Leadership" capabilities to employees based on performance reviews and project outcomes.
bot:Agent Specialization|Define and grant specific capabilities (e.g., "Financial Analysis", "Medical Diagnosis") to AI agents for specialized tasks.
cloud:Workforce Cloud Matching|HUMANOS matches tasks to humans or agents with verified capabilities, ensuring optimal task routing and quality.

Use Cases

1. Grant Capability After Training

Scenario: A human completes training in the HUMΛN Academy—automatically grant the capability.

typescript:TypeScript
```typescript
// Academy completion triggers capability grant
async function onAcademyCourseComplete(
  studentDid: string,
  courseId: string
) {
  // Step 1: Verify course completion
  const completion = await HumanOS.Academy.getCourseCompletion({
    studentDid: studentDid,
    courseId: courseId,
  });
  
  if (!completion.passed) {
    throw new Error('Course not passed');
  }
  
  // Step 2: Grant capability based on course
  const capability = await HumanOS.CapabilityGraph.grantCapability({
    recipientDid: studentDid,
    capability: {
      name: completion.capabilityName, // e.g., "python_programming"
      category: completion.category,
      weight: completion.finalScore / 100, // 0.0 to 1.0
    },
    evidence: {
      type: 'training',
      description: `Completed ${completion.courseName} with score ${completion.finalScore}%`,
      metadata: {
        courseId: courseId,
        finalScore: completion.finalScore,
        modulesCompleted: completion.modulesCompleted,
        projectsSubmitted: completion.projectsSubmitted,
      },
      signedBy: 'did:human:academy-system',
    },
  });
  
  console.log(`✓ Capability "${capability.name}" granted to ${studentDid}`);
  return capability;
}
```

python:Python
```python
# Academy completion triggers capability grant
async def on_academy_course_complete(
    student_did: str,
    course_id: str
):
    # Step 1: Verify course completion
    completion = await HumanOS.Academy.get_course_completion(
        student_did=student_did,
        course_id=course_id
    )
    
    if not completion.passed:
        raise Exception('Course not passed')
    
    # Step 2: Grant capability based on course
    capability = await HumanOS.CapabilityGraph.grant_capability(
        recipient_did=student_did,
        capability={
            'name': completion.capability_name,  # e.g., "python_programming"
            'category': completion.category,
            'weight': completion.final_score / 100  # 0.0 to 1.0
        },
        evidence={
            'type': 'training',
            'description': f"Completed {completion.course_name} with score {completion.final_score}%",
            'metadata': {
                'course_id': course_id,
                'final_score': completion.final_score,
                'modules_completed': completion.modules_completed,
                'projects_submitted': completion.projects_submitted
            },
            'signed_by': 'did:human:academy-system'
        }
    )
    
    print(f"✓ Capability \"{capability.name}\" granted to {student_did}")
    return capability
```

2. Grant Capability After Task Completion

Scenario: A human completes multiple tasks in the Workforce Cloud—capability weight increases with demonstrated proficiency.

typescript:TypeScript
```typescript
// After human completes 10 tasks, strengthen capability
async function updateCapabilityAfterTaskCompletion(
  humanDid: string,
  task: Task,
  performance: PerformanceMetrics
) {
  // Check if capability already exists
  const existing = await HumanOS.CapabilityGraph.getCapability({
    passportDid: humanDid,
    capabilityName: task.requiredCapability,
  });
  
  // Calculate new weight based on performance
  const performanceScore = (
    performance.accuracy * 0.5 +
    performance.efficiency * 0.3 +
    performance.quality * 0.2
  );
  
  if (existing) {
    // Update existing capability (strengthen)
    await HumanOS.CapabilityGraph.updateCapability({
      capabilityId: existing.id,
      weightDelta: 0.05 * performanceScore, // Incremental increase
      evidence: {
        type: 'task_completion',
        description: `Completed ${task.type} with ${(performanceScore * 100).toFixed(0)}% performance`,
        metadata: {
          taskId: task.id,
          performance: performance,
        },
        signedBy: 'did:human:humanos-system',
      },
    });
  } else {
    // Grant new capability
    await HumanOS.CapabilityGraph.grantCapability({
      recipientDid: humanDid,
      capability: {
        name: task.requiredCapability,
        category: task.category,
        weight: 0.5 * performanceScore, // Start at moderate weight
      },
      evidence: {
        type: 'task_completion',
        description: `First ${task.type} completed`,
        metadata: { taskId: task.id, performance: performance },
        signedBy: 'did:human:humanos-system',
      },
    });
  }
  
  console.log(`✓ Capability updated for ${humanDid}`);
}
```

python:Python
```python
# After human completes 10 tasks, strengthen capability
async def update_capability_after_task_completion(
    human_did: str,
    task: Task,
    performance: dict
):
    # Check if capability already exists
    existing = await HumanOS.CapabilityGraph.get_capability(
        passport_did=human_did,
        capability_name=task.required_capability
    )
    
    # Calculate new weight based on performance
    performance_score = (
        performance['accuracy'] * 0.5 +
        performance['efficiency'] * 0.3 +
        performance['quality'] * 0.2
    )
    
    if existing:
        # Update existing capability (strengthen)
        await HumanOS.CapabilityGraph.update_capability(
            capability_id=existing.id,
            weight_delta=0.05 * performance_score,  # Incremental increase
            evidence={
                'type': 'task_completion',
                'description': f"Completed {task.type} with {int(performance_score * 100)}% performance",
                'metadata': {
                    'task_id': task.id,
                    'performance': performance
                },
                'signed_by': 'did:human:humanos-system'
            }
        )
    else:
        # Grant new capability
        await HumanOS.CapabilityGraph.grant_capability(
            recipient_did=human_did,
            capability={
                'name': task.required_capability,
                'category': task.category,
                'weight': 0.5 * performance_score  # Start at moderate weight
            },
            evidence={
                'type': 'task_completion',
                'description': f"First {task.type} completed",
                'metadata': {'task_id': task.id, 'performance': performance},
                'signed_by': 'did:human:humanos-system'
            }
        )
    
    print(f"✓ Capability updated for {human_did}")
```

3. Import External Credential

Scenario: A human has an external credential (AWS cert, university degree)—import it as a capability.

typescript:TypeScript
```typescript
async function importExternalCredential(
  humanDid: string,
  credentialType: string,
  verificationProof: string
) {
  // Verify external credential (e.g., via API call to AWS, university, etc.)
  const verified = await verifyExternalCredential({
    type: credentialType,
    proof: verificationProof,
  });
  
  if (!verified.valid) {
    throw new Error('Credential verification failed');
  }
  
  // Grant capability based on external credential
  await HumanOS.CapabilityGraph.grantCapability({
    recipientDid: humanDid,
    capability: {
      name: verified.capabilityName, // e.g., "aws_solutions_architect"
      category: verified.category,
      weight: 0.9, // High weight for verified external credentials
    },
    evidence: {
      type: 'credential',
      description: `Verified ${credentialType}: ${verified.credentialName}`,
      metadata: {
        credentialType: credentialType,
        issuer: verified.issuer,
        issueDate: verified.issueDate,
        expiryDate: verified.expiryDate,
        verificationUrl: verified.verificationUrl,
      },
      signedBy: 'did:human:credential-verifier-system',
    },
  });
  
  console.log(`✓ External credential imported as capability`);
}
```

python:Python
```python
async def import_external_credential(
    human_did: str,
    credential_type: str,
    verification_proof: str
):
    # Verify external credential (e.g., via API call to AWS, university, etc.)
    verified = await verify_external_credential(
        type=credential_type,
        proof=verification_proof
    )
    
    if not verified.valid:
        raise Exception('Credential verification failed')
    
    # Grant capability based on external credential
    await HumanOS.CapabilityGraph.grant_capability(
        recipient_did=human_did,
        capability={
            'name': verified.capability_name,  # e.g., "aws_solutions_architect"
            'category': verified.category,
            'weight': 0.9  # High weight for verified external credentials
        },
        evidence={
            'type': 'credential',
            'description': f"Verified {credential_type}: {verified.credential_name}",
            'metadata': {
                'credential_type': credential_type,
                'issuer': verified.issuer,
                'issue_date': verified.issue_date,
                'expiry_date': verified.expiry_date,
                'verification_url': verified.verification_url
            },
            'signed_by': 'did:human:credential-verifier-system'
        }
    )
    
    print("✓ External credential imported as capability")
```

Capability Weights

Capability weights range from 0.0 to 1.0, representing confidence/proficiency:

Weight Range	Meaning	Example
0.0 - 0.3	Novice	Just started learning Python
0.3 - 0.6	Intermediate	Can complete routine Python tasks
0.6 - 0.8	Advanced	Expert-level Python development
0.8 - 1.0	Master	World-class Python expertise, mentors others

Weights are updated dynamically as humans gain experience and complete more tasks.

do:Verify the `signedBy` entity is authorized and trustworthy to attest to the capability.
do:Assign a `weight` that accurately reflects the confidence and proficiency level of the granted capability.
do:Ensure all capability grants are recorded on the provenance ledger for an immutable audit trail.
do:Implement granular access control for who can grant specific types of capabilities.
do:Use peer review for subjective capabilities (e.g., leadership).
dont:Grant capabilities without strong, verifiable evidence; this undermines trust.
dont:Over-inflate capability weights, as it can lead to incorrect task routing and misrepresentation.
dont:Allow self-attestation of critical capabilities without external verification.
dont:Forget to define clear expiration or re-certification policies for time-sensitive capabilities.

Provenance

Every capability grant is permanently recorded:

{
  "eventType": "capability_granted",
  "recipientDid": "did:human:alice-smith",
  "capabilityName": "ai_safety_evaluation",
  "weight": 0.8,
  "evidenceType": "task_completion",
  "attestorDid": "did:human:supervisor-bob",
  "ledgerSignature": "0x7b3f9a2c...",
  "timestamp": "2026-01-10T12:00:00Z"
}

This creates an immutable capability history that can be verified by anyone.

users:Skill Recognition|Award capabilities after completing training courses or certifications
building:Performance Reviews|Grant capabilities based on demonstrated work quality
bot:Agent Qualification|Define and grant specific capabilities to AI agents based on testing
network:Task Routing|Use granted capabilities to match qualified workers to tasks

do:Require cryptographic proof of evidence before granting
do:Set appropriate confidence levels (weight) based on evidence quality
do:Anchor all capability grants to the provenance ledger
do:Implement expiry dates for time-sensitive capabilities
dont:Grant capabilities without verifiable evidence
dont:Allow self-attestation without third-party validation
dont:Over-inflate capability weights to game routing
dont:Skip verification of the grantor's authority

Next Steps

• Learn how to Verify Capabilities
• Understand Capability Routing
• Explore Training in Academy

---

See Also

• Concept Doc: Capability Graph
• API Reference: Grant Capability API
• SDK Reference: CapabilityGraph.grantCapability()