Project Structure

osint-ai-one/
├── src/
│   ├── config.py                 # Pydantic Settings — all environment variables
│   ├── cache.py                  # Transparent cache layer for tools
│   ├── agent.py                  # Compatibility shim → src/agent/
│   ├── logger.py                 # Logging configuration
│   ├── utils.py                  # Shared utilities
│   │
│   ├── agent/                    # ReAct agent (LangGraph)
│   │   └── __init__.py           # create_osint_agent(), SYSTEM_PROMPT
│   │
│   ├── tools/                    # 19 async OSINT tools
│   │   ├── virustotal.py         # ip_lookup, domain_lookup, hash_lookup
│   │   ├── abuseipdb.py          # check_ip
│   │   ├── alienvault.py         # ip_lookup
│   │   ├── shodan_tool.py        # host_lookup
│   │   ├── ipinfo.py             # lookup
│   │   ├── urlscan.py            # lookup
│   │   ├── whois_tool.py         # lookup (free)
│   │   ├── dns_tool.py           # lookup (free)
│   │   ├── crtsh.py              # lookup (free)
│   │   ├── threat_feeds.py       # fetch_threat_feed (free)
│   │   ├── pivot.py              # pivot_investigate
│   │   ├── history.py            # search_history
│   │   ├── gdelt_tool.py         # entity_search, topic_search, tone_analysis
│   │   ├── rss_monitor.py        # news_search, financial_news, security_news
│   │   ├── financial_data.py     # crypto_prices, economic_indicator, energy_prices
│   │   ├── threat_classifier.py  # classify_threat_type
│   │   ├── acled_tool.py         # conflict_events
│   │   ├── country_risk.py       # get_country_risk_score
│   │   └── ais_tool.py           # vessel_lookup, chokepoint_activity
│   │
│   ├── analysis/                 # Advanced analysis modules
│   │   ├── anomaly_detector.py   # Welford anomaly detection
│   │   ├── market_correlation.py # IOC ↔ market signal correlation
│   │   └── narrative_detector.py # Narrative cluster detection
│   │
│   ├── investigation/            # Investigation management
│   │   ├── manager.py            # Create / archive / reactivate
│   │   ├── evidence.py           # SHA-256 → extract → chunk → embed
│   │   ├── entities.py           # CRUD + dedup + normalization
│   │   ├── claims.py             # Register / verify / dispute
│   │   ├── normalize.py          # Spanish entity normalization
│   │   ├── extract.py            # PDF / TXT / HTML / MD extraction
│   │   └── alerts.py             # Scheduled alerts with change detection
│   │
│   ├── vector/
│   │   └── store.py              # ChromaDB: upsert / search / cross-search
│   │
│   ├── database/
│   │   ├── cache_db.py           # OSINT results cache (SQLite)
│   │   └── investigation_db.py   # Investigation schema — 8 tables, 40+ methods
│   │
│   ├── scoring/
│   │   └── dashboard.py          # Composite scoring (0-100) and dashboard
│   │
│   ├── reporting/
│   │   ├── threat_report.py      # Threat intel reports per session
│   │   └── investigation_report.py  # Investigation reports (9 sections)
│   │
│   ├── services/
│   │   └── osint_service.py      # Unified facade (OSINT + investigation)
│   │
│   ├── mcp_server/
│   │   ├── server.py             # FastMCP: 29 tools, 5 resources, 3 prompts
│   │   └── __main__.py           # Entry point: osint-mcp
│   │
│   ├── a2a_server/
│   │   ├── server.py             # Uvicorn launcher
│   │   ├── agent_card.py         # A2A Agent Card (5 skills)
│   │   ├── executor.py           # Task executor with streaming
│   │   └── __main__.py           # Entry point: osint-a2a
│   │
│   └── cli/
│       └── main.py               # CLI: interactive, single query, batch, investigation
│
├── .claude/
│   ├── skills/                   # 15 Claude Code skills
│   │   ├── _shared/scripts/      # Shared scripts (DB, vector, hash, normalize)
│   │   │   ├── puruto_db.py      # 47 investigation CRUD commands
│   │   │   ├── puruto_vector.py  # ChromaDB operations
│   │   │   ├── puruto_hash.py    # SHA-256
│   │   │   ├── puruto_normalize.py  # ES entity normalization
│   │   │   └── puruto_alerts.py  # Alert execution
│   │   ├── investigation-init/
│   │   ├── evidence-ingest/
│   │   ├── entity-extract/
│   │   ├── osint-investigate/
│   │   ├── osint-recon/
│   │   └── ...                   # 10 more skills
│   └── agents/                   # 4 specialized agents
│
├── tests/
│   ├── tools/                    # 73 OSINT tool tests (mocked with respx)
│   ├── investigation/            # 77 investigation layer tests
│   ├── integration/              # 17 integration tests (MCP, A2A)
│   └── *.py                      # 41 cache, dashboard, session, etc. tests
│
├── data/                         # Runtime data (gitignored)
│   ├── osint_cache.db
│   ├── osint_ai.db
│   ├── chroma/
│   └── .active                   # Active investigation slug
│
├── investigaciones/              # Investigation folders (gitignored)
│   └── <slug>/
│       ├── evidencias/
│       ├── hallazgos/
│       └── informes/
│
├── reports/                      # Generated threat intelligence reports
├── docs/                         # Static HTML documentation (legacy)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml                # Package configuration and entry points
├── CLAUDE.md                     # Claude Code context
├── AGENTS.md                     # IA agent instructions
├── ontology-v1.md                # Complete FTM ontology
└── .env.example                  # Environment variables template

Entry points (pyproject.toml)

[project.scripts]
osint-agent = "src.cli.main:main"
osint-mcp = "src.mcp_server.__main__:main"
osint-a2a = "src.a2a_server.__main__:main"

After pip install -e ., these commands are available in the virtual environment’s PATH.