contract-analyzer

/**
 * Contract Analyzer - Production Reference Agent
 *
 * Canon alignment: KB 105, P5 (Human-in-Loop)
 * Demonstrates: ctx.files, ctx.llm, ctx.escalate()
 *
 * Real use case: Extract clauses, identify risks, flag for legal review
 * when high-risk terms detected.
 */

import { handler, withProvenanceContext } from '@human/agent-sdk';
import type { ExecutionContext } from '@human/agent-sdk';

export const AGENT_ID = 'contract-analyzer';
export const VERSION = '1.0.0';
export const CAPABILITIES = ['legal/contract/analyze'];

export interface ContractAnalyzerInput {
  contract_path: string;
  /** Risk threshold for escalation (0-1) */
  risk_escalation_threshold?: number;
}

export interface ContractAnalyzerOutput {
  success: boolean;
  clauses: Array<{ name: string; summary: string; risk: 'low' | 'medium' | 'high' }>;
  overall_risk: 'low' | 'medium' | 'high';
  escalation_required: boolean;
  escalation_reason?: string;
  provenance_id: string;
}

const execute = async (
  ctx: ExecutionContext,
  input: ContractAnalyzerInput
): Promise<ContractAnalyzerOutput> => {
  ctx.log.info('Analyzing contract', { path: input.contract_path });

  const content = await ctx.files.readText(input.contract_path);
  const threshold = input.risk_escalation_threshold ?? 0.7;

  const result = await ctx.llm.complete({
    prompt: [
      {
        role: 'system',
        content: `Analyze contract and return JSON: { "clauses": [{"name":"","summary":"","risk":"low|medium|high"}], "overall_risk": "low|medium|high" }. Only return valid JSON.`,
      },
      {
        role: 'user',
        content: `Analyze this contract:\n\n${content.slice(0, 8000)}`,
      },
    ],
    temperature: 0.2,
    maxTokens: 2000,
  });

  let clauses: ContractAnalyzerOutput['clauses'] = [];
  let overallRisk: ContractAnalyzerOutput['overall_risk'] = 'low';

  try {
    const parsed = JSON.parse(result.content) as {
      clauses?: ContractAnalyzerOutput['clauses'];
      overall_risk?: ContractAnalyzerOutput['overall_risk'];
    };
    clauses = parsed.clauses ?? [];
    overallRisk = parsed.overall_risk ?? 'low';
  } catch {
    clauses = [];
  }

  const riskScore = { low: 0, medium: 0.5, high: 1 }[overallRisk];
  const escalationRequired = riskScore >= threshold;

  if (escalationRequired) {
    const decision = await ctx.escalate({
      reason: 'Contract contains high-risk terms - legal review required',
      context: {
        contract_path: input.contract_path,
        overall_risk: overallRisk,
        clauses: clauses.filter((c) => c.risk === 'high'),
      },
      requiredCapability: 'legal/review',
    });

    const provenanceId = await ctx.provenance.log(
      withProvenanceContext(ctx, {
        type: 'contract:escalation',
        status: 'success',
        metadata: {
          input: { contract_path: input.contract_path },
          output: {
            escalation_required: true,
            human_approved: decision.approved,
            reason: decision.reason,
          },
        },
      })
    );

    return {
      success: true,
      clauses,
      overall_risk: overallRisk,
      escalation_required: true,
      escalation_reason: decision.reason,
      provenance_id: provenanceId,
    };
  }

  const provenanceId = await ctx.provenance.log(
    withProvenanceContext(ctx, {
      type: 'contract:analyzed',
      status: 'success',
      metadata: {
        input: { contract_path: input.contract_path },
        output: { overall_risk: overallRisk, clause_count: clauses.length },
      },
    })
  );

  return {
    success: true,
    clauses,
    overall_risk: overallRisk,
    escalation_required: false,
    provenance_id: provenanceId,
  };
};

export default handler({
  name: AGENT_ID,
  id: AGENT_ID,
  version: VERSION,
  capabilities: CAPABILITIES,
  manifest: {
    operations: [
      {
        name: 'analyze',
        description: 'Extract clauses, assess risk, and flag for legal review when threshold exceeded',
        paramsSchema: {
          contract_path: { type: 'string', required: true, description: 'Path to contract file' },
          risk_escalation_threshold: { type: 'number', description: 'Risk threshold for escalation (0-1)' },
        },
        resultKind: 'agent.contract-analyzer.result',
      },
    ],
  },
  execute,
});