AnthropiArch

# 🏛️ AnthropiArch [](https://python.org) [](LICENSE) [](https://streamlit.io) [](https://anthropic.com) [](https://www.anthropic.com/certification) **Open-source CCA-F exam study engine — and a live demonstration of everything it teaches.** > The autonomous study agent, the streaming tutor, the analytics engine: every line of this codebase implements the CCA-F best practices you need to pass the exam. > *Reading the source is part of the curriculum.* --- ## The Problem Preparing for the **[Claude Certified Architect – Foundations (CCA-F)](https://www.anthropic.com/certification)** exam means mastering agentic loops, MCP integration, prompt caching, structured tool use, and context management — abstract concepts that are hard to absorb from documentation alone. AnthropiArch solves this with a **production-quality study engine that demonstrates every concept it teaches**. When the autonomous agent surveys your knowledge gaps, fetches authoritative sources, synthesises cheat sheets, and generates quiz banks — that's a live CCA-F agentic loop you can read in `src/agent/core.py`. The code is the curriculum. --- ## What It Does in Practice ``` ▶ Run Study Session (click once — takes ~2 minutes) ───────────────────────────────────────────────────────────────── 📖 read_knowledge — surveys 24 docs across 5 CCA-F domains 🔍 web_search — finds agentic loop termination patterns 🌐 web_crawl — fetches docs.anthropic.com/agents/overview 💾 save_knowledge — persists source doc (reliability: 100/100) 🔬 pattern_analysis — synthesises cheat sheet + tricky trap guide 📝 generate_quiz — generates 5 hard MCQs on orchestration 💾 save_knowledge — saves quiz bank to docs/analysis/ ───────────────────────────────────────────────────────────────── +8 docs added · KB Readiness: C → B · AI report saved ``` --- ## Features | Mode | What it does | |---|---| | 🤖 **Tutor** | Streaming chat grounded in your KB. Quick-questions rotate by domain priority. One-click session archiving. Paginated session history. | | 🧠 **Study Agent** | Fully autonomous 5-step loop: assess KB gaps by CCA-F domain weight → web research → synthesise cheat sheets & trap guides → generate quiz banks → KB readiness report. No prompting required. | | 🔍 **Quick Search** | Instant semantic search over your KB — **zero LLM cost**. Type a question, get the most relevant KB passages back in milliseconds. Powered by local ChromaDB + fastembed embeddings. | | 📊 **Analytics** | KB Readiness Score (A–F grade). Domain coverage progress bars. Clickable bigram/trigram phrase cloud. Full Q&A bank with situation context. Dual ingest vs. agent-output timeline. | | 🔬 **Analytics Agent** | Haiku analyses your entire KB and produces a structured readiness report: per-domain ratings, source quality assessment, 4 ranked priority actions, estimated exam score range. Auto-runs after every Study Agent session and after every doc ingest — no manual trigger needed. | | 📋 **Exam Brief** | One A4 page synthesised from your KB — core concepts per domain, must-know facts, exam traps (❌ wrong → ✓ correct), decision rules, last-minute reminders. Current brief always reflects your latest KB; every run also saves a dated archive copy so older versions are preserved and browseable. Downloadable as MD, HTML, or PDF. | | 📥 **Knowledge Ingest** | Web crawl (URL or free-text topic), file upload (PDF / HTML / TXT / MD, including JS-rendered pages), paste text. Duplicate URL detection. Optional CCA-F relevance gate. Semantic search panel in the Unified Viewer. | --- ## Quick Start ```bash git clone https://github.com/yungkim/AnthropiArch.git cd AnthropiArch python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev]" pip install -e ".[rag]" # optional: adds semantic search (Quick Search mode) cp .env.example .env # add ANTHROPIC_API_KEY=sk-ant-… streamlit run src/ui/app.py # opens http://localhost:8501 ``` Go to **Study Agent → ▶ Run Study Session**. In about two minutes your knowledge base will have its first cheat sheets, quiz banks, and a readiness report. > **Semantic search (Quick Search)** — `pip install -e ".[rag]"` enables local ChromaDB + fastembed. The `BAAI/bge-small-en-v1.5` embedding model (~130 MB) is downloaded once and loaded lazily — only when docs are first indexed, not at startup. The vector index builds in the background on first run and persists to `data/vector_db/`. Terminal logs show real-time progress. Pattern analysis falls back to keyword scan if RAG is not installed. --- ## Recommended Daily Flow ``` 1. 🤖 Tutor — study, ask questions, archive insights 2. 🔍 Quick Search — free instant lookup, no LLM cost 3. 📥 Knowledge Ingest — add URLs, files, or notes as you find them 4. 🧠 Study Agent — run once per day (or after 3+ new sources) 5. 📋 Exam Brief — review the updated one-pager, download PDF 6. 📊 Analytics — check weekly for domain gaps and KB grade ``` **Study Agent runs a confirmation dialog** before starting — shows time since last run, new docs added since then, a recommendation, and estimated cost (~$0.20–0.50 per session). Domains updated within the last 7 days are skipped automatically to save tokens. > **PDF export (Exam Brief)** — requires one extra system library on macOS: > ```bash > brew install pango > ``` > Without it the button falls back to a print-ready HTML file (open in browser → Cmd+P → Save as PDF). > **Optional REST API** — `uvicorn src.main:app --reload` starts FastAPI at `http://localhost:8000` with Swagger UI at `/docs`. --- ## Architecture ``` AnthropiArch/ ├── src/ │ ├── ui/ app.py ← Streamlit: 5 modes, sidebar, theme, session state │ ├── agent/ core.py ← StudyAgent: stream_run(), agentic loop, tool dispatch │ ├── knowledge/ │ │ ├── store.py ← KnowledgeStore: YAML frontmatter, scan(), update_analysis() │ │ ├── vector_store.py ← VectorStore: ChromaDB + fastembed, semantic search, graceful fallback │ │ ├── doc.py ← KnowledgeDoc: reliability scoring by domain, slugify │ │ ├── ingest.py ← PDF/HTML/TXT/MD parser + JS-rendered page extractor │ │ ├── fetcher.py ← URL fetch with follow_links, bot-protection fallback │ │ └── validation.py ← CCA-F relevance gate (Haiku, fails open at score < 3) │ ├── skills/ │ │ ├── web_crawl.py ← WebCrawlSkill: fetch + save source doc in one step │ │ ├── research.py ← ResearchSkill: web_search → CCA-F summary │ │ ├── save_knowledge.py ← SaveKnowledgeSkill: Merge & Append pattern │ │ ├── quiz_master.py ← QuizMasterSkill: medium/hard MCQ generation │ │ ├── pattern_analysis.py ← PatternAnalysisSkill: cheat sheets + trap guides │ │ ├── kb_report.py ← Analytics Agent: structured readiness report (Haiku) │ │ ├── exam_brief.py ← Exam Brief: one A4 page, replace-on-refresh (Haiku) │ │ └── session_logger.py ← SessionLoggerSkill: anonymised Q&A archiving │ ├── persistence/ session_store.py← SQLite: session history, message store (async) │ └── mcp/ ← MCP server experiments & integrations ├── docs/ │ ├── research/ ← Source docs (user-ingested + agent-fetched) │ ├── analysis/ ← Cheat sheets, quiz banks, KB readiness reports │ └── interactions/ ← Anonymised tutor session logs (PII-stripped) ├── tests/ │ ├── unit/ ← Fast, isolated — no API calls │ └── integration/ ← Real API calls, opt-in via @pytest.mark.integration └── pyproject.toml ``` --- ## What the Code Demonstrates The CCA-F exam tests these patterns. Every item is implemented in this codebase — reading the source is an active study exercise: | CCA-F Concept | Where to look | |---|---| | Agentic loop with streaming tool dispatch | `src/agent/core.py` → `stream_run()` | | Multi-turn agent with session persistence | `src/agent/core.py` + `src/persistence/session_store.py` | | Skill / tool design with Pydantic I/O | `src/skills/*.py` | | Merge & Append pattern for growing docs | `src/knowledge/store.py` → `update_analysis()` | | Prompt caching (`cache_control`) on system prompts | `src/agent/core.py` → `_AUTONOMOUS_SYSTEM_PROMPT` | | RAG with local embeddings (no API cost) | `src/knowledge/vector_store.py` → `VectorStore` | | Token-cost optimisation (history truncation, recency skip) | `src/agent/core.py` → `_truncate_for_history()`, `_TOOL_HISTORY_LIMITS` | | Haiku as fast, cheap relevance gate | `src/knowledge/validation.py` | | Structured JSON output with schema enforcement | `src/knowledge/validation.py`, `src/skills/kb_report.py` | | Minimal-footprint principle in agent design | `src/skills/save_knowledge.py` | | MCP server resource / tool definitions | `src/mcp/` | | Reliability scoring by source provenance | `src/knowledge/doc.py` | | Fully autonomous loop (no human-in-the-loop) | `src/ui/app.py` → `_run_study_session()` | | Archive + Replace pattern for living documents | `src/skills/exam_brief.py` → `run_exam_brief()` — current slug always latest, dated archive saved each run | | Markdown → HTML → PDF pipeline | `src/ui/app.py` → `_brief_to_pdf()` | --- ## CCA-F Exam Domains | Domain | Weight | Implemented in | |---|---|---| | Agentic Architecture & Orchestration | **27%** | Agent loop, tool dispatch, autonomous session, subagent pattern | | Claude Code Configuration & Workflows | **20%** | `CLAUDE.md`, hook patterns, slash commands, workspace conventions | | Prompt Engineering & Structured Output | **20%** | Validation prompts, quiz generation, KB report, Merge & Append | | Tool Design & MCP Integration | **18%** | Skill classes, MCP server, resource and tool definitions | | Context Management & Reliability | **15%** | Prompt caching, relevance gate, context window strategy | Official exam: [anthropic.com/certification](https://www.anthropic.com/certification) · Community guide: [claudecertifiedarchitects.com](https://www.claudecertifiedarchitects.com) --- ## KB Readiness Score The Analytics page grades your knowledge base across four weighted components: | Component | Weight | How it's calculated | |---|---|---| | Domain Coverage | 40% | Weighted % of CCA-F domains with adequate documentation | | Source Quality | 30% | Average reliability score × document status multiplier | | Synthesis Depth | 20% | Ratio of analysis docs (cheat sheets, quizzes) to source docs | | Study Activity | 10% | Tutor sessions logged (capped at 5 = 100%) | Grade scale: **A** ≥ 85 · **B** ≥ 70 · **C** ≥ 55 · **D** ≥ 40 · **F** < 40 --- ## Reliability Scoring Every document is automatically scored by its source domain at ingest time: | Source | Score | |---|---| | docs.anthropic.com | 100 / 100 | | modelcontextprotocol.io | 95 / 100 | | github.com/anthropics/\* | 92 / 100 | | claudecertifiedarchitects.com | 80 / 100 | | Unknown domain | 35 / 100 | | File upload / paste | 0 / 100 | --- ## Running Tests ```bash pytest # all tests pytest --cov=src --cov-report=term-missing # with coverage pytest -m "not integration" # unit tests only (no API calls) ``` --- ## Prerequisites - Python 3.11 or higher - An [Anthropic API key](https://console.anthropic.com/) --- ## Contributing Contributions are welcome. Open an issue to discuss significant changes before submitting a pull request. All code, comments, and documentation must be in English. 1. Fork the repository 2. Create a feature branch: `git checkout -b feat/your-feature` 3. Run lint and unit tests: `ruff check . && pytest -m "not integration"` 4. Open a pull request with a clear description --- ## License MIT — see [LICENSE](LICENSE) for details. --- > AnthropiArch is an independent open-source project and is not affiliated with or endorsed by Anthropic. > "Claude Certified Architect" and "CCA-F" are trademarks of Anthropic.