agentic-thesis

AgenticThesis

English | 简体中文 | Documentation

Let every new company report challenge your investment thesis.

AgenticThesis is an open-source AI agent that tests your investment thesis—why you own a stock—against new company disclosures. Every proposed change links to exact source evidence and waits for Human Review before becoming authoritative history.

Status: main contains the v1.1 implementation. The PyPI badge shows the latest published package. Start v1.1 with a fresh data directory; prerelease data is not supported.

Why it exists

You write down why a business deserves to remain in your portfolio or watchlist—and what observable facts would prove each reason wrong. AgenticThesis monitors selected SEC and issuer IR sources, preserves what they published, finds claim-relevant evidence, and proposes a reviewable update.

It does not predict prices, value securities, size positions, or issue Buy/Sell/Hold instructions. The investor owns the judgment.

A concrete Apple example

An earlier measured run compared three saved beliefs with a new Apple filing:

Each result retained exact source evidence. None became thesis history until approval. This is an illustrative historical run, not investment advice or a statement about current Apple fundamentals.

Quick start

Install the latest published package:

python -m pip install agentic-thesis

Configure the reasoning and embedding endpoints in ~/.agentic-thesis/.env:

OPENAI_API_KEY=your-key
AGENTIC_THESIS_MODEL=gpt-5-mini

EMBEDDING_API_KEY=your-key
EMBEDDING_BASE_URL=https://api.openai.com/v1
AGENTIC_THESIS_EMBEDDING_MODEL=text-embedding-3-small

# Required only for SEC monitoring
AGENTIC_THESIS_SEC_USER_AGENT="AgenticThesis your-email@example.com"

Start the self-hosted application:

agentic-thesis serve

Open http://127.0.0.1:8000. For development against current main:

git clone https://github.com/suvimatt/agentic-thesis.git
cd agentic-thesis
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/pytest -q -p no:cacheprovider
.venv/bin/agentic-thesis serve

See the 5-minute setup for provider URLs, SEC configuration, and the first evidence cycle.

What v1.1 provides

• Authoritative collection: SEC submissions and explicitly trusted issuer IR pages, including selected filing artifacts, PDFs, presentations, and official text transcripts.
• Immutable provenance: original bytes, canonical source URLs, SHA-256 fingerprints, parser outcomes, fetch failures, and exact page/character locators.
• Thesis-aware Radar: versioned deterministic routing against claims and falsifiers before spending a model call.
• Bounded evidence: structure-aware BM25/vector retrieval, conditional reranking, whole-span Context packing, and exact citation validation.
• Human-owned history: structured four-state thesis deltas that remain non-authoritative until approval.
• Recoverable execution: checkpoint/resume, durable event replay, immutable revisions, and compare-and-swap conflict protection.

Architecture

One application-owned LangGraph coordinates the workflow. Deterministic code owns parsing, retrieval fusion, citation validation, Radar routing, and version commits; model work is limited to embeddings, conditional reranking, and structured thesis comparison.

The same Python distribution exposes:

• AgenticThesisEngine for Python applications;
• agentic-thesis serve for the local browser UI and FastAPI service.

Documentation

• Getting Started
• Core Workflow
• Python Engine
• HTTP API and CLI
• API Reference
• Operations
• Architecture
• Evaluation and Limits

The public API Reference is generated from FastAPI's OpenAPI schema. After starting the local service, http://127.0.0.1:8000/docs remains available as an instance-local API debugger.

Boundary and license

AgenticThesis maintains company-fundamentals theses. Valuation, portfolio actions, and investment decisions remain outside the engine. Secondary sources may create verification leads but cannot independently authorize thesis history.

Licensed under GNU Affero General Public License v3.0. Bugs and focused proposals belong in GitHub Issues.

For the complete evidence, operations, and contribution contracts, use the documentation site.