Adds comprehensive documentation for phased bug fixes:
- SPEC-20: PubMed JSON Parsing Fix (P2)
- SPEC-21: Middleware Architecture Refactor (P2)
- SPEC-22: Progress Bar Removal (P3)
Also adds:
- docs/specs/README.md - Master index with implementation order
- docs/bugs/p2-hardening-issues.md - P2 issue tracker
- docs/bugs/p3-ms-framework-gaps.md - MS framework gap analysis
- docs/architecture/adr-001-middleware-refactor.md - ADR for middleware
- docs/architecture/ms-framework-usage-report.md - What we use from MS
docs: Audit and fix architecture documentation for accuracy
Verified all architecture docs against actual codebase:
- component-inventory.md: Fixed RetrievalAgent (it's a factory function,
not a class) and WebSearchTool (added dead code warning per issue #134)
- overview.md: Added Status column to Agents table, added RetrievalAgent
with "Not wired" status (see #134)
- agent-tool-state-contracts.md: Added dead code warning for RetrievalAgent
explaining it's implemented but not wired into magentic_agents.py
- workflow-diagrams.md: Fixed Implementation Highlights to show actual
factory pattern (not fake MagenticBuilder code), updated footer to
distinguish Active Agents (4) from Implemented but Not Wired (1)
- production-readiness.md: Removed timeline estimates from Next Steps
sections per style guidelines
All verified against:
- src/agents/magentic_agents.py (factory functions)
- src/agents/retrieval_agent.py (create_retrieval_agent, search_web)
- src/agents/tools.py (line numbers verified)
- src/utils/exceptions.py (exception hi…
docs: Add Production Readiness Assessment
Claude
Unverified signature
3a8b0e5
Add honest gap analysis comparing DeepBoner to enterprise best practices
from Microsoft, AWS, Shopify, IBM, and OpenTelemetry guidance.
Key findings:
- Architecture: 8/10 (solid patterns, hierarchical orchestration)
- State Management: 8/10 (ResearchMemory, ContextVars isolation)
- Error Handling: 7/10 (exception hierarchy, fallbacks)
- Testing: 7/10 (unit tests, CI/CD)
- Observability: 3/10 (GAP - no tracing, no OpenTelemetry)
- Safety/Guardrails: 2/10 (GAP - no prompt injection protection)
- Cost Tracking: 1/10 (GAP - no token counting)
Verdict: Well-architected hackathon project with solid foundations,
lacking production observability and safety features.
Sources cited from industry leaders for credibility.
docs: Add Agent-Tool-State Contract Registry
Claude
Unverified signature
f81b58b
Add critical documentation for multi-agent coordination:
- docs/architecture/agent-tool-state-contracts.md
- Complete agent input/output contracts
- Judge decision criteria and thresholds
- Shared state (ResearchMemory) access patterns
- Tool contracts with side effects
- Event flow documentation
- Break conditions (judge approval, max rounds, timeout)
- Dependency matrix ("if I change X, what breaks?")
Also:
- Update docs/README.md to feature new contract registry
- Fix technical debt registry (remove DEBT-001 about intentionally
duplicate CLAUDE.md/AGENTS.md/GEMINI.md files)
- Renumber remaining debt items (now 13 total)
This is the source of truth for agent coordination in DeepBoner.
- Delete several obsolete files, including `design-patterns.md`, `HF_FREE_TIER_ANALYSIS.md`, `overview.md`, `deployment.md`, and `workflow-diagrams.md`, as they no longer align with the current project structure and objectives.
- This cleanup enhances the clarity and relevance of the documentation for developers and stakeholders.
- Delete the `index.md` and `STATUS_LLAMAINDEX_INTEGRATION.md` files as they are no longer relevant to the current project structure and documentation needs.
- Add a new `workflow-diagrams.md` file to provide a comprehensive overview of the updated Magentic architecture and workflow, enhancing clarity for users and developers.
fix(deps): Sync requirements.txt with pyproject.toml (P0 MCP fix)
## Summary
Fixes P1 bug where Free Tier tool calls were never executed because `@use_function_invocation` decorator was skipped.
## Root Cause
`HuggingFaceChatClient` had `__function_invoking_chat_client__ = True` in class body, causing decorator early return.
## Changes
- Remove premature marker from `src/clients/huggingface.py`
- Add `docs/architecture/system_registry.md` as canonical SSOT for wiring
- Document P1 root cause analysis
- Address all CodeRabbit review findings
## Impact
- Free Tier tool execution now works correctly
- P2 7B garbage output superseded (was symptom, not cause)
docs: Organize and archive resolved bug documentation
Critical fixes:
- Fix invalid model names (gpt-5.1 → gpt-4o, claude-sonnet-4-5 → claude-sonnet-4-20250514)
- Add OpenAI key validation in MagenticOrchestrator with clear error message
- Document Magentic mode's OpenAI-only requirement
Nitpicks:
- Add streaming icon to AgentEvent.to_markdown()
- Use exact equality for PubMed placeholder detection
- Update app.py info text for API key requirements
- Add language identifiers to markdown code blocks in docs
feat(architecture): update system design and roadmap for Phases 1-8
- Revised high-level design to include detailed phases and components of the Magentic system.
- Introduced new agents: Magentic Manager, SearchAgent, HypothesisAgent, JudgeAgent, and ReportAgent, each with specific roles in the research process.
- Updated success criteria to reflect completion of Phases 1-5 and outlined specifications for Phases 6-8.
- Enhanced documentation for clarity on system architecture and agent interactions.
docs: add reference repos, orchestration patterns, and 100% ironclad specs
- Section 14: Why we chose Pydantic AI + FastMCP over AutoGen/Claude SDK
- Section 15: Gucci bangers to steal if shipping like animals
- Priority order for stretch goal integrations
- Post-hackathon roadmap for multi-agent expansion
refine formatting in design patterns documentation for better readability
