16.6 — Project: Enterprise Knowledge Assistant

This project builds the federated, multi-domain knowledge assistant designed in Part 11.8 into a real, runnable system. Read Part 11.8 first.

1. Customer Scenario

A large, multi-department enterprise (Part 11.8's scenario) needs one internal AI assistant spanning HR, IT, Finance, and business-unit knowledge — each domain independently owned, with different sensitivity levels and update cadences.

2. Requirements

Recap of Part 11.8: correct query routing across independently-owned domains; per-domain permission enforcement that a bug in one domain never affects others; support for onboarding new departments without redesigning the shared platform.

3. Architecture

Part 11.8's federated architecture: a domain router (Part 3.7) dispatching to independently-owned, independently-permissioned retrieval domains, unified by a consistent generation/citation layer.

4. Technology Selection

• A small, fast classification model (Part 3.11) for domain routing.
• Per-domain pgvector instances or schemas (Part 1.5/3.4/10.5) — each department's content genuinely isolated at the infrastructure level, not just via application-layer tagging.
• A plugin-based ingestion architecture (Part 10.2) letting each department register its own ingestion pipeline against a shared interface contract.

5. Folder Structure

knowledge-assistant/
├── src/
│   ├── routing/
│   │   └── domain_router.py        # Part 3.7's routing pattern, multi-domain aware
│   ├── domains/
│   │   ├── base_domain.py          # shared interface every domain plugin implements
│   │   ├── hr_domain/
│   │   │   ├── ingestion.py        # HR-team-owned, independent pipeline
│   │   │   └── permissions.py      # HR-specific access rules
│   │   ├── it_domain/
│   │   │   └── ...                 # structurally identical shape, independently owned
│   │   └── finance_domain/
│   │       └── ...
│   ├── generation/
│   │   └── unified_response.py     # consistent citation format across domains
│   └── onboarding/
│       └── new_domain_template.py  # scaffolding for onboarding a new department
├── tests/
│   ├── unit/
│   ├── security/
│   │   └── test_cross_domain_isolation.py  # verifies one domain's permission bug
│   │                                          # cannot leak into another domain
│   └── eval/
│       └── routing_accuracy.py     # Part 6.2, per-domain and multi-domain query cases
└── requirements.txt

6. Implementation (key excerpt)

The domain interface contract, directly implementing Part 11.8's federated-ownership principle:

from abc import ABC, abstractmethod

class KnowledgeDomain(ABC):
    """Every department's domain plugin implements this same interface,
    independently, with its own ingestion and permission logic."""

    @abstractmethod
    async def retrieve(self, query_embedding: list[float], requesting_user) -> list[dict]:
        """Retrieves relevant content, enforcing THIS domain's own
        permission rules against the requesting user."""
        ...

    @abstractmethod
    async def ingest_update(self, document) -> None:
        """Handles a content update, independent of every other domain's
        ingestion process."""
        ...


async def answer_query(query: str, requesting_user, domains: dict[str, KnowledgeDomain], router) -> dict:
    """Routes a query to relevant domain(s), composing results with
    consistent citation formatting regardless of source domain."""
    relevant_domain_names = await router.classify(query)
    results = []
    for name in relevant_domain_names:
        domain_results = await domains[name].retrieve(embed(query), requesting_user)
        results.extend([{"domain": name, **r} for r in domain_results])
    return await generate_unified_response(query, results)

7. Testing

test_cross_domain_isolation.py deliberately introduces a permission bug into a mock domain plugin and verifies it has zero effect on other domains' isolation — a direct, concrete test of Part 11.8's core architectural claim (federation contains a bug to one domain).

8. Evaluation

Domain-routing accuracy evaluated separately from per-domain retrieval quality (Part 8.1's layered-property principle) — a query correctly routed to the wrong domain's good retrieval is a different failure than a query correctly routed but poorly retrieved within that domain, and conflating them into one score would obscure which fix is needed.

9. Security

Federated permission enforcement (Part 11.8, section 9) is the central security architecture — each domain's access-control logic is independently reviewed and tested, never sharing a single permission-enforcement codebase across genuinely different sensitivity models (HR versus general IT content).

10. Observability

Per-domain usage and quality metrics (Part 8.4) support federated content-quality accountability — each department's content owners can see how well their specific domain performs, directly informing their own content-maintenance priorities.

11. Deployment

New departments onboard by deploying a new domain plugin against the shared interface (section 6) — no modification to the shared routing/generation layer required, directly realizing Part 11.8's organizational-scalability requirement.

12. Scaling

Domains scale independently — a high-traffic domain (likely IT help-desk questions, given typical volume patterns) can be provisioned with more retrieval capacity without affecting lower-traffic domains' resource allocation.

13. Cost Considerations

Per-domain cost attribution (Part 7.9/7.10) supports a genuinely federated cost model where departments can be charged back for their own domain's usage, aligning content-quality investment incentives with the teams who benefit from it.

14. Failure Scenarios

One domain's retrieval fails or times out for a multi-domain query → graceful degradation, answering from the domains that succeeded with an explicit note (Part 11.8, section 8) rather than failing the entire response. Domain misclassification → broader multi-domain retrieval when router confidence is ambiguous, favoring recall over a single wrong guess.

15. Improvements

A federated evaluation dashboard letting each department's content owners see and act on their own domain's quality metrics directly, without needing central-team involvement — extending the federated-ownership principle from ingestion into ongoing quality management as well.

16. Business Metrics

Reduction in cross-department "who do I even ask" friction (measured via a pre/post survey or ticket-routing-time comparison, Part 15) alongside per-domain usage growth as departments onboard, demonstrating the platform's actual organizational-scalability value in practice, not just in theory.

---

Key takeaways

• The federated domain interface (a shared contract, independently implemented per department) is what makes both organizational scalability and permission-bug containment achievable simultaneously.
• Domain-routing accuracy and per-domain retrieval quality are separate, independently-measurable properties whose conflation would obscure which specific fix a given failure actually needs.
• Graceful multi-domain degradation (answering from what succeeded, rather than failing entirely) matters specifically because this architecture's whole point is composing genuinely independent, independently-reliable domains.

Recommended next chapter

07-ai-api-gateway.md