AutoInfo

Imported from 1StepMore/AutoInfo (AGENTS.md). Install upstream with npx skills add 1StepMore/AutoInfo. Copyright stays with the author.

AutoInfo — Agent Guide

What Is AutoInfo

AutoInfo is a universal information tracking and knowledge base platform. You configure sources and topics; AutoInfo handles collection, LLM-based structured extraction, summarization, and builds a queryable knowledge base.

Key principle: Domain-agnostic. The 21 demo domains (medical-research, ai-commercial, financial-intelligence, tech-ai-developer, language-learning, online-video, financial-news, online-education, legal-compliance, general-news, gaming, b2b, retail, english-learning, french-learning, hindi-learning, italian-learning, korean-learning, portuguese-learning, russian-learning, spanish-learning) are configurations, not hardcoded features. Users define their own domains.

Agent Operating Model

AutoInfo is designed agent-first:

Director-user (human) ──NL──> Agent ──MCP tools──> AutoInfo MCP Server
                                ↑                           │
                                └──── structured JSON-RPC ───┘

1. You (the agent) connect to AutoInfo's MCP server over stdio (SSE transport is future work)
2. All capabilities are exposed as MCP tools (149 tools across 35 categories)
3. CLI mirrors MCP — --domain X --topic Y flags map 1:1 to tool parameters
4. Human director communicates intent to you in natural language; you translate to tool calls
5. Human can also use CLI directly as a fallback, but the primary interface is through you

Quick Start (5 Seconds)

Connect your AI agent to AutoInfo immediately:

Cursor: .cursor/mcp.json is already committed to the repo -- restart Cursor and the autoinfo MCP server is ready to use.

Claude Desktop: Copy .claude/claude_desktop_config.json from this repo to claude_desktop_config.json in your Claude config directory:

• Linux: ~/.config/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

OpenCode: .opencode/mcp.json is already committed -- OpenCode discovers it automatically via project-level configuration.

Manual (any platform):

python -m autoinfo.mcp.server

Running the CLI

The CLI is the human-facing entry point — same capabilities as MCP, with --domain X --topic Y flags mapping 1:1 to tool parameters. Two equivalent invocations run the same Typer app (src/autoinfo/cli/__init__.py):

Do not confuse the CLI with the MCP server: python -m autoinfo.mcp.server starts the MCP stdio server (agent-facing, protocol over stdio — never use it interactively). The CLI prints human output; the MCP server speaks JSON-RPC.

First commands:

autoinfo --help                              # or: python -m autoinfo.cli --help
autoinfo init --demo medical-research        # scaffold a demo domain
autoinfo collect --domain medical-research   # fetch items (live per-source progress lines)
autoinfo process --domain medical-research   # LLM extraction + quality gates

Project Structure

AutoInfo/
├── AGENTS.md                       # ← You are here
├── README.md                       # Project overview
├── pyproject.toml                  # Python packaging
├── Makefile                        # Build automation
├── .gitignore
├── docs/
│   ├── dev/
│   │   ├── founder-expectations.md # Index doc (simplified; full content in specs/)
│   │   ├── specs/                  # Extracted spec files (2026-07-26 restructuring)
│   │   │   ├── expectations.md     # F01-F57 expectation catalog (57 expectations, 12 phases)
│   │   │   ├── quality-gates.md    # G0-G7, D1-D3 gate catalog & configuration + testing strategy
│   │   │   ├── pipeline.md         # Collection pipeline, KB pipeline, LLM config, extraction, search, performance targets
│   │   │   ├── delivery.md         # Output generation, delivery channels, end user lifecycle
│   │   │   ├── operations.md       # Cost, data privacy, knowledge lifecycle, observability
│   │   │   ├── market-positioning.md # Priority matrix, competitive landscape, pricing, personas
│   │   │   ├── mcp-tools.md        # 149 MCP tools across 35 categories
│   │   │   ├── data-models.md      # Consolidated data model schemas
│   │   │   ├── user-lifecycle-definition.md # Foundational user type definitions (B1/B2/B3)
│   │   │   ├── multi-tenancy-auth.md    # Multi-tenancy and authorization spec
│   │   │   └── ops-runbook.md           # Operations runbook spec
│   │   ├── cross-dimensional-catalog.md # Cross-dimensional catalog — keystone product matrix (A1-A7 × B1/B2/B3, supersedes archived gap docs)
│   │   ├── archive/                  # Archived/historical docs
│   │   ├── director-user-guide.md    # Human-Agent interaction lifecycle
│   └── skills/                     # AutoInfo operator skills (for agent-users of AutoInfo)
│       ├── autoinfo-skill/SKILL.md # Operating AutoInfo via MCP tools
│       └── translator-qa-skill/    # Translation QA workflow
├── .opencode/
│   └── skills/                     # Coding agent skills (for developing AutoInfo)
├── src/
│   └── autoinfo/
│       ├── cli/                     # 31 CLI command groups
│       ├── mcp/                     # MCP server (149 tools)
│       ├── api/                     # REST API (FastAPI, port 8741)
│       ├── kb.py                    # Knowledge base pipeline (4-tier KB pipeline)
│       ├── collectors/              # 30 collector handlers (PubMed, Semantic Scholar, DBLP, OpenAlex, USPTO, NYT, Yahoo Finance, Quandl, RSS, Web, webhook, email, PDF, Reddit, Spotify, YouTube, Bilibili, Apple Podcasts, AP API, Reuters MCP, SSRN, GDELT, HuggingFace/Kaggle, Unpaywall/CORE, HackerNews, AKShare, SEC EDGAR, edX sitemap)
│       ├── llm.py                   # LLM extraction engine
│       ├── output/                   # Output generation package (digest, report, tutorial, presentation, export; formats: Markdown/HTML/JSON/PDF/Audio/Agent/EPUB/MOBI/Audiobook/Video) — __init__.py + export.py (KB export family: export_kb + all format exporters) + entries.py (shared deterministic entry filters) + ebook.py (B23: EPUB/MOBI/audiobook) + video.py (HyperFrames HTML+GSAP→MP4, 36+8 themes) + video_assets/ (themes + templates) + seo.py + free_tier.py (free-tier product limits)
│       ├── data/                     # Domain configs (domains/*/sources.yaml) + 8 output product templates (incl. premium-briefing.md.j2, enterprise-briefing.md.j2) + prompts/ (16 LLM prompt files, loaded via prompts.py)
│       ├── prompts.py                # Prompt registry + loader (issue #426): PROMPTS_DIR / list_prompts / get_prompt / render_prompt / PROMPT_VERSIONS / PROMPT_PLACEHOLDERS. `$name` placeholders — NOT `{name}` (several prompts carry literal JSON braces). Prompt text is byte-pinned in tests/test_prompts.py.
│       ├── cefr.py                  # CEFR classification (EN/ZH/JA)
│       ├── quality.py               # Quality gates G0-G7, D1-D3 delivery gates
│       ├── delivery.py              # Delivery channel abstraction (13 channels)
│       ├── delivery/scheduler.py    # Delivery schedule management (cron integration)
│       ├── delivery/gate_report.py   # Per-product gate reports (01-QA-GATES/ md+json for validation delivery)
│       ├── delivery/frequency_gate.py # Delivery frequency gate (free-tier frequency enforcement at cron add-delivery)
│       ├── alerts.py                # Alert rule CRUD, YAML persistence, check & dispatch
│       └── ...                      # email_sender, keywords, qa, etc.

Architecture Rules

Hard constraints derived from founder-expectations.md. Violating them produces incorrect behavior.

KB Pipeline

Collected Item → 01-Raw → 02-Draft → 03-Wiki
     ↑             ↑          ↑           ↑
  Auto-ingest    Sole       Agent can   Agent
                 entry      process &   promotes
                 point      create      Draft → Wiki

Collection Pipeline

Two phases, separable in time:

Phase 1 — Fetch:     autoinfo collect --domain medical
  → Source handlers fetch items in parallel
  → Raw JSON cached to collections/
  → Dedup (URL → DOI → fuzzy title → semantic)
  → Collection log written

Phase 2 — Process:   autoinfo process --domain medical [--model deepseek-chat]
  → Reads cached raw items
  → LLM extraction (configurable model per task)
  → Quality gates (G1-G5)
  → Creates 01-Raw KB entries

Quality Gates (Production-Grade)

Hard/soft split with retry-first, block-last philosophy. G0 (Schema Integrity) and G4 (Factual Consistency) are hard gates — 3× retry then block. G1-G3 and G5 are soft gates with configurable thresholds and actions (archive/flag/pass). 3 delivery gates (D1-D3) check product completeness, format integrity, and freshness at output time. Validation-delivery packaging additionally persists per-product 01-QA-GATES/gate-report-<product>.{md,json} (D1-D3 + authenticity verdicts, md for humans / json for agents) with a gate-reports-index.json — the packaged reports record delivery-gate outcomes; G0-G5 run at the process layer and are not recomputed in packaging.

Product QC — 3-Layer Model (issue #194)

Product/delivery quality control is layered, not one mechanism. L0 is the default workhorse; L1 is opt-in; humans own value judgment.

Single-production discipline: a product is produced ONCE; the QC pipeline (L0 → opt-in L1 → ESCALATE) is the arbiter. Do NOT regenerate-and-select the "best" version — that reintroduces hidden selection bias. A failed gate sends the product back for ONE constrained regeneration (with the flagged defect fed back), then re-gates.

L1 vendor/model agnosticism (#194/#195): the battery LLM channel is the config-driven config.llm resolution (provider/model/api_key/base_url + fallback chain) — no vendor or model name is hardcoded in the battery or its blind-spot manifest. Structured output is capability-probed (config llm.json_mode); unsupported ⇒ markdown verdict blocks parsed deterministically into the same schema.

Honest hedges are PASS: a product that says "not disclosed in the available sources" is CORRECT behavior (#179/#191) — never flag it.

Agent Constraints (MUST NOT)

Merging a PR (MUST)

Two agents write to this repository. The rules below are not style preferences — each one exists because its absence produced a specific failure.

Expect the rebase to cost a full CI cycle. The release PR auto-merges within minutes of any push to main (Release PR auto-merge triggers on push), so every release invalidates every open PR and forces the rebase above. Budget ~20 min. Do not weaken strict_required_status_checks_policy to avoid it: with two writers a stale-base merge can be textually clean, semantically wrong, and still green in CI — the rebase is what makes CI test the real merge result.

The auto-merge itself is load-bearing, not incidental — it exists because without it the tag went uncuts (1.17.8 shipped a silent half-release, 1.17.9 sat untagged for 33 min). The churn is the price of correct releases. The available mitigation is on our side: fewer, larger PRs, which means fewer merges and therefore fewer rebase cycles.

Tool Discovery Guidance

149 MCP tools across 35 categories — full catalog in README.md (MCP Tools table) and discoverable at runtime via health_check() → tools/list → get_tool_count(). Category → key-tool mapping is maintained in the README, not duplicated here.

Discovery flow: health_check() → tools/list (MCP auto-discovery) → list_domains() → get_domain_schema(domain) → list_available_models() → list_output_templates(domain).

Validation: list_validation_scenarios / run_validation_scenario — 182 scenarios (86 functional + 96 regression in src/autoinfo/mcp/scenarios/regression/); per-scenario timeout, recovery_steps + partial-pass, per-step trace + root-cause report, regression flywheel; env-gated steps report unconfigured (never silently pass); llm_assert runs a real model call. Scenario authoring contract: docs/dev/validation-scenario-contract.md.

Response format: All tools return {success: true, data: ...} on success and {success: false, error: {code, message, actionable}} on failure. actionable is a boolean flag; the remediation guidance itself lives in message. Error codes: src/autoinfo/mcp/errors.py (ErrorCode enum, 26 values, all CamelCase; never-emitted codes retired — T-S-05). LLM-required tools return LLM_NOT_CONFIGURED when no key is configured. REST API uses the same envelope.

Common Patterns

Full step-by-step worked examples live in docs/dev/mcp-usage-examples.md — the authoritative index of every pattern with real call traces. The highest-value patterns, inlined:

Track a new topic: add_topic(domain, name, keywords) → collect_sources(domain, topic, dry_run=true) → collect_sources(...) → process_collection(domain) → list_summaries(domain, topic) → flag_for_knowledge_base(summary_id, tags).

Check system health: diagnose_system() → returns health_score (0-100) + phase (uninitialized / llm_unconfigured / no_sources / ready_to_collect / operational). On degraded status, inspect phase.

Search KB: search_knowledge_base(domain, query, mode="hybrid") (FTS5 + vector), mode="vector" (semantic only), or mode="faceted" with filters={...}; filter_custom_fields={...} facets on custom_fields JSON (e.g. {"product_analysis.action_required": ""}). Omit domain to search across all domains.

Handle MCP errors: All tools return {success, error: {code, message, actionable}}. Read error.code, follow the remediation hint in error.message (actionable: true marks that a hint exists, e.g. DOMAIN_NOT_FOUND says "Use add_domain()"). process_collection with no cached items returns {status: "noop"}, not an error.

LLM Configuration

AutoInfo uses LiteLLM under the hood. Standard OpenAI-format providers work.

Precedence (highest to lowest):

1. MCP tool parameter (e.g. init_project(llm_provider="openai"))
2. Config file .autoinfo/config.yaml → llm.provider, llm.model
3. Environment variable AUTOINFO_LLM_API_KEY
4. Default values (openrouter/deepseek/deepseek-chat)

Custom endpoint (e.g. OpenCode Go, Ollama, Azure): set provider="openai", base_url to your endpoint, api_key via env var, model to your model name.

Fallback example (.autoinfo/config.yaml) — when the fallback sits on the same gateway as the primary, empty provider/api_key inherit the primary provider/key. The entry below carries full fields with empty provider/api_key; because its base_url equals the primary's, an empty api_key inherits the primary key (or its resolved ${ENV} reference). A cross-endpoint fallback (different base_url) does NOT inherit the key and must carry its own explicit ${ENV} reference — keys are never shared across gateways:

llm:
  provider: openai
  model: deepseek-v4-flash
  base_url: https://opencode.ai/zen/go/v1
  fallback:
    - provider: ''
      model: mimo-v2.5
      base_url: https://opencode.ai/zen/go/v1
      api_key: ''

Per-task model routing (2026-08-13): _resolve_task_llm_config (config.py) resolves the model per task and feeds call_with_fallback(task=) → _build_config_with_model (process.py). Extraction/classification tasks use the task-config model (else the base model). Judgment calls (G4 factual, G5 translation, llm_judge) resolve to the release-pinned JUDGMENT_MODEL = "deepseek-v4-flash" constant (config.py, beside LLMConfig) — a release-level decision, never runtime task-config drift.

.omo/ Workspace

The .omo/ directory is the agent-orchestrator workspace used by Sisyphus-style workflows (plans, notepads, evidence, drafts, run-continuation, scripts, boulder.json). It is agent runtime scratch space, not AutoInfo product data.

• Agents may read .omo/ to recover orchestrator context (plans, evidence, notepads).
• Do not treat .omo/ contents as KB entries, sources, or product output. Not part of the collection pipeline or 4-tier KB.
• Do not modify .omo/ from AutoInfo MCP tools. It is owned by the orchestrator layer above AutoInfo.
• .omo/ is gitignored runtime state, not a source-of-truth directory.

Runtime Artifacts vs Source Files

AutoInfo generates runtime state at execution time. Distinguish from source:

Never hand-edit runtime artifacts to fix behavior — fix the source.

Status

Component-by-component status lives in README.md → Status table (the single authoritative component matrix; AGENTS.md and README are cross-checked by scripts/doc_inventory.py --check on the drift-prone facts below).

Key counts the agent must know without opening README:

| Validation scenarios | 182 scenarios (86 functional + 96 regression) |

| Demo domains | 21 demo domains | | LLM-required tools | 16 LLM-required tools | | Test suite | ~6152 tests |

Operational invariants (full rules in Architecture Rules above and docs/dev/acceptance-framework.md):

• KB pipeline: 01-Raw sole entry → 02-Draft → 03-Wiki append-only.
• Quality gates: G0/G4 hard (retry-then-block), G1-G3/G5 soft, D1-D3 delivery.
• Promotion Draft→Wiki is an agent operation (promote_kb_draft, no human gate).
• Everything else is deferred/planned in docs/dev/founder-expectations.md §14.

References

• docs/dev/workflow-charter.md — Development workflow charter (7-stage process + 3 support methods, English index; canonical methodology: docs/dev/七阶段AI开发流程-用CodingAgent交付成品的方法论.md; adoption decision: docs/adr/0006-dev-process-workflow-charter.md)
• docs/dev/mcp-usage-examples.md — Full worked MCP tool workflow examples (moved from Common Patterns)
• docs/dev/required-api-keys.md — Full catalog of API keys and environment variables
• docs/dev/founder-expectations.md — D3 index (simplified after split; see docs/archive/founder-expectations-pre-split.md for full original)
• docs/dev/specs/ — Extracted spec files (11 files: expectations.md, quality-gates.md, pipeline.md, delivery.md, operations.md, market-positioning.md, mcp-tools.md, data-models.md, user-lifecycle-definition.md, multi-tenancy-auth.md, ops-runbook.md)
• docs/archive/kb-pipeline-reference.md — Reference KB pipeline model (archived)
• docs/dev/cross-dimensional-catalog.md — Keystone: A1-A7 Pipeline × B1/B2/B3 Users (126 cells = 7×18; 42 catalogued gaps, 5 gap types). Supersedes archived gap-audit docs.
• docs/dev/enduser-coverage-matrix.md — End-user feature coverage matrix (A–E, 99 items); generated from docs/dev/specs/end-user-matrix.yaml (report_demand) by scripts/coverage_matrix.py --render-enduser-doc. Historical analysis: docs/archive/enduser-coverage-matrix-analysis.md.
• docs/dev/acceptance-framework.md — Acceptance mechanism (keystone, AC1-AC9): user model integrity, data-layer integrity, dual orientation (agent-operated tool / human-first results), coverage commitment, quality, commercial viability, process governance, documentation health (AC8), test & validation suite health (AC9). Supersedes launch-validation-framework.md as the top-level validation charter (D1-D5 now archived at docs/archive/launch-validation-framework.md; evidence machinery retained as tooling).
• docs/dev/validation-scenario-contract.md — Scenario authoring and agent-tester execution how-to (real MCP/CLI/REST calls, real artifacts); authoring + execution merged into one doc 2026-08-08 (former runbook archived at docs/archive/agent-tester-validation.md); graded against acceptance-framework.md (AC1-AC9)
• docs/adr/ — Architecture Decision Records: the why behind architecture rules (01-Raw sole entry, agent promotion without human gate, LLM fallback chain, reasoning-model JSON control, unified envelope, release-please version truth). Template: docs/adr/TEMPLATE.md.
• docs/glossary.md — Project glossary (Ubiquitous Language): the authoritative definitions of KB pipeline, gates, user types, and agent/tooling terms.
• docs/demo-release-standard.md — Demo release Definition of Done (4 checkable criteria: independent review / 2 consecutive one-shots in stable band / residual register current / repo+protocol clean). Audience: the human decision authority + coding agents executing QC. NOT end-user material.
• docs/known-limitations/demo-quality-residuals.md — Demo quality residual risk register: known failure classes → detection layer → severity → status; new classes are registered here BEFORE being fixed. Audience: coding agents + future maintainers. NOT end-user material.
• docs/dev/agent-era-doc-architecture.md — Portable playbook: agent-era documentation architecture (generic, applies to any project).
• docs/dev/agent-era-doc-architecture-autoinfo.md — AutoInfo-specific map of the doc architecture (what to keep/update, the maintenance loop, cleaned-items record).

Community

• CONTRIBUTING.md — Human-facing contribution guide (Conventional Commits, AI contribution policy, mandatory 回归场景).
• GOVERNANCE.md — Roles, label taxonomy, review policy, branch protection + DCO, release management (release-please).
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• SECURITY.md — Vulnerability reporting (48-72h acknowledgment) + security-relevant areas (BYOK keys, webhooks, REST port 8741).
• .github/ — PR/issue templates (mandatory 回归场景), CODEOWNERS, workflow gates (pr-title-check, baseline-aware coverage, release-please), dependabot, .pre-commit-config.yaml (gitleaks + credential-url guard).