Vector Search

1
import { HoleFoundationClient } from '@hole-foundation/sdk';
2
3
const client = new HoleFoundationClient({
4
  environment: 'https://api.theholefoundation.org',
5
  token: 'your-jwt-token'
6
});
7
8
const results = await client.vectorSearch.search({
9
  query: 'FOIA exemptions for national security',
10
  limit: 10
11
});
12
13
console.log(`Found ${results.results.length} documents`);
14
results.results.forEach(result => {
15
  console.log(`${result.title} (score: ${result.score})`);
16
  console.log(result.excerpt);
17
});

1
// Good queries
2
await client.vectorSearch.search({
3
  query: "What are the exemptions to public records laws?"
4
});
5
6
await client.vectorSearch.search({
7
  query: "California Public Records Act attorney fees"
8
});
9
10
// Works with legal citations
11
await client.vectorSearch.search({
12
  query: "5 USC 552(b)(6)"
13
});

1
const results = await client.vectorSearch.search({
2
  query: "FOIA deadlines",
3
  limit: 25  // Get up to 25 results
4
});

1
const results = await client.vectorSearch.search({
2
  query: "privacy exemptions",
3
  include_context: true
4
});
5
6
results.results.forEach(result => {
7
  console.log(result.before_context);  // Text before match
8
  console.log(result.excerpt);         // Matched text
9
  console.log(result.after_context);   // Text after match
10
});

1
const results = await client.vectorSearch.search({
2
  query: "open meeting laws",
3
  filters: {
4
    jurisdiction: "california",
5
    document_type: "statute",
6
    year: "2024"
7
  }
8
});

1
interface SearchResponse {
2
  results: SearchResult[];
3
  total: number;
4
  query: string;
5
  took_ms: number;
6
}
7
8
interface SearchResult {
9
  id: string;
10
  title: string;
11
  excerpt: string;
12
  score: number;
13
  document_type: string;
14
  jurisdiction?: string;
15
  citation?: string;
16
  url?: string;
17
  metadata: Record<string, any>;
18
19
  // When include_context: true
20
  before_context?: string;
21
  after_context?: string;
22
}

1
results.results.forEach(result => {
2
  if (result.score > 0.9) {
3
    console.log('⭐ Highly relevant:', result.title);
4
  } else if (result.score > 0.7) {
5
    console.log('✓ Relevant:', result.title);
6
  } else {
7
    console.log('? Review:', result.title);
8
  }
9
});

1
const document = await client.vectorSearch.getDocument('doc-123');
2
3
console.log(document.title);
4
console.log(document.full_text);
5
console.log(document.metadata);

1
const states = ['california', 'texas', 'florida'];
2
const allResults = await Promise.all(
3
  states.map(state =>
4
    client.vectorSearch.search({
5
      query: "public meeting notice requirements",
6
      filters: { jurisdiction: state }
7
    })
8
  )
9
);
10
11
// Combine and sort by score
12
const combined = allResults
13
  .flatMap(r => r.results)
14
  .sort((a, b) => b.score - a.score);

1
// First: Broad search
2
const broad = await client.vectorSearch.search({
3
  query: "privacy exemptions",
4
  limit: 100
5
});
6
7
// Analyze results to find patterns
8
const jurisdictions = new Set(
9
  broad.results.map(r => r.jurisdiction)
10
);
11
12
console.log('Found in jurisdictions:', Array.from(jurisdictions));
13
14
// Second: Focused search
15
const focused = await client.vectorSearch.search({
16
  query: "privacy exemptions",
17
  filters: { jurisdiction: "california" }
18
});

1
const results = await client.vectorSearch.search({
2
  query: "attorney general opinions on FOIA"
3
});
4
5
const citations = results.results
6
  .filter(r => r.citation)
7
  .map(r => ({
8
    citation: r.citation,
9
    title: r.title,
10
    url: r.url
11
  }));
12
13
console.log('Found citations:', citations);

1
import { TheholetruthApiError } from '@hole-foundation/sdk';
2
3
try {
4
  const results = await client.vectorSearch.search({
5
    query: "FOIA exemptions",
6
    limit: 10
7
  });
8
} catch (error) {
9
  if (error instanceof TheholetruthApiError) {
10
    if (error.status === 400) {
11
      console.error('Invalid query:', error.message);
12
    } else if (error.status === 429) {
13
      console.error('Rate limit exceeded');
14
    } else if (error.status === 401) {
15
      console.error('Authentication failed');
16
    }
17
  }
18
  throw error;
19
}

1
// ❌ Too vague
2
await client.vectorSearch.search({ query: "laws" });
3
4
// ✅ Specific
5
await client.vectorSearch.search({
6
  query: "California Public Records Act response deadlines"
7
});

1
// For quick lookup
2
await client.vectorSearch.search({
3
  query: "statute text",
4
  limit: 5
5
});
6
7
// For comprehensive research
8
await client.vectorSearch.search({
9
  query: "privacy exemptions across jurisdictions",
10
  limit: 50
11
});

1
// Instead of this
2
await client.vectorSearch.search({
3
  query: "California open meeting laws"
4
});
5
6
// Do this
7
await client.vectorSearch.search({
8
  query: "open meeting laws",
9
  filters: { jurisdiction: "california" }
10
});

1
// Only request context when needed
2
const quickSearch = await client.vectorSearch.search({
3
  query: "FOIA",
4
  limit: 10
5
  // No include_context
6
});
7
8
// Request context for detailed review
9
const detailedSearch = await client.vectorSearch.search({
10
  query: "FOIA exemption (b)(6)",
11
  limit: 5,
12
  include_context: true
13
});

1
const cache = new Map<string, SearchResponse>();
2
3
async function cachedSearch(query: string) {
4
  if (cache.has(query)) {
5
    return cache.get(query)!;
6
  }
7
8
  const results = await client.vectorSearch.search({ query });
9
  cache.set(query, results);
10
  return results;
11
}

1
async function getAllResults(query: string) {
2
  const pageSize = 50;
3
  let offset = 0;
4
  const allResults = [];
5
6
  while (true) {
7
    const results = await client.vectorSearch.search({
8
      query,
9
      limit: pageSize,
10
      filters: { offset }
11
    });
12
13
    allResults.push(...results.results);
14
15
    if (results.results.length < pageSize) break;
16
    offset += pageSize;
17
  }
18
19
  return allResults;
20
}