@auxiora/research 1.0.0

package/src/citation.ts

@@ -0,0 +1,80 @@
+import { nanoid } from 'nanoid';
+import type { Source, Finding } from './types.js';
+
+export class CitationTracker {
+  private sources = new Map<string, Source>();
+  private findings: Finding[] = [];
+
+  addSource(url: string, title: string, credibilityScore?: number): Source {
+    const parsed = new URL(url);
+    const domain = parsed.hostname.replace(/^www\./, '');
+
+    const source: Source = {
+      id: nanoid(),
+      url,
+      title,
+      domain,
+      accessedAt: Date.now(),
+      credibilityScore: credibilityScore ?? 0.5,
+    };
+
+    this.sources.set(source.id, source);
+    return source;
+  }
+
+  addFinding(content: string, sourceId: string, relevance?: number, category?: string): Finding {
+    const finding: Finding = {
+      id: nanoid(),
+      content,
+      sourceId,
+      relevance: relevance ?? 0.5,
+      category: category ?? 'general',
+    };
+
+    this.findings.push(finding);
+    return finding;
+  }
+
+  getSources(): Source[] {
+    return Array.from(this.sources.values());
+  }
+
+  getFindings(sourceId?: string): Finding[] {
+    if (sourceId) {
+      return this.findings.filter((f) => f.sourceId === sourceId);
+    }
+    return [...this.findings];
+  }
+
+  formatCitations(style: 'inline' | 'footnote' | 'bibliography'): string {
+    const sources = this.getSources();
+
+    switch (style) {
+      case 'inline':
+        return sources
+          .map((s, i) => `[${i + 1}] ${s.title} (${s.domain})`)
+          .join('\n');
+
+      case 'footnote':
+        return sources
+          .map((s, i) => {
+            const date = new Date(s.accessedAt).toISOString().split('T')[0];
+            return `^${i + 1} ${s.title}. ${s.url}. Accessed: ${date}`;
+          })
+          .join('\n');
+
+      case 'bibliography':
+        return sources
+          .map(
+            (s) =>
+              `${s.title}. ${s.domain}. ${s.url}. Credibility: ${s.credibilityScore.toFixed(2)}`,
+          )
+          .join('\n');
+    }
+  }
+
+  clear(): void {
+    this.sources.clear();
+    this.findings = [];
+  }
+}

package/src/credibility.ts

@@ -0,0 +1,65 @@
+import type { CredibilityFactors } from './types.js';
+
+const KNOWN_DOMAINS = new Map<string, number>([
+  ['wikipedia.org', 0.95],
+  ['arxiv.org', 0.95],
+  ['nature.com', 0.95],
+  ['science.org', 0.95],
+  ['bbc.com', 0.9],
+  ['reuters.com', 0.9],
+  ['apnews.com', 0.9],
+  ['nytimes.com', 0.8],
+  ['washingtonpost.com', 0.8],
+  ['theguardian.com', 0.8],
+  ['techcrunch.com', 0.8],
+  ['medium.com', 0.7],
+  ['stackoverflow.com', 0.7],
+  ['github.com', 0.7],
+  ['reddit.com', 0.5],
+  ['quora.com', 0.5],
+  ['twitter.com', 0.3],
+  ['facebook.com', 0.3],
+]);
+
+export class CredibilityScorer {
+  score(url: string, factors?: Partial<CredibilityFactors>): number {
+    const domain = this.extractDomain(url);
+    let score = this.getDomainReputation(domain);
+
+    if (factors?.isHttps) {
+      score += 0.05;
+    }
+    if (factors?.hasAuthor) {
+      score += 0.05;
+    }
+    if (factors?.hasDate) {
+      score += 0.05;
+    }
+    if (factors?.crossReferenced) {
+      score += 0.1;
+    }
+
+    return Math.min(Math.max(score, 0), 1);
+  }
+
+  getDomainReputation(domain: string): number {
+    const lookup = KNOWN_DOMAINS.get(domain);
+    if (lookup !== undefined) {
+      return lookup;
+    }
+
+    if (domain.endsWith('.gov')) {
+      return 0.9;
+    }
+    if (domain.endsWith('.edu')) {
+      return 0.9;
+    }
+
+    return 0.5;
+  }
+
+  extractDomain(url: string): string {
+    const parsed = new URL(url);
+    return parsed.hostname.replace(/^www\./, '');
+  }
+}

package/src/engine.ts

@@ -0,0 +1,244 @@
+import { nanoid } from 'nanoid';
+import type { ResearchDepth, ResearchQuery, ResearchResult, Finding, Source, ResearchProvider } from './types.js';
+import { BraveSearchClient } from './brave-search.js';
+import { CredibilityScorer } from './credibility.js';
+import { CitationTracker } from './citation.js';
+
+export interface ResearchEngineConfig {
+  maxConcurrentSources?: number;
+  defaultDepth?: ResearchDepth;
+  braveApiKey?: string;
+  searchTimeout?: number;
+  fetchTimeout?: number;
+  provider?: ResearchProvider;
+}
+
+export class ResearchEngine {
+  private readonly config: Required<Omit<ResearchEngineConfig, 'provider' | 'braveApiKey'>>;
+  private readonly braveClient: BraveSearchClient;
+  private readonly provider?: ResearchProvider;
+  private readonly credibilityScorer = new CredibilityScorer();
+
+  constructor(config?: ResearchEngineConfig) {
+    const apiKey = config?.braveApiKey ?? process.env.AUXIORA_RESEARCH_BRAVE_API_KEY;
+    if (!apiKey) {
+      throw new Error('Research engine requires a Brave Search API key (braveApiKey or AUXIORA_RESEARCH_BRAVE_API_KEY)');
+    }
+
+    this.config = {
+      maxConcurrentSources: config?.maxConcurrentSources ?? 5,
+      defaultDepth: config?.defaultDepth ?? 'standard',
+      searchTimeout: config?.searchTimeout ?? 10_000,
+      fetchTimeout: config?.fetchTimeout ?? 15_000,
+    };
+
+    this.braveClient = new BraveSearchClient({
+      apiKey,
+      searchTimeout: this.config.searchTimeout,
+      fetchTimeout: this.config.fetchTimeout,
+    });
+
+    this.provider = config?.provider;
+  }
+
+  async research(query: ResearchQuery): Promise<ResearchResult> {
+    const startTime = Date.now();
+    const depth = query.depth ?? this.config.defaultDepth;
+    const maxSources = query.maxSources ?? this.getMaxSources(depth);
+    const searchQueries = this.planResearch(query.topic, depth, query.focusAreas);
+
+    const tracker = new CitationTracker();
+    const findings: Finding[] = [];
+
+    // Execute searches in parallel, limited to maxSources total results
+    const searchPromises = searchQueries.map((q) => this.braveClient.search(q, 3));
+    const searchResults = await Promise.all(searchPromises);
+
+    // Flatten and deduplicate by URL, cap at maxSources
+    const seenUrls = new Set<string>();
+    const uniqueResults: { query: string; url: string; title: string; snippet: string }[] = [];
+
+    for (let i = 0; i < searchResults.length; i++) {
+      for (const result of searchResults[i]) {
+        if (!seenUrls.has(result.url) && uniqueResults.length < maxSources) {
+          seenUrls.add(result.url);
+          uniqueResults.push({
+            query: searchQueries[i],
+            url: result.url,
+            title: result.title,
+            snippet: result.description,
+          });
+        }
+      }
+    }
+
+    // Fetch pages in parallel
+    const fetchPromises = uniqueResults.map((r) => this.braveClient.fetchPage(r.url));
+    const pageContents = await Promise.all(fetchPromises);
+
+    // Process each result
+    for (let i = 0; i < uniqueResults.length; i++) {
+      const r = uniqueResults[i];
+      const credibility = this.credibilityScorer.score(r.url, {
+        isHttps: r.url.startsWith('https'),
+      });
+      const source = tracker.addSource(r.url, r.title, credibility);
+
+      const content = pageContents[i];
+      if (this.provider && content) {
+        // AI-powered extraction
+        const extracted = await this.extractFindings(r.query, content, r.title);
+        for (const text of extracted) {
+          tracker.addFinding(text, source.id, credibility, 'general');
+        }
+      } else {
+        // Fallback: use search snippet + first paragraph from fetched content
+        let text = r.snippet;
+        if (content) {
+          const firstParagraph = content.split('\n\n').find((p) => p.trim().length > 50);
+          if (firstParagraph) {
+            text += ' ' + firstParagraph.trim();
+          }
+        }
+        tracker.addFinding(text, source.id, credibility, 'general');
+      }
+    }
+
+    const allFindings = tracker.getFindings();
+    const deduplicated = this.deduplicateFindings(allFindings);
+    const sources = tracker.getSources();
+
+    // Synthesize summary
+    let executiveSummary: string;
+    if (this.provider && deduplicated.length > 0) {
+      executiveSummary = await this.synthesizeWithAI(query.topic, deduplicated, sources);
+    } else {
+      executiveSummary = this.synthesize(deduplicated);
+    }
+
+    return {
+      id: nanoid(),
+      query,
+      findings: deduplicated,
+      executiveSummary,
+      sources,
+      confidence: Math.min(deduplicated.length / maxSources, 1),
+      generatedAt: Date.now(),
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  planResearch(topic: string, depth: ResearchDepth, focusAreas?: string[]): string[] {
+    let queries: string[];
+    switch (depth) {
+      case 'quick':
+        queries = [topic];
+        break;
+      case 'standard':
+        queries = [topic, `${topic} overview`, `${topic} analysis`];
+        break;
+      case 'deep':
+        queries = [
+          topic,
+          `${topic} overview`,
+          `${topic} analysis`,
+          `${topic} comparison`,
+          `${topic} best practices`,
+          `${topic} research papers`,
+        ];
+        break;
+    }
+
+    if (focusAreas?.length) {
+      for (const area of focusAreas) {
+        queries.push(`${topic} ${area}`);
+      }
+    }
+
+    return queries;
+  }
+
+  synthesize(findings: Finding[]): string {
+    const sourceIds = new Set(findings.map((f) => f.sourceId));
+    const topFindings = findings
+      .sort((a, b) => b.relevance - a.relevance)
+      .slice(0, 3)
+      .map((f) => f.content);
+
+    return `Based on ${findings.length} findings from ${sourceIds.size} sources: ${topFindings.join('. ')}`;
+  }
+
+  deduplicateFindings(findings: Finding[]): Finding[] {
+    const seen = new Set<string>();
+    return findings.filter((f) => {
+      if (seen.has(f.content)) {
+        return false;
+      }
+      seen.add(f.content);
+      return true;
+    });
+  }
+
+  private async extractFindings(query: string, content: string, title: string): Promise<string[]> {
+    if (!this.provider) return [];
+
+    try {
+      const result = await this.provider.complete(
+        [{ role: 'user', content: `Extract key findings from this source about "${query}".\n\nSource: ${title}\n\nContent:\n${content.slice(0, 8000)}` }],
+        {
+          systemPrompt: 'You are a research assistant. Extract 2-4 distinct factual findings from the source. Return each finding on a separate line, prefixed with "- ". Be concise and factual.',
+          maxTokens: 500,
+          temperature: 0.1,
+        },
+      );
+
+      return result.content
+        .split('\n')
+        .filter((line) => line.startsWith('- '))
+        .map((line) => line.slice(2).trim())
+        .filter((line) => line.length > 10);
+    } catch {
+      return [];
+    }
+  }
+
+  private async synthesizeWithAI(topic: string, findings: Finding[], sources: Source[]): Promise<string> {
+    if (!this.provider) return this.synthesize(findings);
+
+    try {
+      const findingsText = findings
+        .sort((a, b) => b.relevance - a.relevance)
+        .slice(0, 10)
+        .map((f, i) => `${i + 1}. ${f.content}`)
+        .join('\n');
+
+      const sourcesText = sources
+        .map((s) => `- ${s.title} (${s.domain}, credibility: ${s.credibilityScore.toFixed(2)})`)
+        .join('\n');
+
+      const result = await this.provider.complete(
+        [{ role: 'user', content: `Synthesize these research findings about "${topic}" into a concise executive summary.\n\nFindings:\n${findingsText}\n\nSources:\n${sourcesText}` }],
+        {
+          systemPrompt: 'You are a research analyst. Write a concise executive summary (2-4 paragraphs) synthesizing the findings. Mention source credibility where relevant. Be factual and balanced.',
+          maxTokens: 800,
+          temperature: 0.3,
+        },
+      );
+
+      return result.content;
+    } catch {
+      return this.synthesize(findings);
+    }
+  }
+
+  private getMaxSources(depth: ResearchDepth): number {
+    switch (depth) {
+      case 'quick':
+        return 3;
+      case 'standard':
+        return 5;
+      case 'deep':
+        return 10;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export type {
+  ResearchDepth,
+  ResearchQuery,
+  ResearchResult,
+  Finding,
+  Source,
+  CredibilityFactors,
+  KnowledgeEntity,
+  KnowledgeRelation,
+  ResearchProvider,
+  BraveWebResult,
+  BraveSearchResponse,
+} from './types.js';
+export { ResearchEngine, type ResearchEngineConfig } from './engine.js';
+export { BraveSearchClient, type BraveSearchOptions } from './brave-search.js';
+export { CredibilityScorer } from './credibility.js';
+export { CitationTracker } from './citation.js';
+export { KnowledgeGraph } from './knowledge-graph.js';

package/src/knowledge-graph.ts

@@ -0,0 +1,87 @@
+import { nanoid } from 'nanoid';
+import type { KnowledgeEntity, KnowledgeRelation } from './types.js';
+
+export class KnowledgeGraph {
+  private entities = new Map<string, KnowledgeEntity>();
+  private relations: KnowledgeRelation[] = [];
+
+  addEntity(name: string, type: string, properties?: Record<string, string>): KnowledgeEntity {
+    const entity: KnowledgeEntity = {
+      id: nanoid(),
+      name,
+      type,
+      properties: properties ?? {},
+    };
+
+    this.entities.set(entity.id, entity);
+    return entity;
+  }
+
+  getEntity(id: string): KnowledgeEntity | undefined {
+    return this.entities.get(id);
+  }
+
+  findByName(name: string): KnowledgeEntity | undefined {
+    for (const entity of this.entities.values()) {
+      if (entity.name === name) {
+        return entity;
+      }
+    }
+    return undefined;
+  }
+
+  findByType(type: string): KnowledgeEntity[] {
+    const result: KnowledgeEntity[] = [];
+    for (const entity of this.entities.values()) {
+      if (entity.type === type) {
+        result.push(entity);
+      }
+    }
+    return result;
+  }
+
+  addRelation(fromId: string, toId: string, relation: string): void {
+    this.relations.push({ fromId, toId, relation });
+  }
+
+  getRelated(entityId: string): Array<{ entity: KnowledgeEntity; relation: string; direction: 'from' | 'to' }> {
+    const result: Array<{ entity: KnowledgeEntity; relation: string; direction: 'from' | 'to' }> = [];
+
+    for (const rel of this.relations) {
+      if (rel.fromId === entityId) {
+        const entity = this.entities.get(rel.toId);
+        if (entity) {
+          result.push({ entity, relation: rel.relation, direction: 'from' });
+        }
+      }
+      if (rel.toId === entityId) {
+        const entity = this.entities.get(rel.fromId);
+        if (entity) {
+          result.push({ entity, relation: rel.relation, direction: 'to' });
+        }
+      }
+    }
+
+    return result;
+  }
+
+  removeEntity(id: string): boolean {
+    const deleted = this.entities.delete(id);
+    if (deleted) {
+      this.relations = this.relations.filter((r) => r.fromId !== id && r.toId !== id);
+    }
+    return deleted;
+  }
+
+  toJSON(): { entities: KnowledgeEntity[]; relations: KnowledgeRelation[] } {
+    return {
+      entities: Array.from(this.entities.values()),
+      relations: [...this.relations],
+    };
+  }
+
+  clear(): void {
+    this.entities.clear();
+    this.relations = [];
+  }
+}

package/src/types.ts

@@ -0,0 +1,78 @@
+export type ResearchDepth = 'quick' | 'standard' | 'deep';
+
+export interface ResearchQuery {
+  topic: string;
+  depth: ResearchDepth;
+  maxSources?: number;
+  focusAreas?: string[];
+}
+
+export interface ResearchResult {
+  id: string;
+  query: ResearchQuery;
+  findings: Finding[];
+  executiveSummary: string;
+  sources: Source[];
+  confidence: number; // 0-1
+  generatedAt: number;
+  durationMs: number;
+}
+
+export interface Finding {
+  id: string;
+  content: string;
+  sourceId: string;
+  relevance: number; // 0-1
+  category: string;
+}
+
+export interface Source {
+  id: string;
+  url: string;
+  title: string;
+  domain: string;
+  accessedAt: number;
+  credibilityScore: number; // 0-1
+}
+
+export interface CredibilityFactors {
+  domainReputation: number;
+  hasAuthor: boolean;
+  hasDate: boolean;
+  isHttps: boolean;
+  crossReferenced: boolean;
+}
+
+export interface KnowledgeEntity {
+  id: string;
+  name: string;
+  type: string;
+  properties: Record<string, string>;
+}
+
+export interface KnowledgeRelation {
+  fromId: string;
+  toId: string;
+  relation: string;
+}
+
+/** Minimal provider interface — avoids hard dep on @auxiora/providers */
+export interface ResearchProvider {
+  complete(
+    messages: { role: 'user' | 'assistant' | 'system'; content: string }[],
+    options?: { systemPrompt?: string; maxTokens?: number; temperature?: number },
+  ): Promise<{ content: string }>;
+}
+
+export interface BraveWebResult {
+  title: string;
+  url: string;
+  description: string;
+  extra_snippets?: string[];
+}
+
+export interface BraveSearchResponse {
+  web?: {
+    results: BraveWebResult[];
+  };
+}

package/tests/citation.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { CitationTracker } from '../src/citation.js';
+
+describe('CitationTracker', () => {
+  it('addSource creates source with ID', () => {
+    const tracker = new CitationTracker();
+    const source = tracker.addSource('https://example.com/article', 'Test Article');
+    expect(source.id).toBeDefined();
+    expect(source.title).toBe('Test Article');
+    expect(source.url).toBe('https://example.com/article');
+  });
+
+  it('addSource extracts domain', () => {
+    const tracker = new CitationTracker();
+    const source = tracker.addSource('https://www.example.com/article', 'Test');
+    expect(source.domain).toBe('example.com');
+  });
+
+  it('addFinding links to source', () => {
+    const tracker = new CitationTracker();
+    const source = tracker.addSource('https://example.com', 'Source');
+    const finding = tracker.addFinding('Important fact', source.id);
+    expect(finding.sourceId).toBe(source.id);
+    expect(finding.content).toBe('Important fact');
+  });
+
+  it('getFindings filters by sourceId', () => {
+    const tracker = new CitationTracker();
+    const s1 = tracker.addSource('https://a.com', 'A');
+    const s2 = tracker.addSource('https://b.com', 'B');
+    tracker.addFinding('Fact 1', s1.id);
+    tracker.addFinding('Fact 2', s2.id);
+    tracker.addFinding('Fact 3', s1.id);
+
+    const filtered = tracker.getFindings(s1.id);
+    expect(filtered).toHaveLength(2);
+    expect(filtered.every((f) => f.sourceId === s1.id)).toBe(true);
+  });
+
+  it('formatCitations inline format', () => {
+    const tracker = new CitationTracker();
+    tracker.addSource('https://example.com/page', 'Example Page', 0.8);
+    const output = tracker.formatCitations('inline');
+    expect(output).toContain('[1]');
+    expect(output).toContain('Example Page');
+    expect(output).toContain('example.com');
+  });
+
+  it('formatCitations bibliography format', () => {
+    const tracker = new CitationTracker();
+    tracker.addSource('https://example.com/page', 'Example Page', 0.8);
+    const output = tracker.formatCitations('bibliography');
+    expect(output).toContain('Example Page');
+    expect(output).toContain('Credibility: 0.80');
+  });
+
+  it('getSources returns all', () => {
+    const tracker = new CitationTracker();
+    tracker.addSource('https://a.com', 'A');
+    tracker.addSource('https://b.com', 'B');
+    expect(tracker.getSources()).toHaveLength(2);
+  });
+
+  it('clear empties everything', () => {
+    const tracker = new CitationTracker();
+    tracker.addSource('https://a.com', 'A');
+    tracker.addFinding('fact', 'some-id');
+    tracker.clear();
+    expect(tracker.getSources()).toHaveLength(0);
+    expect(tracker.getFindings()).toHaveLength(0);
+  });
+});

package/tests/credibility.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { CredibilityScorer } from '../src/credibility.js';
+
+describe('CredibilityScorer', () => {
+  const scorer = new CredibilityScorer();
+
+  it('wikipedia.org scores 0.95', () => {
+    const score = scorer.score('https://wikipedia.org/wiki/Test');
+    expect(score).toBe(0.95);
+  });
+
+  it('.gov domain scores 0.9', () => {
+    const score = scorer.score('https://data.gov/dataset');
+    expect(score).toBe(0.9);
+  });
+
+  it('.edu domain scores 0.9', () => {
+    const score = scorer.score('https://mit.edu/research');
+    expect(score).toBe(0.9);
+  });
+
+  it('unknown domain scores 0.5', () => {
+    const score = scorer.score('https://randomsite.xyz/page');
+    expect(score).toBe(0.5);
+  });
+
+  it('HTTPS bonus adds 0.05', () => {
+    const base = scorer.score('https://randomsite.xyz/page');
+    const withHttps = scorer.score('https://randomsite.xyz/page', { isHttps: true });
+    expect(withHttps - base).toBeCloseTo(0.05);
+  });
+
+  it('crossReferenced adds 0.1', () => {
+    const base = scorer.score('https://randomsite.xyz/page');
+    const withCross = scorer.score('https://randomsite.xyz/page', { crossReferenced: true });
+    expect(withCross - base).toBeCloseTo(0.1);
+  });
+
+  it('score clamped to max 1.0', () => {
+    const score = scorer.score('https://wikipedia.org/wiki/Test', {
+      isHttps: true,
+      hasAuthor: true,
+      hasDate: true,
+      crossReferenced: true,
+    });
+    expect(score).toBeLessThanOrEqual(1.0);
+  });
+
+  it('extractDomain handles full URLs', () => {
+    expect(scorer.extractDomain('https://www.example.com/path?q=1')).toBe('example.com');
+    expect(scorer.extractDomain('https://sub.domain.org/page')).toBe('sub.domain.org');
+  });
+});