competitive-intelligence

/**
 * Competitive Intelligence - Production Reference Agent
 *
 * Canon alignment: KB 105
 * Demonstrates: ctx.queue, ctx.llm, ctx.cache
 *
 * Real use case: Monitor competitor sites, summarize changes, schedule jobs.
 */

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

export const AGENT_ID = 'competitive-intelligence';
export const VERSION = '1.0.0';
export const CAPABILITIES = ['research/competitive/monitor'];

export interface CompetitiveIntelInput {
  competitor_name: string;
  url?: string;
}

export interface CompetitiveIntelOutput {
  success: boolean;
  summary: string;
  cache_hit: boolean;
  job_id: string;
  provenance_id: string;
}

const execute = async (
  ctx: ExecutionContext,
  input: CompetitiveIntelInput
): Promise<CompetitiveIntelOutput> => {
  ctx.log.info('Monitoring competitor', { name: input.competitor_name });

  // Check cache for recent analysis (ctx.cache)
  const cacheKey = `competitive:${input.competitor_name}`;
  const cached = await ctx.cache.get(cacheKey);

  if (cached) {
    const provenanceId = await ctx.provenance.log(
      withProvenanceContext(ctx, {
        action: 'competitive:cache_hit',
        status: 'success',
        input: { competitor: input.competitor_name },
      })
    );
    return {
      success: true,
      summary: cached,
      cache_hit: true,
      job_id: '',
      provenance_id: provenanceId,
    };
  }

  // Generate analysis with LLM (ctx.llm)
  const analysis = await ctx.llm.complete({
    prompt: [
      {
        role: 'system',
        content: 'You are a competitive intelligence analyst. Provide a brief analysis.',
      },
      {
        role: 'user',
        content: `Analyze competitive positioning of: ${input.competitor_name}${input.url ? ` (${input.url})` : ''}`,
      },
    ],
    temperature: 0.4,
    maxTokens: 500,
  });

  // Cache result (ctx.cache)
  await ctx.cache.set(cacheKey, analysis.content, { ttl: 3600 });

  // Schedule follow-up job (ctx.queue)
  const jobId = await ctx.queue.enqueue('competitive:refresh', {
    competitor_name: input.competitor_name,
    url: input.url,
  });

  const provenanceId = await ctx.provenance.log(
    withProvenanceContext(ctx, {
      action: 'competitive:analyzed',
      status: 'success',
      input: { competitor: input.competitor_name },
      output: { job_id: jobId },
    })
  );

  return {
    success: true,
    summary: analysis.content,
    cache_hit: false,
    job_id: jobId,
    provenance_id: provenanceId,
  };
};

export default handler({
  name: AGENT_ID,
  id: AGENT_ID,
  version: VERSION,
  capabilities: CAPABILITIES,
  manifest: {
    operations: [
      {
        name: 'monitor',
        description: 'Monitor competitor, summarize changes, schedule refresh jobs',
        paramsSchema: {
          competitor_name: { type: 'string', required: true, description: 'Competitor name' },
          url: { type: 'string', description: 'Optional URL to monitor' },
        },
        resultKind: 'agent.competitive-intelligence.result',
      },
    ],
  },
  execute,
});