edgar-cli 0.1.3 → 0.1.4

package/README.md

@@ -73,6 +73,9 @@ npx edgar-cli --user-agent "Your Name your.email@example.com" research sync --id
 
 # Query by ticker against cached corpus (auto-syncs on cache miss)
 npx edgar-cli --user-agent "Your Name your.email@example.com" research ask "what changed on the board?" --id NVDA --profile core
+
+# Query latest filing(s) in one shot: discover -> fetch/cache -> search
+npx edgar-cli --user-agent "Your Name your.email@example.com" research ask "gross margin drivers" --id AAPL --form 10-Q --latest 1
 ```
 
 ## Research Profiles and Cache
@@ -91,6 +94,11 @@ By default, cached corpora are stored in:
 
 Override per command with `--cache-dir`.
 
+When using `research ask --id`, you can also scope discovery directly:
+
+- `--form <form>` to filter filings by form type (e.g. `10-Q`)
+- `--latest <n>` to limit selection to the latest N filings after filters
+
 ## Output Contract (default)
 
 All JSON-mode commands emit:

package/dist/cli.js

@@ -239,6 +239,8 @@ export function buildProgram(io) {
         .argument('<query>', 'Natural language query')
         .option('--id <id>', 'Ticker or CIK for cached/profile-based research')
         .option('--profile <profile>', 'core|events|financials (used with --id)', 'core')
+        .option('--form <form>', 'SEC form filter for scoped filing selection with --id, e.g. 10-Q')
+        .option('--latest <n>', 'With --id, limit to latest N filings after filters')
         .option('--cache-dir <path>', 'Override cache directory')
         .option('--refresh', 'With --id, force refetch of filings before querying')
         .option('--doc <path>', 'Path to a local document (repeatable)', collectValues, [])
@@ -250,6 +252,18 @@ export function buildProgram(io) {
         const topK = parsePositiveInt(options.topK, '--top-k');
         const chunkLines = parsePositiveInt(options.chunkLines, '--chunk-lines');
         const chunkOverlap = parseNonNegativeInt(options.chunkOverlap, '--chunk-overlap');
+        const latest = options.latest === undefined
+            ? undefined
+            : parsePositiveInt(options.latest, '--latest');
+        if (!options.id && (options.form || latest !== undefined)) {
+            throw new CLIAbortError(emitError({
+                command: 'research ask',
+                err: new CLIError(ErrorCode.VALIDATION_ERROR, '--form and --latest require --id'),
+                runtimeView: 'summary',
+                humanMode: false,
+                io
+            }));
+        }
         const requiresSecIdentity = Boolean(options.id);
         const profile = parseResearchProfile(options.profile);
         await executeCommand('research ask', this, io, async (context) => options.id
@@ -257,6 +271,10 @@ export function buildProgram(io) {
                 id: options.id,
                 query,
                 profile,
+                scope: {
+                    form: options.form,
+                    latest
+                },
                 cacheDir: options.cacheDir,
                 refresh: Boolean(options.refresh),
                 topK,

package/dist/commands/research.d.ts

@@ -1,5 +1,9 @@
 import { CommandContext, CommandResult } from '../core/runtime.js';
 type ResearchProfile = 'core' | 'events' | 'financials';
+interface AskScope {
+    form?: string;
+    latest?: number;
+}
 export declare function parseResearchProfile(value: string): ResearchProfile;
 export declare function runResearchSync(params: {
     id: string;
@@ -19,6 +23,7 @@ export declare function runResearchAskById(params: {
     id: string;
     query: string;
     profile: ResearchProfile;
+    scope?: AskScope;
     cacheDir?: string;
     refresh?: boolean;
     topK: number;

package/dist/commands/research.js

@@ -64,6 +64,10 @@ function parseCachedManifest(value) {
     }
     return manifest;
 }
+function normalizeForm(value) {
+    const normalized = value?.trim().toUpperCase();
+    return normalized && normalized.length > 0 ? normalized : undefined;
+}
 async function readCachedManifest(cacheRoot, cik, profile) {
     const manifestPath = profileManifestPath(cacheRoot, cik, profile);
     let raw;
@@ -105,6 +109,57 @@ async function fileExists(filePath) {
         throw new CLIError(ErrorCode.VALIDATION_ERROR, `Unable to stat ${filePath}: ${err.message}`);
     }
 }
+async function materializeCachedDocs(params) {
+    const docs = [];
+    const skipped = [];
+    let fetchedCount = 0;
+    let reusedCount = 0;
+    for (const row of params.rows) {
+        const docPath = filingDocPath(params.cacheRoot, params.cik, row.accession);
+        const shouldUseCache = !params.refresh && (await fileExists(docPath));
+        if (!shouldUseCache) {
+            try {
+                const filingResult = await runFilingsGet({
+                    id: params.cik,
+                    accession: row.accession,
+                    format: 'markdown'
+                }, params.context);
+                const filingData = filingResult.data;
+                if (typeof filingData.content !== 'string') {
+                    throw new CLIError(ErrorCode.PARSE_ERROR, `Unable to parse markdown content for accession ${row.accession}`);
+                }
+                await mkdir(path.dirname(docPath), { recursive: true });
+                const content = filingData.content.endsWith('\n') ? filingData.content : `${filingData.content}\n`;
+                await writeFile(docPath, content, 'utf8');
+                fetchedCount += 1;
+            }
+            catch (error) {
+                if (error instanceof CLIError && error.code === ErrorCode.NOT_FOUND) {
+                    skipped.push({ accession: row.accession, reason: error.message });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        else {
+            reusedCount += 1;
+        }
+        docs.push({
+            accession: row.accession,
+            form: row.form,
+            filing_date: row.filingDate,
+            report_date: row.reportDate,
+            filing_url: row.filingUrl,
+            path: docPath
+        });
+    }
+    return {
+        docs,
+        fetchedCount,
+        reusedCount,
+        skipped
+    };
+}
 export function parseResearchProfile(value) {
     const normalized = value.trim().toLowerCase();
     if (normalized === 'core' || normalized === 'events' || normalized === 'financials') {
@@ -480,49 +535,13 @@ export async function runResearchSync(params, context) {
         }
     }
     const selectedRows = [...selectedByAccession.values()].sort((a, b) => (b.filingDate ?? '').localeCompare(a.filingDate ?? ''));
-    const docs = [];
-    const skipped = [];
-    let fetchedCount = 0;
-    let reusedCount = 0;
-    for (const row of selectedRows) {
-        const docPath = filingDocPath(cacheRoot, entity.cik, row.accession);
-        const shouldUseCache = !params.refresh && (await fileExists(docPath));
-        if (!shouldUseCache) {
-            try {
-                const filingResult = await runFilingsGet({
-                    id: entity.cik,
-                    accession: row.accession,
-                    format: 'markdown'
-                }, context);
-                const filingData = filingResult.data;
-                if (typeof filingData.content !== 'string') {
-                    throw new CLIError(ErrorCode.PARSE_ERROR, `Unable to parse markdown content for accession ${row.accession}`);
-                }
-                await mkdir(path.dirname(docPath), { recursive: true });
-                const content = filingData.content.endsWith('\n') ? filingData.content : `${filingData.content}\n`;
-                await writeFile(docPath, content, 'utf8');
-                fetchedCount += 1;
-            }
-            catch (error) {
-                if (error instanceof CLIError && error.code === ErrorCode.NOT_FOUND) {
-                    skipped.push({ accession: row.accession, reason: error.message });
-                    continue;
-                }
-                throw error;
-            }
-        }
-        else {
-            reusedCount += 1;
-        }
-        docs.push({
-            accession: row.accession,
-            form: row.form,
-            filing_date: row.filingDate,
-            report_date: row.reportDate,
-            filing_url: row.filingUrl,
-            path: docPath
-        });
-    }
+    const { docs, fetchedCount, reusedCount, skipped } = await materializeCachedDocs({
+        cacheRoot,
+        cik: entity.cik,
+        rows: selectedRows,
+        refresh: params.refresh,
+        context
+    });
     const manifest = {
         version: 1,
         id_input: params.id,
@@ -569,6 +588,62 @@ export async function runResearchAsk(params, context) {
 export async function runResearchAskById(params, context) {
     const cacheRoot = resolveCacheRoot(params.cacheDir);
     const entity = await resolveEntity(params.id, context.secClient, { strictMapMatch: false });
+    const form = normalizeForm(params.scope?.form);
+    if (form || params.scope?.latest !== undefined) {
+        const latest = params.scope?.latest;
+        const listResult = await runFilingsList({
+            id: entity.cik,
+            form,
+            queryLimit: latest
+        }, context);
+        const selectedRows = listResult.data;
+        if (selectedRows.length === 0) {
+            const formLabel = form ?? 'any form';
+            throw new CLIError(ErrorCode.NOT_FOUND, `No filings found for ${params.id} using ${formLabel}.`);
+        }
+        const { docs, fetchedCount, reusedCount, skipped } = await materializeCachedDocs({
+            cacheRoot,
+            cik: entity.cik,
+            rows: selectedRows,
+            refresh: params.refresh,
+            context
+        });
+        if (docs.length === 0) {
+            throw new CLIError(ErrorCode.DOCS_REQUIRED, `No queryable filings were fetched for ${params.id}.`);
+        }
+        const docPaths = docs.map((doc) => doc.path);
+        const searchResult = await runLexicalSearch({
+            query: params.query,
+            docPaths,
+            topK: params.topK,
+            chunkLines: params.chunkLines,
+            chunkOverlap: params.chunkOverlap
+        });
+        const searchData = searchResult.data;
+        return {
+            data: {
+                ...searchData,
+                id: params.id,
+                cik: entity.cik,
+                ticker: entity.ticker,
+                title: entity.title,
+                cache_root: cacheRoot,
+                scope: {
+                    form: form ?? null,
+                    latest: latest ?? null
+                },
+                corpus_docs_count: docs.length,
+                selected_filings: docs,
+                sync: {
+                    fetched_count: fetchedCount,
+                    reused_count: reusedCount,
+                    docs_count: docs.length,
+                    skipped_count: skipped.length,
+                    skipped
+                }
+            }
+        };
+    }
     let manifest = !params.refresh
         ? await readCachedManifest(cacheRoot, entity.cik, params.profile)
         : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edgar-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agent-friendly SEC EDGAR CLI",
   "license": "MIT",
   "type": "module",