From ddad72279a9d39b21f66a0d0723da41dbfc76425 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Thu, 21 May 2026 14:56:35 +0200
Subject: [PATCH 01/16] docs: add agentcore/enthusiast architecture split spec

---
 specs/ai-agent-core-extraction.md | 507 ++++++++++++++++++++++++++++++
 1 file changed, 507 insertions(+)
 create mode 100644 specs/ai-agent-core-extraction.md

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
new file mode 100644
index 00000000..25b0fc16
--- /dev/null
+++ b/specs/ai-agent-core-extraction.md
@@ -0,0 +1,507 @@
+# Design: agentcore / enthusiast Architecture Split
+
+**Author:** Dawid Mularczyk
+
+---
+
+## Overview
+
+Extract the domain-agnostic AI agent framework from Enthusiast into a standalone platform called **agentcore** (placeholder name — final name TBD). Enthusiast becomes an e-commerce vertical plugin installed on top of agentcore. Other verticals (healthcare, logistics, etc.) can be built the same way.
+
+---
+
+## Problem Statement
+
+Enthusiast's AI agent infrastructure (conversation management, agent framework, LLM providers, memory, WebSocket streaming) is tightly coupled with e-commerce domain concepts (products, documents, DataSets). This prevents the agent core from being reused in other domains and makes the codebase harder to reason about as each layer grows.
+
+---
+
+## Goals
+
+- Decouple AI agent infrastructure from e-commerce domain logic
+- Make agentcore a general-purpose platform other verticals can build on
+- Enthusiast becomes a true plugin — installable on agentcore with no modifications to core
+- agentcore is useful standalone (without enthusiast) out of the box
+
+---
+
+## Non-Goals
+
+- Abstracting over LangChain — it stays as a hard dependency in agentcore
+- Building a plugin marketplace or auto-discovery mechanism — Django settings is sufficient
+- Merging into a monorepo — two separate repos from day one
+
+---
+
+## Architecture
+
+### Repository Structure
+
+**Two separate repositories:**
+
+1. `github.com/upsidelab/agentcore` — the platform
+2. `github.com/upsidelab/enthusiast` — the e-commerce vertical plugin
+
+---
+
+### agentcore repo (the platform)
+
+agentcore is a **runnable Django project**. Users clone/install it, configure settings, and install vertical plugins on top.
+
+```
+agentcore/
+  server/
+    manage.py
+    settings.py             # base settings, INSTALLED_APPS = ['agentcore']
+    settings_override.py    # env-based user config (add verticale here)
+    pecl/
+      urls.py
+      wsgi.py / asgi.py
+      celery.py
+    docker-compose.yml
+    agentcore/              # Django app
+      models/               # Conversation, Message, Agent, AgenticExecution
+      core/
+        builder.py          # AgentBuilder (Django implementation)
+        injector.py         # Injector (Django implementation)
+        memory/             # PersistentChatHistory, memory strategies
+        registries/         # LanguageModelRegistry, EmbeddingRegistry, etc.
+        repositories.py     # Django ORM implementations of base repos
+        retrievers/         # DocumentRetriever, base vector search
+        callbacks/          # WebSocket callback handler
+      consumers/            # Django Channels WebSocket consumer
+      conversation/         # ConversationManager
+      agentic_execution/    # AgenticExecution Django models, views, tasks
+      views.py
+      urls.py
+      serializers/
+      tasks.py
+      admin.py
+  frontend/                 # React 18 + TypeScript chat UI
+  plugins/
+    agentcore-common/       # Pure Python interfaces (PyPI: agentcore-common)
+      agents/               # BaseAgent, BaseAgentBuilder, ConfigType
+      tools/                # BaseTool, BaseFunctionTool, BaseLLMTool,
+                            # BaseFileTool, BaseAgentTool
+      agentic_execution/    # BaseAgenticExecutionDefinition, ExecutionResult,
+                            # ToolScratchpad, BaseExecutionValidator
+      registries/           # LanguageModelProvider, BaseLanguageModelRegistry,
+                            # EmbeddingProvider, BaseEmbeddingProviderRegistry
+      repositories/         # BaseRepository[T], BaseUserRepository,
+                            # BaseConversationRepository, BaseMessageRepository,
+                            # BaseDataSetRepository, BaseAgentRepository
+      injectors/            # BaseInjector
+      retrievers/           # BaseVectorStoreRetriever[T]
+      structures/           # TextContent, LLMFile, BaseContent
+      callbacks/            # ConversationCallbackHandler
+      config/               # AgentConfig, LLMConfig, tool configs
+      errors/               # BaseAgentFriendlyError
+    agentcore-model-openai/
+    agentcore-model-anthropic/
+    agentcore-model-google/
+    agentcore-model-mistral/
+    agentcore-model-ollama/
+    agentcore-model-azureopenai/
+```
+
+**What agentcore provides out of the box:**
+- Conversation management (create, respond, history)
+- Agent registration and execution
+- WebSocket streaming of agent responses
+- Agentic execution engine (autonomous multi-step tasks with retries/validators)
+- LLM provider plugins (OpenAI, Anthropic, Google, Mistral, Ollama, Azure)
+- Memory strategies (persistent, limited, summary)
+- React chat UI
+- REST API + Django admin
+
+---
+
+### enthusiast repo (e-commerce vertical)
+
+enthusiast is a **Django app package** installed into agentcore. It has no `manage.py` — agentcore is the project that runs it.
+
+```
+enthusiast/
+  plugins/
+    enthusiast-common/      # Thin e-commerce interfaces (PyPI: enthusiast-common)
+                            # NO dependency on agentcore-common
+      structures/           # ProductDetails, DocumentDetails, Address,
+                            # DocumentChunkDetails, ProductUpdateDetails
+      interfaces/           # ProductSourcePlugin, DocumentSourcePlugin,
+                            # ECommerceIntegrationPlugin
+      connectors/           # ECommercePlatformConnector (ABC)
+      retrievers/           # BaseProductRetriever
+    enthusiast/             # Django app (PyPI: enthusiast)
+      models/               # DataSet, Product, ProductChunk,
+                            # Document, DocumentChunk
+      catalog/              # Catalog management views/API
+      sync/                 # Source synchronization engine
+      injector.py           # EnthusiastInjector (extends BaseInjector)
+      builder.py            # EnthusiastAgentBuilder (extends BaseAgentBuilder)
+      repositories.py       # Django ORM implementations for e-commerce models
+      retrievers/           # ProductRetriever, DocumentRetriever (pgvector)
+      admin.py
+      urls.py
+      serializers/
+    enthusiast-agent-product-search/
+    enthusiast-agent-catalog-enrichment/
+    enthusiast-agent-order-intake/
+    enthusiast-agent-user-manual-search/
+    enthusiast-agent-invoice-scanning/
+    enthusiast-source-medusa/
+    enthusiast-source-shopify/
+    enthusiast-source-woocommerce/
+    enthusiast-source-shopware/
+    enthusiast-source-solidus/
+    enthusiast-source-wordpress/
+    enthusiast-source-sanitycms/
+    enthusiast-source-sample/
+```
+
+---
+
+### Package Dependency Graph
+
+```
+agentcore-common          (langchain, pydantic — no project deps)
+      ↑                              ↑
+agentcore (Django app)         agentcore-model-*
+
+
+enthusiast-common         (no dependency on agentcore-common — fully independent)
+      ↑                              ↑               ↑
+enthusiast (Django app)    enthusiast-agent-*    enthusiast-source-*
+      ↑                         ↑
+   agentcore              agentcore-common
+                          enthusiast-common
+```
+
+Key rule: **`enthusiast-common` has zero dependency on `agentcore-common`**. E-commerce interfaces are fully independent of the AI agent framework.
+
+---
+
+### Plugin Registration (Django settings)
+
+agentcore `settings.py` defines base config. Users extend via `settings_override.py`:
+
+```python
+# agentcore/server/settings.py
+INSTALLED_APPS = [
+    'agentcore',
+    # vertical plugins added via settings_override:
+]
+
+AGENTCORE_LANGUAGE_MODEL_PLUGINS = [
+    'agentcore_model_openai.OpenAILanguageModelProvider',
+    'agentcore_model_anthropic.AnthropicLanguageModelProvider',
+    'agentcore_model_google.GoogleLanguageModelProvider',
+    'agentcore_model_mistral.MistralLanguageModelProvider',
+    'agentcore_model_ollama.OllamaLanguageModelProvider',
+    'agentcore_model_azureopenai.AzureOpenAILanguageModelProvider',
+]
+AGENTCORE_AGENT_PLUGINS = []
+AGENTCORE_EMBEDDING_PLUGINS = []
+
+# agentcore/server/settings_override.py (user-configured, env-based)
+INSTALLED_APPS += ['enthusiast']
+
+AGENTCORE_AGENT_PLUGINS = [
+    'enthusiast_agent_product_search.ProductSearchAgent',
+    'enthusiast_agent_catalog_enrichment.CatalogEnrichmentAgent',
+    'enthusiast_agent_order_intake.OrderIntakeAgent',
+    'enthusiast_agent_user_manual_search.UserManualSearchAgent',
+    'enthusiast_agent_invoice_scanning.InvoiceScanningAgent',
+]
+AGENTCORE_SOURCE_PLUGINS = [
+    'enthusiast_source_medusa.MedusaIntegration',
+    # ...
+]
+```
+
+Each vertical plugin follows the same pattern — never modifies agentcore settings directly.
+
+---
+
+### How enthusiast extends agentcore
+
+enthusiast provides Django-specific implementations of agentcore's abstract bases:
+
+```python
+# enthusiast/injector.py
+from agentcore_common.injectors import BaseInjector
+from enthusiast_common.retrievers import BaseProductRetriever
+
+class EnthusiastInjector(BaseInjector):
+    def __init__(self, ..., product_retriever: BaseProductRetriever):
+        super().__init__(...)
+        self._product_retriever = product_retriever
+
+    @property
+    def product_retriever(self) -> BaseProductRetriever:
+        return self._product_retriever
+
+# enthusiast/builder.py
+from agentcore.core.builder import AgentBuilder  # Django agentcore builder
+
+class EnthusiastAgentBuilder(AgentBuilder):
+    def _build_injector(self) -> EnthusiastInjector:
+        # builds product retriever, passes to EnthusiastInjector
+        ...
+```
+
+---
+
+## What Moves Where
+
+### From enthusiast → agentcore
+| Current location | New location |
+|---|---|
+| `plugins/enthusiast-common/` (generic parts) | `plugins/agentcore-common/` |
+| `plugins/enthusiast-model-*` | `plugins/agentcore-model-*` |
+| `server/agent/core/` | `server/agentcore/core/` |
+| `server/agent/` (Conversation, Message, Agent models) | `server/agentcore/models/` |
+| `server/agent/conversation/` | `server/agentcore/conversation/` |
+| `server/agent/agentic_execution/` (Django layer) | `server/agentcore/agentic_execution/` |
+| `server/agent/consumers/` | `server/agentcore/consumers/` |
+| `server/account/` | `server/account/` (stays, generic auth) |
+| `frontend/` | `agentcore/frontend/` |
+| `server/pecl/` (project config) | `agentcore/server/pecl/` |
+
+### Stays in enthusiast
+| Current location | Notes |
+|---|---|
+| `plugins/enthusiast-common/` (e-commerce parts) | Becomes thin `enthusiast-common` |
+| `plugins/enthusiast-agent-*` | All e-commerce agents |
+| `plugins/enthusiast-source-*` | All source plugins |
+| `server/catalog/` | Moves into `plugins/enthusiast/catalog/` |
+| `server/sync/` | Moves into `plugins/enthusiast/sync/` |
+
+### Renamed
+| Old name | New name |
+|---|---|
+| `enthusiast-model-openai` | `agentcore-model-openai` |
+| `enthusiast-model-anthropic` | `agentcore-model-anthropic` |
+| `enthusiast-model-google` | `agentcore-model-google` |
+| `enthusiast-model-mistral` | `agentcore-model-mistral` |
+| `enthusiast-model-ollama` | `agentcore-model-ollama` |
+| `enthusiast-model-azureopenai` | `agentcore-model-azureopenai` |
+| `enthusiast_common.*` (generic imports) | `agentcore_common.*` |
+
+---
+
+## Migration Strategy
+
+### Phase 1 — Build agentcore (green field, new repo)
+
+1. Create `github.com/upsidelab/agentcore`
+2. Copy and refactor:
+   - `enthusiast-common` → `agentcore-common` (strip all e-commerce types)
+   - `enthusiast-model-*` → `agentcore-model-*` (rename packages + imports)
+   - `server/agent/` → `agentcore/server/agentcore/` (Django app)
+   - `server/account/` → agentcore (generic auth)
+   - `server/pecl/` → agentcore project config
+   - `frontend/` → agentcore frontend
+3. agentcore runs standalone, all existing tests pass
+4. Publish `agentcore-common` and `agentcore` to PyPI (alpha)
+
+### Phase 2 — Migrate enthusiast (branch on enthusiast repo)
+
+1. Create branch `feature/agentcore-migration` on enthusiast
+2. Remove from enthusiast:
+   - `enthusiast-common` generic parts
+   - All `enthusiast-model-*` packages
+   - `server/agent/core/` (builder, injector, registries, memory)
+   - `server/agent/` (Conversation, Message, Agent Django models)
+   - `server/account/`
+   - `frontend/`
+3. Thin `enthusiast-common`: keep only e-commerce interfaces
+4. Update all imports: `enthusiast_common.*` → `agentcore_common.*`
+5. Add `agentcore` as dependency in `pyproject.toml`
+6. Implement `EnthusiastInjector`, `EnthusiastAgentBuilder` extending agentcore bases
+7. End-to-end tests: agentcore + enthusiast plugin working together
+8. Merge branch
+
+### Phase 3 — Release
+
+1. Publish `enthusiast-common` and `enthusiast` to PyPI
+2. `docker-compose.yml` in agentcore repo with enthusiast pre-installed as reference setup
+3. Update documentation
+
+---
+
+## Workspace Model (resolved)
+
+The `Conversation → DataSet` circular dependency is resolved by introducing a generic `Workspace` model in agentcore. All verticale extend it via `OneToOne`.
+
+```python
+# agentcore
+class Workspace(models.Model):
+    name = CharField()
+    owner = FK(User)
+    created_at = DateTimeField()
+    llm_provider = CharField()     # platform-level LLM config
+    llm_model = CharField()
+
+class Agent(models.Model):
+    workspace = FK(Workspace)
+
+class Conversation(models.Model):
+    workspace = FK(Workspace)
+
+# enthusiast
+class DataSet(models.Model):
+    workspace = OneToOneField(Workspace, related_name='dataset')
+    language = CharField()
+    embedding_provider = CharField()   # tied to pgvector store
+    embedding_model = CharField()
+    # source integration configs
+```
+
+**Config override cascade:**
+```
+[1] settings.py defaults      (DEFAULT_LLM_PROVIDER, DEFAULT_LLM_MODEL)
+[2] Workspace                 (llm_provider, llm_model) — agentcore
+[3] DataSet                   (embedding_provider, embedding_model) — enthusiast
+[4] Agent config              (system_prompt, tools, memory) — agentcore
+```
+
+`AgentBuilder` (agentcore) handles levels 1–2. `EnthusiastAgentBuilder` handles level 3.
+
+## Frontend Architecture Discussion
+
+The frontend work is split into two iterations with a clear decision point between them.
+
+---
+
+### Iteration 1 — Django staticfiles bundle (decided, implement now)
+
+The plugin extension mechanism is intentionally simple for the first iteration. No NPM infrastructure, no package publishing, no shared types. The goal is to get the plugin system working end-to-end.
+
+**How it works:**
+
+```
+enthusiast/static/enthusiast/frontend/bundle.js  ← pre-built, ships with pip package
+AppConfig.ready() → register_frontend_plugin(id, bundle_url)
+GET /api/config/ → { plugins: [{ bundle: "/static/enthusiast/frontend/bundle.js" }] }
+shell → <script src="bundle.js"> → window.agentcore.registerPlugin({nav, routes})
+```
+
+**Plugin registration (global contract via `window.agentcore`):**
+
+```typescript
+// enthusiast bundle.js — called on load, no imports from agentcore
+window.agentcore.registerPlugin({
+  id: 'enthusiast',
+  nav: [
+    { label: 'Catalog',      path: '/catalog' },
+    { label: 'Integrations', path: '/integrations' },
+  ],
+  routes: [
+    { path: '/catalog/*',      componentId: 'CatalogApp' },
+    { path: '/integrations/*', componentId: 'IntegrationsApp' },
+  ],
+  toolRenderers: {
+    'product_search': 'ProductSearchRenderer',
+    'order_intake':   'OrderIntakeRenderer',
+  },
+})
+```
+
+**What ships in Iteration 1:**
+- agentcore frontend: existing React shell with a `pluginRegistry` module, `window.agentcore.registerPlugin()` global, dynamic `<script>` injection from `/api/config/`
+- enthusiast frontend: existing React app compiled to `bundle.js`, copied to `enthusiast/static/`, committed to git, shipped with pip package
+
+**Known limitations (acceptable for now):**
+- No TypeScript types shared between shell and plugins — plugin developers need to know the `registerPlugin()` contract by reading docs
+- Plugin components can't import from agentcore's component library — no shared UI primitives
+- DX friction: to develop the enthusiast frontend you need a running agentcore instance
+
+These limitations are intentional trade-offs to unblock the backend architecture work (Plans 1–3) and ship a working plugin system quickly.
+
+---
+
+### Iteration 2 — Frontend architecture (deferred, consult with Filip)
+
+Once Plans 1–3 are shipped and the backend plugin system is stable, the frontend injection approach from Iteration 1 will have served its purpose but will show its limits — no shared types, no shared component library, DX friction when developing plugin frontend without a running agentcore.
+
+**Before starting Iteration 2, schedule a meeting with Filip (frontend developer).** The whole frontend strategy should be his call — he will know what's practical. Topics to bring:
+
+- **Overall strategy** — is the staticfiles bundle + injection approach worth keeping long-term, or should we replace it with something fundamentally different?
+- **Chat UI library** — current chat UI is custom-built. Is there a library worth adopting (e.g. assistant-ui, or something else Filip would recommend)?
+- **Shared frontend packages** — does it make sense to extract shared types/components into packages (`@agentcore/ui`, `@enthusiast/ui`)? Or is it over-engineering for the team size?
+- **Separate frontend repo** — should the frontend live in its own repo, separate from the Python repos? Filip may prefer that as a frontend developer.
+- **Build pipeline** — how does the enthusiast bundle get built and shipped with the pip package in a maintainable way?
+
+No decisions are made here — this is a conversation to have with Filip, not a spec to lock in upfront.
+
+---
+
+## Open Questions
+
+- **Final name for agentcore** — placeholder only, needs branding discussion
+- **PyPI namespace** — check `agentcore` availability before publishing
+- **Versioning strategy** — agentcore and enthusiast version independently
+- **Workspace → DataSet extension pattern** — current decision is `DataSet OneToOne Workspace`, but this needs more thought. Is OneToOne the right Django pattern here? Could it create awkward joins or leaky abstractions when multiple verticale are installed? Are there better patterns (e.g. multi-table inheritance, a pure FK from DataSet with no back-reference on Workspace)? To be revisited before implementation of the data model.
+- **Frontend architecture (Iteration 2)** — Iteration 1 decided: Django staticfiles bundle + `window.agentcore.registerPlugin()`. Iteration 2 fully open: needs a meeting with Filip (frontend developer) to decide on chat UI library, shared package strategy, separate frontend repo, and build pipeline. See Frontend Architecture Discussion for details.
+
+---
+
+## Plugin Developer Documentation (needed before public release)
+
+Before agentcore can be used by third parties, we need a "Build your own vertical" guide. enthusiast is the reference implementation, but someone building a healthcare or logistics plugin shouldn't need to read its source code to understand what to implement.
+
+The guide should cover:
+
+### What agentcore exposes (the extension points)
+
+**Must implement** — these are abstract, agentcore won't run without a concrete implementation:
+
+| Class | Where | What to implement |
+|---|---|---|
+| `BaseInjector` | `agentcore-common` | `document_retriever`, `chat_history`, `tool_scratchpad` properties |
+| `BaseAgentBuilder` | `agentcore-common` | `_build_injector()`, `_build_llm_registry()`, `_build_tools()`, `_build_agent()`, and related factory methods |
+| `BaseConversationRepository` | `agentcore-common` | `get_workspace_id()`, `get_agent_id()`, `list_files()`, `get_file_objects()` |
+| `BaseWorkspaceRepository` | `agentcore-common` | standard CRUD methods from `BaseRepository` |
+
+**Can implement** — optional extension points that unlock additional capabilities:
+
+| Class | What it adds |
+|---|---|
+| `BaseAgent` subclass | Custom agent with domain-specific `get_answer()` logic |
+| `BaseFunctionTool` | A simple tool the agent can call (e.g. `lookup_patient_record`) |
+| `BaseLLMTool` | A tool that itself calls an LLM (e.g. summariser, classifier) |
+| `BaseAgentTool` | A tool that spawns a sub-agent |
+| `BaseAgenticExecutionDefinition` | An autonomous multi-step task with retry/validation loop |
+| `LanguageModelProvider` | A new LLM provider (if not covered by agentcore-model-*) |
+
+**Django integration** — what the plugin's Django app must/can provide:
+
+| Item | Required? | Purpose |
+|---|---|---|
+| `AppConfig.ready()` calls `register_frontend_plugin()` | optional | registers frontend bundle with agentcore shell |
+| `INSTALLED_APPS` entry | required | Django discovers models, migrations, admin |
+| `settings_override.py` entries (`AGENTCORE_AGENT_PLUGINS`, etc.) | required | registers agents, sources with agentcore registries |
+| `OneToOneField(Workspace, related_name='+')` on domain model | recommended | extends Workspace with vertical-specific config |
+
+### What the guide should walk through step by step
+
+1. Create a new Python package (pip-installable)
+2. Define a domain model extending `Workspace` via `OneToOneField`
+3. Implement `BaseInjector` with domain-specific retrievers
+4. Implement `BaseAgentBuilder` wiring up the injector and tools
+5. Write a simple `BaseFunctionTool`
+6. Register everything in `settings_override.py`
+7. Write a minimal frontend bundle that calls `window.agentcore.registerPlugin()`
+8. Ship it: `pip install yourplugin` + `INSTALLED_APPS += ['yourplugin']`
+
+enthusiast itself serves as the living reference for all of the above.
+
+---
+
+## Success Criteria
+
+- agentcore runs standalone with a working chat UI and conversation API, zero e-commerce imports
+- enthusiast installs into agentcore via `INSTALLED_APPS` and `pip install enthusiast`
+- A hypothetical healthcare plugin could follow the same pattern as enthusiast
+- All existing enthusiast tests pass after migration
+- No circular dependencies between packages

From d41511e35e302d493db8da757fd7e3e2544d956e Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Fri, 22 May 2026 10:59:24 +0200
Subject: [PATCH 02/16] docs: update spec with DataSet/Repository/Integration
 model and simplified frontend

---
 specs/ai-agent-core-extraction.md | 234 +++++++++++++++++-------------
 1 file changed, 130 insertions(+), 104 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 25b0fc16..1eb2dba6 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -60,7 +60,8 @@ agentcore/
       celery.py
     docker-compose.yml
     agentcore/              # Django app
-      models/               # Conversation, Message, Agent, AgenticExecution
+      models/               # DataSet, Repository, Integration,
+                            # Conversation, Message, Agent, AgenticExecution
       core/
         builder.py          # AgentBuilder (Django implementation)
         injector.py         # Injector (Django implementation)
@@ -132,14 +133,14 @@ enthusiast/
       connectors/           # ECommercePlatformConnector (ABC)
       retrievers/           # BaseProductRetriever
     enthusiast/             # Django app (PyPI: enthusiast)
-      models/               # DataSet, Product, ProductChunk,
-                            # Document, DocumentChunk
-      catalog/              # Catalog management views/API
-      sync/                 # Source synchronization engine
-      injector.py           # EnthusiastInjector (extends BaseInjector)
+      models/               # Product, ProductChunk, Document, DocumentChunk
+                            # (no DataSet — that lives in agentcore now)
+      sync/                 # Source synchronization engine (syncs to agentcore Repository)
+      injector.py           # EnthusiastInjector — implements get_retriever(type)
       builder.py            # EnthusiastAgentBuilder (extends BaseAgentBuilder)
       repositories.py       # Django ORM implementations for e-commerce models
       retrievers/           # ProductRetriever, DocumentRetriever (pgvector)
+      handlers.py           # ProductRepositoryHandler, MedusaIntegrationHandler, etc.
       admin.py
       urls.py
       serializers/
@@ -224,28 +225,35 @@ Each vertical plugin follows the same pattern — never modifies agentcore setti
 
 ### How enthusiast extends agentcore
 
-enthusiast provides Django-specific implementations of agentcore's abstract bases:
+enthusiast provides Django-specific implementations of agentcore's abstract bases. It registers its repository types (`products`, `documents`) and integration types (`medusa`, `shopify`, etc.) with agentcore at startup:
 
 ```python
+# enthusiast/apps.py
+class EnthusiastAppConfig(AppConfig):
+    def ready(self):
+        from agentcore.registry import register_repository_type, register_integration_type
+        register_repository_type('products', ProductRepositoryHandler)
+        register_repository_type('documents', DocumentRepositoryHandler)
+        register_integration_type('medusa', MedusaIntegrationHandler)
+        register_integration_type('shopify', ShopifyIntegrationHandler)
+
 # enthusiast/injector.py
 from agentcore_common.injectors import BaseInjector
-from enthusiast_common.retrievers import BaseProductRetriever
 
 class EnthusiastInjector(BaseInjector):
-    def __init__(self, ..., product_retriever: BaseProductRetriever):
-        super().__init__(...)
-        self._product_retriever = product_retriever
-
-    @property
-    def product_retriever(self) -> BaseProductRetriever:
-        return self._product_retriever
+    def get_retriever(self, repository_type: str):
+        if repository_type == 'products':
+            return self._product_retriever
+        elif repository_type == 'documents':
+            return self._document_retriever
+        raise ValueError(f"No retriever for repository type: {repository_type}")
 
 # enthusiast/builder.py
-from agentcore.core.builder import AgentBuilder  # Django agentcore builder
+from agentcore.core.builder import AgentBuilder
 
 class EnthusiastAgentBuilder(AgentBuilder):
     def _build_injector(self) -> EnthusiastInjector:
-        # builds product retriever, passes to EnthusiastInjector
+        # builds product + document retrievers, passes to EnthusiastInjector
         ...
 ```
 
@@ -267,13 +275,21 @@ class EnthusiastAgentBuilder(AgentBuilder):
 | `frontend/` | `agentcore/frontend/` |
 | `server/pecl/` (project config) | `agentcore/server/pecl/` |
 
+### New in agentcore (greenfield)
+| What | Notes |
+|---|---|
+| `agentcore/models/dataset.py` | `DataSet` model — replaces `Workspace`, generic tenant |
+| `agentcore/models/repository.py` | `Repository` model — generic data collection |
+| `agentcore/models/integration.py` | `Integration` model — generic external system connector |
+| `agentcore/registry/repository_types.py` | registry for plugin-defined repository/integration type handlers |
+
 ### Stays in enthusiast
 | Current location | Notes |
 |---|---|
 | `plugins/enthusiast-common/` (e-commerce parts) | Becomes thin `enthusiast-common` |
 | `plugins/enthusiast-agent-*` | All e-commerce agents |
 | `plugins/enthusiast-source-*` | All source plugins |
-| `server/catalog/` | Moves into `plugins/enthusiast/catalog/` |
+| `server/catalog/` | Moves into `plugins/enthusiast/` (sync engine only, no DataSet) |
 | `server/sync/` | Moves into `plugins/enthusiast/sync/` |
 
 ### Renamed
@@ -329,110 +345,122 @@ class EnthusiastAgentBuilder(AgentBuilder):
 
 ---
 
-## Workspace Model (resolved)
+## Data Model (resolved)
 
-The `Conversation → DataSet` circular dependency is resolved by introducing a generic `Workspace` model in agentcore. All verticale extend it via `OneToOne`.
+`DataSet` replaces `Workspace` as the central tenant model and moves to agentcore. It is fully generic — no e-commerce concepts. Plugins extend agentcore by registering `Repository` and `Integration` types, not by extending the DataSet model via OneToOne.
 
 ```python
-# agentcore
-class Workspace(models.Model):
+# agentcore — all generic, no e-commerce concepts
+
+class DataSet(models.Model):
     name = CharField()
     owner = FK(User)
     created_at = DateTimeField()
-    llm_provider = CharField()     # platform-level LLM config
+    llm_provider = CharField()
     llm_model = CharField()
 
-class Agent(models.Model):
-    workspace = FK(Workspace)
+class Integration(models.Model):
+    """External system connection. Type and config defined by plugin."""
+    dataset = FK(DataSet)
+    name = CharField()
+    type = CharField()       # e.g. 'medusa', 'shopify', 'epic_ehr' — plugin-defined
+    config = JSONField()     # credentials, URLs, etc. — schema defined by plugin
 
-class Conversation(models.Model):
-    workspace = FK(Workspace)
+class Repository(models.Model):
+    """Data collection that agents can search. Type and config defined by plugin."""
+    dataset = FK(DataSet)
+    name = CharField()
+    type = CharField()       # e.g. 'products', 'documents', 'patients' — plugin-defined
+    config = JSONField()     # embedding model, etc. — schema defined by plugin
+    source = FK(Integration, null=True, blank=True)  # optional sync source
 
-# enthusiast
-class DataSet(models.Model):
-    workspace = OneToOneField(Workspace, related_name='dataset')
-    language = CharField()
-    embedding_provider = CharField()   # tied to pgvector store
-    embedding_model = CharField()
-    # source integration configs
-```
+class Agent(models.Model):
+    dataset = FK(DataSet)
 
-**Config override cascade:**
-```
-[1] settings.py defaults      (DEFAULT_LLM_PROVIDER, DEFAULT_LLM_MODEL)
-[2] Workspace                 (llm_provider, llm_model) — agentcore
-[3] DataSet                   (embedding_provider, embedding_model) — enthusiast
-[4] Agent config              (system_prompt, tools, memory) — agentcore
+class Conversation(models.Model):
+    dataset = FK(DataSet)
 ```
 
-`AgentBuilder` (agentcore) handles levels 1–2. `EnthusiastAgentBuilder` handles level 3.
+agentcore has **no knowledge** of what `type` means for Repository or Integration — it is a black box. The plugin registers handlers for each type it owns.
 
-## Frontend Architecture Discussion
+**BaseInjector (agentcore-common) — generic retriever access:**
+```python
+class BaseInjector(ABC):
+    @abstractmethod
+    def get_retriever(self, repository_type: str) -> BaseVectorStoreRetriever:
+        pass
 
-The frontend work is split into two iterations with a clear decision point between them.
+    @property
+    @abstractmethod
+    def chat_history(self) -> BaseChatMessageHistory:
+        pass
 
----
+    @property
+    @abstractmethod
+    def tool_scratchpad(self) -> ToolScratchpad:
+        pass
+```
 
-### Iteration 1 — Django staticfiles bundle (decided, implement now)
+No hardcoded `product_retriever` or `document_retriever` — those are enthusiast concerns.
 
-The plugin extension mechanism is intentionally simple for the first iteration. No NPM infrastructure, no package publishing, no shared types. The goal is to get the plugin system working end-to-end.
+**EnthusiastInjector (enthusiast) — implements retriever lookup by type:**
+```python
+class EnthusiastInjector(BaseInjector):
+    def get_retriever(self, repository_type: str) -> BaseVectorStoreRetriever:
+        if repository_type == 'products':
+            return self._product_retriever
+        elif repository_type == 'documents':
+            return self._document_retriever
+        raise ValueError(f"No retriever for repository type: {repository_type}")
+```
 
-**How it works:**
+**enthusiast tools use the generic interface:**
+```python
+class ProductSearchTool(BaseFunctionTool):
+    def run(self, query: str):
+        retriever = self._injector.get_retriever('products')
+        return retriever.search(query)
+```
 
+**Config cascade:**
 ```
-enthusiast/static/enthusiast/frontend/bundle.js  ← pre-built, ships with pip package
-AppConfig.ready() → register_frontend_plugin(id, bundle_url)
-GET /api/config/ → { plugins: [{ bundle: "/static/enthusiast/frontend/bundle.js" }] }
-shell → <script src="bundle.js"> → window.agentcore.registerPlugin({nav, routes})
+[1] settings.py defaults      (DEFAULT_LLM_PROVIDER, DEFAULT_LLM_MODEL)
+[2] DataSet                   (llm_provider, llm_model) — agentcore
+[3] Agent config              (system_prompt, tools, memory) — agentcore
 ```
 
-**Plugin registration (global contract via `window.agentcore`):**
-
-```typescript
-// enthusiast bundle.js — called on load, no imports from agentcore
-window.agentcore.registerPlugin({
-  id: 'enthusiast',
-  nav: [
-    { label: 'Catalog',      path: '/catalog' },
-    { label: 'Integrations', path: '/integrations' },
-  ],
-  routes: [
-    { path: '/catalog/*',      componentId: 'CatalogApp' },
-    { path: '/integrations/*', componentId: 'IntegrationsApp' },
-  ],
-  toolRenderers: {
-    'product_search': 'ProductSearchRenderer',
-    'order_intake':   'OrderIntakeRenderer',
-  },
-})
-```
+No level 3 for embedding config — that lives in `Repository.config` (per-repository, not per-DataSet).
+
+## Frontend Architecture
 
-**What ships in Iteration 1:**
-- agentcore frontend: existing React shell with a `pluginRegistry` module, `window.agentcore.registerPlugin()` global, dynamic `<script>` injection from `/api/config/`
-- enthusiast frontend: existing React app compiled to `bundle.js`, copied to `enthusiast/static/`, committed to git, shipped with pip package
+With DataSet, Repository, and Integration now living in agentcore as generic concepts, agentcore's frontend can provide a **complete, working UI without any plugin injection**.
 
-**Known limitations (acceptable for now):**
-- No TypeScript types shared between shell and plugins — plugin developers need to know the `registerPlugin()` contract by reading docs
-- Plugin components can't import from agentcore's component library — no shared UI primitives
-- DX friction: to develop the enthusiast frontend you need a running agentcore instance
+**agentcore frontend covers everything generically:**
+```
+Conversations     ← chat, history, WebSocket streaming
+DataSets          ← list, create, LLM config
+  ├── Repositories  ← add/configure/sync (generic — shows type + config)
+  └── Integrations  ← add/configure (generic — shows type + config)
+Settings          ← LLM providers, embedding providers
+```
 
-These limitations are intentional trade-offs to unblock the backend architecture work (Plans 1–3) and ship a working plugin system quickly.
+A developer installs enthusiast, creates a DataSet, adds a Repository of type `products` sourced from a `medusa` Integration — all through agentcore's generic UI. enthusiast adds **no frontend** of its own for this to work.
 
----
+**enthusiast is pure backend.** No `bundle.js`, no `window.agentcore.registerPlugin()`, no staticfiles frontend. The plugin injection system is not needed.
 
-### Iteration 2 — Frontend architecture (deferred, consult with Filip)
+---
 
-Once Plans 1–3 are shipped and the backend plugin system is stable, the frontend injection approach from Iteration 1 will have served its purpose but will show its limits — no shared types, no shared component library, DX friction when developing plugin frontend without a running agentcore.
+### Custom frontend (deferred, consult with Filip)
 
-**Before starting Iteration 2, schedule a meeting with Filip (frontend developer).** The whole frontend strategy should be his call — he will know what's practical. Topics to bring:
+If a team wants a richer UI beyond what agentcore's generic views provide — e.g. a full product catalog grid with images and filters, or custom tool output renderers that show `<ProductCard>` instead of JSON in the chat — that's a separate decision.
 
-- **Overall strategy** — is the staticfiles bundle + injection approach worth keeping long-term, or should we replace it with something fundamentally different?
-- **Chat UI library** — current chat UI is custom-built. Is there a library worth adopting (e.g. assistant-ui, or something else Filip would recommend)?
-- **Shared frontend packages** — does it make sense to extract shared types/components into packages (`@agentcore/ui`, `@enthusiast/ui`)? Or is it over-engineering for the team size?
-- **Separate frontend repo** — should the frontend live in its own repo, separate from the Python repos? Filip may prefer that as a frontend developer.
-- **Build pipeline** — how does the enthusiast bundle get built and shipped with the pip package in a maintainable way?
+**Before building any custom frontend, schedule a meeting with Filip (frontend developer).** Topics:
+- Is agentcore's generic UI sufficient for the e-commerce use case, or do we need a custom Catalog page?
+- Chat UI library — is there something worth adopting (e.g. assistant-ui)?
+- If custom frontend is needed: separate repo, NPM packages, or something else?
+- Tool output renderers — do we need them, and how should they work?
 
-No decisions are made here — this is a conversation to have with Filip, not a spec to lock in upfront.
+No decisions locked in here.
 
 ---
 
@@ -441,8 +469,8 @@ No decisions are made here — this is a conversation to have with Filip, not a
 - **Final name for agentcore** — placeholder only, needs branding discussion
 - **PyPI namespace** — check `agentcore` availability before publishing
 - **Versioning strategy** — agentcore and enthusiast version independently
-- **Workspace → DataSet extension pattern** — current decision is `DataSet OneToOne Workspace`, but this needs more thought. Is OneToOne the right Django pattern here? Could it create awkward joins or leaky abstractions when multiple verticale are installed? Are there better patterns (e.g. multi-table inheritance, a pure FK from DataSet with no back-reference on Workspace)? To be revisited before implementation of the data model.
-- **Frontend architecture (Iteration 2)** — Iteration 1 decided: Django staticfiles bundle + `window.agentcore.registerPlugin()`. Iteration 2 fully open: needs a meeting with Filip (frontend developer) to decide on chat UI library, shared package strategy, separate frontend repo, and build pipeline. See Frontend Architecture Discussion for details.
+- **Repository/Integration type registration** — how does agentcore know the config schema for a plugin-defined type (e.g. what fields does a `medusa` Integration require)? Options: (a) JSON Schema registered by plugin in `AppConfig.ready()`, (b) agentcore renders raw JSONField and plugin provides no schema, (c) plugin registers a Django form/serializer per type. Needs decision before building the DataSet configuration UI.
+- **Custom frontend** — agentcore's generic UI covers DataSet/Repository/Integration management. Whether enthusiast needs a custom Catalog page or custom chat tool renderers is an open question. Consult with Filip before any frontend work begins.
 
 ---
 
@@ -458,10 +486,10 @@ The guide should cover:
 
 | Class | Where | What to implement |
 |---|---|---|
-| `BaseInjector` | `agentcore-common` | `document_retriever`, `chat_history`, `tool_scratchpad` properties |
+| `BaseInjector` | `agentcore-common` | `get_retriever(type)`, `chat_history`, `tool_scratchpad` |
 | `BaseAgentBuilder` | `agentcore-common` | `_build_injector()`, `_build_llm_registry()`, `_build_tools()`, `_build_agent()`, and related factory methods |
-| `BaseConversationRepository` | `agentcore-common` | `get_workspace_id()`, `get_agent_id()`, `list_files()`, `get_file_objects()` |
-| `BaseWorkspaceRepository` | `agentcore-common` | standard CRUD methods from `BaseRepository` |
+| `BaseConversationRepository` | `agentcore-common` | `get_dataset_id()`, `get_agent_id()`, `list_files()`, `get_file_objects()` |
+| `BaseDataSetRepository` | `agentcore-common` | standard CRUD methods from `BaseRepository` |
 
 **Can implement** — optional extension points that unlock additional capabilities:
 
@@ -478,21 +506,19 @@ The guide should cover:
 
 | Item | Required? | Purpose |
 |---|---|---|
-| `AppConfig.ready()` calls `register_frontend_plugin()` | optional | registers frontend bundle with agentcore shell |
+| `AppConfig.ready()` registers repository/integration types | optional | agentcore knows what types this plugin handles |
 | `INSTALLED_APPS` entry | required | Django discovers models, migrations, admin |
-| `settings_override.py` entries (`AGENTCORE_AGENT_PLUGINS`, etc.) | required | registers agents, sources with agentcore registries |
-| `OneToOneField(Workspace, related_name='+')` on domain model | recommended | extends Workspace with vertical-specific config |
+| `settings_override.py` entries (`AGENTCORE_AGENT_PLUGINS`, etc.) | required | registers agents with agentcore registries |
 
 ### What the guide should walk through step by step
 
 1. Create a new Python package (pip-installable)
-2. Define a domain model extending `Workspace` via `OneToOneField`
-3. Implement `BaseInjector` with domain-specific retrievers
+2. Register repository types and integration types in `AppConfig.ready()`
+3. Implement `BaseInjector.get_retriever(type)` for your repository types
 4. Implement `BaseAgentBuilder` wiring up the injector and tools
-5. Write a simple `BaseFunctionTool`
-6. Register everything in `settings_override.py`
-7. Write a minimal frontend bundle that calls `window.agentcore.registerPlugin()`
-8. Ship it: `pip install yourplugin` + `INSTALLED_APPS += ['yourplugin']`
+5. Write domain-specific tools using `self._injector.get_retriever('your_type')`
+6. Register agents in `settings_override.py`
+7. Ship it: `pip install yourplugin` + `INSTALLED_APPS += ['yourplugin']`
 
 enthusiast itself serves as the living reference for all of the above.
 

From 90dc22458195a83fb11991a248fe43a3127b5c24 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Fri, 22 May 2026 11:48:03 +0200
Subject: [PATCH 03/16] docs: rename pecl to agentcore_project, clarify schema
 registration approach

---
 specs/ai-agent-core-extraction.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 1eb2dba6..5159dd4b 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -54,7 +54,7 @@ agentcore/
     manage.py
     settings.py             # base settings, INSTALLED_APPS = ['agentcore']
     settings_override.py    # env-based user config (add verticale here)
-    pecl/
+    agentcore_project/      # Django project config (replaces old 'pecl' name)
       urls.py
       wsgi.py / asgi.py
       celery.py
@@ -469,7 +469,7 @@ No decisions locked in here.
 - **Final name for agentcore** — placeholder only, needs branding discussion
 - **PyPI namespace** — check `agentcore` availability before publishing
 - **Versioning strategy** — agentcore and enthusiast version independently
-- **Repository/Integration type registration** — how does agentcore know the config schema for a plugin-defined type (e.g. what fields does a `medusa` Integration require)? Options: (a) JSON Schema registered by plugin in `AppConfig.ready()`, (b) agentcore renders raw JSONField and plugin provides no schema, (c) plugin registers a Django form/serializer per type. Needs decision before building the DataSet configuration UI.
+- **Repository/Integration config schema** — how does agentcore know what fields to show when configuring a plugin-defined type? Recommendation: plugin registers a JSON Schema in `AppConfig.ready()`, agentcore renders a generic form (e.g. via `react-jsonschema-form`). Same pattern as Airbyte connector config. Needs confirmation before building the DataSet configuration UI.
 - **Custom frontend** — agentcore's generic UI covers DataSet/Repository/Integration management. Whether enthusiast needs a custom Catalog page or custom chat tool renderers is an open question. Consult with Filip before any frontend work begins.
 
 ---

From 209bfb5469cc40e4cd4fa234f46e3770aca93208 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 14:39:35 +0200
Subject: [PATCH 04/16] docs: update agentcore spec with session 2 architecture
 decisions

---
 specs/ai-agent-core-extraction.md | 131 +++++++++++++++++++-----------
 1 file changed, 83 insertions(+), 48 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 5159dd4b..d68da203 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -60,7 +60,7 @@ agentcore/
       celery.py
     docker-compose.yml
     agentcore/              # Django app
-      models/               # DataSet, Repository, Integration,
+      models/               # DataSet, Integration,
                             # Conversation, Message, Agent, AgenticExecution
       core/
         builder.py          # AgentBuilder (Django implementation)
@@ -107,7 +107,8 @@ agentcore/
 
 **What agentcore provides out of the box:**
 - Conversation management (create, respond, history)
-- Agent registration and execution
+- Agent registration and execution (global registry, `AppConfig.ready()` pattern)
+- `ToolCallingAgent` — generic tool-calling agent, no built-in tools (plugins register tools)
 - WebSocket streaming of agent responses
 - Agentic execution engine (autonomous multi-step tasks with retries/validators)
 - LLM provider plugins (OpenAI, Anthropic, Google, Mistral, Ollama, Azure)
@@ -134,13 +135,15 @@ enthusiast/
       retrievers/           # BaseProductRetriever
     enthusiast/             # Django app (PyPI: enthusiast)
       models/               # Product, ProductChunk, Document, DocumentChunk
-                            # (no DataSet — that lives in agentcore now)
-      sync/                 # Source synchronization engine (syncs to agentcore Repository)
+                            # all with FK to agentcore.DataSet
+      apps.py               # AppConfig.ready() registers builder, tools, integrations
+      sync/                 # Source synchronization engine (products + documents)
+      integrations/         # MedusaIntegration, ShopifyIntegration handlers
       injector.py           # EnthusiastInjector — implements get_retriever(type)
       builder.py            # EnthusiastAgentBuilder (extends BaseAgentBuilder)
       repositories.py       # Django ORM implementations for e-commerce models
       retrievers/           # ProductRetriever, DocumentRetriever (pgvector)
-      handlers.py           # ProductRepositoryHandler, MedusaIntegrationHandler, etc.
+      tools/                # ProductSearchTool, DocumentSearchTool, OrderManagementTool
       admin.py
       urls.py
       serializers/
@@ -225,17 +228,23 @@ Each vertical plugin follows the same pattern — never modifies agentcore setti
 
 ### How enthusiast extends agentcore
 
-enthusiast provides Django-specific implementations of agentcore's abstract bases. It registers its repository types (`products`, `documents`) and integration types (`medusa`, `shopify`, etc.) with agentcore at startup:
+enthusiast registers its builder, tools, and integration types with agentcore via `AppConfig.ready()`. agentcore has no knowledge of what these do — it only knows they implement the right interfaces.
 
 ```python
 # enthusiast/apps.py
 class EnthusiastAppConfig(AppConfig):
     def ready(self):
-        from agentcore.registry import register_repository_type, register_integration_type
-        register_repository_type('products', ProductRepositoryHandler)
-        register_repository_type('documents', DocumentRepositoryHandler)
-        register_integration_type('medusa', MedusaIntegrationHandler)
-        register_integration_type('shopify', ShopifyIntegrationHandler)
+        from agentcore.registry import agent_registry, tool_registry, integration_registry
+        from .builder import EnthusiastAgentBuilder
+        from .tools import ProductSearchTool, DocumentSearchTool, OrderManagementTool
+        from .integrations import MedusaIntegration, ShopifyIntegration
+
+        agent_registry.register_builder(EnthusiastAgentBuilder)
+        tool_registry.register(ProductSearchTool)
+        tool_registry.register(DocumentSearchTool)
+        tool_registry.register(OrderManagementTool)
+        integration_registry.register('medusa', MedusaIntegration)
+        integration_registry.register('shopify', ShopifyIntegration)
 
 # enthusiast/injector.py
 from agentcore_common.injectors import BaseInjector
@@ -249,14 +258,23 @@ class EnthusiastInjector(BaseInjector):
         raise ValueError(f"No retriever for repository type: {repository_type}")
 
 # enthusiast/builder.py
-from agentcore.core.builder import AgentBuilder
+from agentcore_common.agents import BaseAgentBuilder
 
-class EnthusiastAgentBuilder(AgentBuilder):
+class EnthusiastAgentBuilder(BaseAgentBuilder):
     def _build_injector(self) -> EnthusiastInjector:
+        # reads dataset.embedding_provider, dataset.embedding_model from DataSet
         # builds product + document retrievers, passes to EnthusiastInjector
         ...
+
+    def _build_tools(self) -> list:
+        # picks up registered tools from tool_registry
+        ...
 ```
 
+**Repositories are code-defined, not UI-created.** When enthusiast is installed, every DataSet automatically has product and document retrieval capabilities — no "Add Repository" step in UI. The admin sees this reflected in "Agent Capabilities", not in a repository list.
+
+Enthusiast's models (`Product`, `Document`, `ProductChunk`, `DocumentChunk`) all have a direct FK to `DataSet` from agentcore. No OneToOne extension of DataSet is needed — all configuration lives in `DataSet` itself (LLM config, embedding config) or in enthusiast's own `Integration` records.
+
 ---
 
 ## What Moves Where
@@ -278,10 +296,10 @@ class EnthusiastAgentBuilder(AgentBuilder):
 ### New in agentcore (greenfield)
 | What | Notes |
 |---|---|
-| `agentcore/models/dataset.py` | `DataSet` model — replaces `Workspace`, generic tenant |
-| `agentcore/models/repository.py` | `Repository` model — generic data collection |
-| `agentcore/models/integration.py` | `Integration` model — generic external system connector |
-| `agentcore/registry/repository_types.py` | registry for plugin-defined repository/integration type handlers |
+| `agentcore/models/dataset.py` | `DataSet` model — replaces `Workspace`, holds LLM + embedding config |
+| `agentcore/models/integration.py` | `Integration` model — generic external system connector, type defined by plugin |
+| `agentcore/registry/` | Global registries: `agent_registry`, `tool_registry`, `integration_registry` |
+| `agentcore/agents/tool_calling.py` | `ToolCallingAgent` — generic tool-calling agent, no built-in tools |
 
 ### Stays in enthusiast
 | Current location | Notes |
@@ -347,7 +365,9 @@ class EnthusiastAgentBuilder(AgentBuilder):
 
 ## Data Model (resolved)
 
-`DataSet` replaces `Workspace` as the central tenant model and moves to agentcore. It is fully generic — no e-commerce concepts. Plugins extend agentcore by registering `Repository` and `Integration` types, not by extending the DataSet model via OneToOne.
+`DataSet` replaces `Workspace` as the central tenant model and moves to agentcore. It is fully generic — no e-commerce concepts. Plugins do **not** extend DataSet via OneToOne — all shared configuration (LLM + embedding) lives directly on `DataSet`. Plugin models (e.g. `Product`, `Document`) reference `DataSet` via a plain FK.
+
+There is no `Repository` model in agentcore. Repositories are code-defined by plugins — installed automatically when a plugin is added to `INSTALLED_APPS`, not created through the UI.
 
 ```python
 # agentcore — all generic, no e-commerce concepts
@@ -356,23 +376,22 @@ class DataSet(models.Model):
     name = CharField()
     owner = FK(User)
     created_at = DateTimeField()
+    # LLM config — selected per DataSet in UI, credentials in env vars
     llm_provider = CharField()
     llm_model = CharField()
+    # Embedding config — agentcore stores these, plugins read and use them
+    embedding_provider = CharField()
+    embedding_model = CharField()
+    embedding_dimensions = IntegerField()
+    chunk_size = IntegerField()
+    chunk_overlap = IntegerField()
 
 class Integration(models.Model):
-    """External system connection. Type and config defined by plugin."""
-    dataset = FK(DataSet)
-    name = CharField()
-    type = CharField()       # e.g. 'medusa', 'shopify', 'epic_ehr' — plugin-defined
-    config = JSONField()     # credentials, URLs, etc. — schema defined by plugin
-
-class Repository(models.Model):
-    """Data collection that agents can search. Type and config defined by plugin."""
+    """External system connection (e.g. Medusa, Shopify). Type and config defined by plugin."""
     dataset = FK(DataSet)
     name = CharField()
-    type = CharField()       # e.g. 'products', 'documents', 'patients' — plugin-defined
-    config = JSONField()     # embedding model, etc. — schema defined by plugin
-    source = FK(Integration, null=True, blank=True)  # optional sync source
+    type = CharField()       # e.g. 'medusa', 'shopify' — registered by plugin
+    config = JSONField()     # URLs, non-sensitive config — schema defined by plugin
 
 class Agent(models.Model):
     dataset = FK(DataSet)
@@ -381,7 +400,20 @@ class Conversation(models.Model):
     dataset = FK(DataSet)
 ```
 
-agentcore has **no knowledge** of what `type` means for Repository or Integration — it is a black box. The plugin registers handlers for each type it owns.
+**Sensitive credentials** (API keys, tokens) always go to environment variables — never stored in `Integration.config`.
+
+```python
+# enthusiast — e-commerce models reference DataSet directly
+class Product(models.Model):
+    dataset = FK("agentcore.DataSet")
+    ...
+
+class Document(models.Model):
+    dataset = FK("agentcore.DataSet")
+    ...
+```
+
+agentcore has **no knowledge** of what `type` means for Integration — it is a black box. The plugin registers a handler in `AppConfig.ready()` and agentcore renders a generic config form using the JSON Schema the plugin provides.
 
 **BaseInjector (agentcore-common) — generic retriever access:**
 ```python
@@ -424,27 +456,29 @@ class ProductSearchTool(BaseFunctionTool):
 
 **Config cascade:**
 ```
-[1] settings.py defaults      (DEFAULT_LLM_PROVIDER, DEFAULT_LLM_MODEL)
-[2] DataSet                   (llm_provider, llm_model) — agentcore
-[3] Agent config              (system_prompt, tools, memory) — agentcore
+[1] settings.py / env vars    sensitive credentials only (OPENAI_API_KEY etc.)
+[2] DataSet                   llm_provider, llm_model,
+                              embedding_provider, embedding_model,
+                              embedding_dimensions, chunk_size, chunk_overlap
+[3] Agent config              system_prompt, tools, memory strategy
 ```
 
-No level 3 for embedding config — that lives in `Repository.config` (per-repository, not per-DataSet).
+Embedding config lives on `DataSet`, not per-repository. All DataSet config is set in the UI at creation time — no settings file entries for these values.
 
 ## Frontend Architecture
 
-With DataSet, Repository, and Integration now living in agentcore as generic concepts, agentcore's frontend can provide a **complete, working UI without any plugin injection**.
+agentcore's frontend provides a **complete, working UI without any plugin injection**.
 
-**agentcore frontend covers everything generically:**
+**agentcore frontend covers:**
 ```
 Conversations     ← chat, history, WebSocket streaming
-DataSets          ← list, create, LLM config
-  ├── Repositories  ← add/configure/sync (generic — shows type + config)
-  └── Integrations  ← add/configure (generic — shows type + config)
+DataSets          ← list, create, configure (LLM + embedding)
+  └── Integrations  ← add/configure external systems (generic — type + config form)
+Agent Capabilities  ← auto-discovered from registry (read-only, code-defined)
 Settings          ← LLM providers, embedding providers
 ```
 
-A developer installs enthusiast, creates a DataSet, adds a Repository of type `products` sourced from a `medusa` Integration — all through agentcore's generic UI. enthusiast adds **no frontend** of its own for this to work.
+**Repositories are not managed in the UI.** When enthusiast is installed, product and document retrieval capabilities appear automatically in "Agent Capabilities" — the admin does not create or configure them. Only `Integration` records (e.g. Medusa API connection) require UI configuration.
 
 **enthusiast is pure backend.** No `bundle.js`, no `window.agentcore.registerPlugin()`, no staticfiles frontend. The plugin injection system is not needed.
 
@@ -469,8 +503,8 @@ No decisions locked in here.
 - **Final name for agentcore** — placeholder only, needs branding discussion
 - **PyPI namespace** — check `agentcore` availability before publishing
 - **Versioning strategy** — agentcore and enthusiast version independently
-- **Repository/Integration config schema** — how does agentcore know what fields to show when configuring a plugin-defined type? Recommendation: plugin registers a JSON Schema in `AppConfig.ready()`, agentcore renders a generic form (e.g. via `react-jsonschema-form`). Same pattern as Airbyte connector config. Needs confirmation before building the DataSet configuration UI.
-- **Custom frontend** — agentcore's generic UI covers DataSet/Repository/Integration management. Whether enthusiast needs a custom Catalog page or custom chat tool renderers is an open question. Consult with Filip before any frontend work begins.
+- **Integration config schema** — how does agentcore know what fields to show when configuring a plugin-defined Integration type? Recommendation: plugin registers a JSON Schema in `AppConfig.ready()`, agentcore renders a generic form (e.g. via `react-jsonschema-form`). Same pattern as Airbyte connector config. Needs confirmation before building the Integration configuration UI.
+- **Custom frontend** — agentcore's generic UI covers DataSet/Integration management and a read-only Agent Capabilities view. Whether enthusiast needs a richer Catalog page (products grid, document browser) or custom chat tool renderers is deferred. Consult with Filip before any frontend work begins.
 
 ---
 
@@ -506,19 +540,20 @@ The guide should cover:
 
 | Item | Required? | Purpose |
 |---|---|---|
-| `AppConfig.ready()` registers repository/integration types | optional | agentcore knows what types this plugin handles |
+| `AppConfig.ready()` registers builder, tools, integration types | required | agentcore discovers what this plugin contributes |
 | `INSTALLED_APPS` entry | required | Django discovers models, migrations, admin |
 | `settings_override.py` entries (`AGENTCORE_AGENT_PLUGINS`, etc.) | required | registers agents with agentcore registries |
 
 ### What the guide should walk through step by step
 
 1. Create a new Python package (pip-installable)
-2. Register repository types and integration types in `AppConfig.ready()`
-3. Implement `BaseInjector.get_retriever(type)` for your repository types
-4. Implement `BaseAgentBuilder` wiring up the injector and tools
+2. Define your domain models with FK to `agentcore.DataSet`
+3. Implement `BaseInjector.get_retriever(type)` for your data types
+4. Implement `BaseAgentBuilder` — wires up injector, reads DataSet embedding config, builds tools
 5. Write domain-specific tools using `self._injector.get_retriever('your_type')`
-6. Register agents in `settings_override.py`
-7. Ship it: `pip install yourplugin` + `INSTALLED_APPS += ['yourplugin']`
+6. Register integration types in `AppConfig.ready()` (provide JSON Schema for config form)
+7. Register builder and tools in `AppConfig.ready()`
+8. Ship it: `pip install yourplugin` + `INSTALLED_APPS += ['yourplugin']`
 
 enthusiast itself serves as the living reference for all of the above.
 

From ce3858702234aa2a809861ac759be33c29c30018 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 14:47:05 +0200
Subject: [PATCH 05/16] docs: unify plugin registration on settings, remove
 AppConfig.ready() pattern

---
 specs/ai-agent-core-extraction.md | 55 +++++++++++++++----------------
 1 file changed, 26 insertions(+), 29 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index d68da203..7359f79b 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -192,7 +192,7 @@ agentcore `settings.py` defines base config. Users extend via `settings_override
 # agentcore/server/settings.py
 INSTALLED_APPS = [
     'agentcore',
-    # vertical plugins added via settings_override:
+    # vertical plugins added via settings_override
 ]
 
 AGENTCORE_LANGUAGE_MODEL_PLUGINS = [
@@ -203,8 +203,11 @@ AGENTCORE_LANGUAGE_MODEL_PLUGINS = [
     'agentcore_model_ollama.OllamaLanguageModelProvider',
     'agentcore_model_azureopenai.AzureOpenAILanguageModelProvider',
 ]
-AGENTCORE_AGENT_PLUGINS = []
 AGENTCORE_EMBEDDING_PLUGINS = []
+AGENTCORE_AGENT_PLUGINS = []
+AGENTCORE_TOOL_PLUGINS = []
+AGENTCORE_BUILDER_PLUGINS = []
+AGENTCORE_INTEGRATION_PLUGINS = []
 
 # agentcore/server/settings_override.py (user-configured, env-based)
 INSTALLED_APPS += ['enthusiast']
@@ -216,9 +219,17 @@ AGENTCORE_AGENT_PLUGINS = [
     'enthusiast_agent_user_manual_search.UserManualSearchAgent',
     'enthusiast_agent_invoice_scanning.InvoiceScanningAgent',
 ]
-AGENTCORE_SOURCE_PLUGINS = [
-    'enthusiast_source_medusa.MedusaIntegration',
-    # ...
+AGENTCORE_TOOL_PLUGINS = [
+    'enthusiast.tools.ProductSearchTool',
+    'enthusiast.tools.DocumentSearchTool',
+    'enthusiast.tools.OrderManagementTool',
+]
+AGENTCORE_BUILDER_PLUGINS = [
+    'enthusiast.builder.EnthusiastAgentBuilder',
+]
+AGENTCORE_INTEGRATION_PLUGINS = [
+    'enthusiast.integrations.MedusaIntegration',
+    'enthusiast.integrations.ShopifyIntegration',
 ]
 ```
 
@@ -228,24 +239,9 @@ Each vertical plugin follows the same pattern — never modifies agentcore setti
 
 ### How enthusiast extends agentcore
 
-enthusiast registers its builder, tools, and integration types with agentcore via `AppConfig.ready()`. agentcore has no knowledge of what these do — it only knows they implement the right interfaces.
+enthusiast is registered entirely through `settings_override.py`. agentcore reads the settings lists at startup and loads the declared classes — no runtime `register()` calls, no `AppConfig.ready()` magic.
 
 ```python
-# enthusiast/apps.py
-class EnthusiastAppConfig(AppConfig):
-    def ready(self):
-        from agentcore.registry import agent_registry, tool_registry, integration_registry
-        from .builder import EnthusiastAgentBuilder
-        from .tools import ProductSearchTool, DocumentSearchTool, OrderManagementTool
-        from .integrations import MedusaIntegration, ShopifyIntegration
-
-        agent_registry.register_builder(EnthusiastAgentBuilder)
-        tool_registry.register(ProductSearchTool)
-        tool_registry.register(DocumentSearchTool)
-        tool_registry.register(OrderManagementTool)
-        integration_registry.register('medusa', MedusaIntegration)
-        integration_registry.register('shopify', ShopifyIntegration)
-
 # enthusiast/injector.py
 from agentcore_common.injectors import BaseInjector
 
@@ -266,8 +262,8 @@ class EnthusiastAgentBuilder(BaseAgentBuilder):
         # builds product + document retrievers, passes to EnthusiastInjector
         ...
 
-    def _build_tools(self) -> list:
-        # picks up registered tools from tool_registry
+    def _build_tools(self) -> list[BaseTool]:
+        # instantiates tools from AGENTCORE_TOOL_PLUGINS
         ...
 ```
 
@@ -298,7 +294,7 @@ Enthusiast's models (`Product`, `Document`, `ProductChunk`, `DocumentChunk`) all
 |---|---|
 | `agentcore/models/dataset.py` | `DataSet` model — replaces `Workspace`, holds LLM + embedding config |
 | `agentcore/models/integration.py` | `Integration` model — generic external system connector, type defined by plugin |
-| `agentcore/registry/` | Global registries: `agent_registry`, `tool_registry`, `integration_registry` |
+| `agentcore/registry/` | Loads plugin classes from settings lists at startup (`AGENTCORE_*_PLUGINS`) |
 | `agentcore/agents/tool_calling.py` | `ToolCallingAgent` — generic tool-calling agent, no built-in tools |
 
 ### Stays in enthusiast
@@ -540,9 +536,11 @@ The guide should cover:
 
 | Item | Required? | Purpose |
 |---|---|---|
-| `AppConfig.ready()` registers builder, tools, integration types | required | agentcore discovers what this plugin contributes |
 | `INSTALLED_APPS` entry | required | Django discovers models, migrations, admin |
-| `settings_override.py` entries (`AGENTCORE_AGENT_PLUGINS`, etc.) | required | registers agents with agentcore registries |
+| `AGENTCORE_BUILDER_PLUGINS` entry | required | agentcore loads your AgentBuilder |
+| `AGENTCORE_TOOL_PLUGINS` entries | required | agentcore loads your tools |
+| `AGENTCORE_AGENT_PLUGINS` entries | required | agentcore exposes your agents in the UI |
+| `AGENTCORE_INTEGRATION_PLUGINS` entries | optional | registers integration types with config schema |
 
 ### What the guide should walk through step by step
 
@@ -551,9 +549,8 @@ The guide should cover:
 3. Implement `BaseInjector.get_retriever(type)` for your data types
 4. Implement `BaseAgentBuilder` — wires up injector, reads DataSet embedding config, builds tools
 5. Write domain-specific tools using `self._injector.get_retriever('your_type')`
-6. Register integration types in `AppConfig.ready()` (provide JSON Schema for config form)
-7. Register builder and tools in `AppConfig.ready()`
-8. Ship it: `pip install yourplugin` + `INSTALLED_APPS += ['yourplugin']`
+6. Add entries to `settings_override.py`: `AGENTCORE_BUILDER_PLUGINS`, `AGENTCORE_TOOL_PLUGINS`, `AGENTCORE_AGENT_PLUGINS`
+7. Ship it: `pip install yourplugin` + add settings entries
 
 enthusiast itself serves as the living reference for all of the above.
 

From 601f9e162ee7c548e1f3ba9db82167c9d4c6bed3 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 14:52:04 +0200
Subject: [PATCH 06/16] =?UTF-8?q?docs:=20fix=20Must=20implement=20list=20?=
 =?UTF-8?q?=E2=80=94=20agentcore=20owns=20repository=20implementations?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 specs/ai-agent-core-extraction.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 7359f79b..63006556 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -499,7 +499,7 @@ No decisions locked in here.
 - **Final name for agentcore** — placeholder only, needs branding discussion
 - **PyPI namespace** — check `agentcore` availability before publishing
 - **Versioning strategy** — agentcore and enthusiast version independently
-- **Integration config schema** — how does agentcore know what fields to show when configuring a plugin-defined Integration type? Recommendation: plugin registers a JSON Schema in `AppConfig.ready()`, agentcore renders a generic form (e.g. via `react-jsonschema-form`). Same pattern as Airbyte connector config. Needs confirmation before building the Integration configuration UI.
+- **Integration config schema** — how does agentcore know what fields to show when configuring a plugin-defined Integration type? Recommendation: plugin declares a JSON Schema on its integration class (class attribute), agentcore reads it from `AGENTCORE_INTEGRATION_PLUGINS` and renders a generic form (e.g. via `react-jsonschema-form`). Same pattern as Airbyte connector config. Needs confirmation before building the Integration configuration UI.
 - **Custom frontend** — agentcore's generic UI covers DataSet/Integration management and a read-only Agent Capabilities view. Whether enthusiast needs a richer Catalog page (products grid, document browser) or custom chat tool renderers is deferred. Consult with Filip before any frontend work begins.
 
 ---
@@ -512,14 +512,14 @@ The guide should cover:
 
 ### What agentcore exposes (the extension points)
 
-**Must implement** — these are abstract, agentcore won't run without a concrete implementation:
+**Must implement** — these are the two classes every vertical plugin must provide:
 
 | Class | Where | What to implement |
 |---|---|---|
 | `BaseInjector` | `agentcore-common` | `get_retriever(type)`, `chat_history`, `tool_scratchpad` |
-| `BaseAgentBuilder` | `agentcore-common` | `_build_injector()`, `_build_llm_registry()`, `_build_tools()`, `_build_agent()`, and related factory methods |
-| `BaseConversationRepository` | `agentcore-common` | `get_dataset_id()`, `get_agent_id()`, `list_files()`, `get_file_objects()` |
-| `BaseDataSetRepository` | `agentcore-common` | standard CRUD methods from `BaseRepository` |
+| `BaseAgentBuilder` | `agentcore-common` | `_build_injector()`, `_build_llm_registry()`, `_build_tools()`, `_build_agent()` |
+
+`BaseConversationRepository`, `BaseDataSetRepository`, and all other repository bases are implemented by agentcore itself in `agentcore/core/repositories.py`. Plugins use them — they do not re-implement them.
 
 **Can implement** — optional extension points that unlock additional capabilities:
 

From 9be364afaaf49f7a3db74de44073a1c69029426c Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 15:21:40 +0200
Subject: [PATCH 07/16] docs: Integration is OneToOne per DataSet, not many

---
 specs/ai-agent-core-extraction.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 63006556..757cf8dd 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -383,9 +383,8 @@ class DataSet(models.Model):
     chunk_overlap = IntegerField()
 
 class Integration(models.Model):
-    """External system connection (e.g. Medusa, Shopify). Type and config defined by plugin."""
-    dataset = FK(DataSet)
-    name = CharField()
+    """External system connection (e.g. Medusa, Shopify). One per DataSet."""
+    dataset = OneToOneField(DataSet, on_delete=CASCADE)
     type = CharField()       # e.g. 'medusa', 'shopify' — registered by plugin
     config = JSONField()     # URLs, non-sensitive config — schema defined by plugin
 

From a05a43bed74a55993140ac0009fd2184550cfe89 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 15:23:58 +0200
Subject: [PATCH 08/16] =?UTF-8?q?docs:=20fix=204=20spec=20inconsistencies?=
 =?UTF-8?q?=20=E2=80=94=20retriever=20placement,=20registration=20model,?=
 =?UTF-8?q?=20dep=20graph,=20BaseProductRetriever=20hierarchy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 specs/ai-agent-core-extraction.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 757cf8dd..be740f03 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -68,7 +68,7 @@ agentcore/
         memory/             # PersistentChatHistory, memory strategies
         registries/         # LanguageModelRegistry, EmbeddingRegistry, etc.
         repositories.py     # Django ORM implementations of base repos
-        retrievers/         # DocumentRetriever, base vector search
+        retrievers/         # BaseVectorStoreRetriever (infrastructure only)
         callbacks/          # WebSocket callback handler
       consumers/            # Django Channels WebSocket consumer
       conversation/         # ConversationManager
@@ -175,13 +175,16 @@ agentcore (Django app)         agentcore-model-*
 enthusiast-common         (no dependency on agentcore-common — fully independent)
       ↑                              ↑               ↑
 enthusiast (Django app)    enthusiast-agent-*    enthusiast-source-*
-      ↑                         ↑
+      ↑                         ↑    ↑
    agentcore              agentcore-common
                           enthusiast-common
+                          enthusiast          # domain models (Product, Document, retrievers)
 ```
 
 Key rule: **`enthusiast-common` has zero dependency on `agentcore-common`**. E-commerce interfaces are fully independent of the AI agent framework.
 
+**`BaseProductRetriever` inheritance:** `enthusiast-common` declares `BaseProductRetriever(ABC)` with no dependency on agentcore-common. The concrete `ProductRetriever` in `enthusiast` uses multiple inheritance — `ProductRetriever(BaseProductRetriever, BaseVectorStoreRetriever)` — picking up the agentcore-common interface at the Django app level where both packages are available.
+
 ---
 
 ### Plugin Registration (Django settings)
@@ -408,7 +411,7 @@ class Document(models.Model):
     ...
 ```
 
-agentcore has **no knowledge** of what `type` means for Integration — it is a black box. The plugin registers a handler in `AppConfig.ready()` and agentcore renders a generic config form using the JSON Schema the plugin provides.
+agentcore has **no knowledge** of what `type` means for Integration — it is a black box. The plugin declares a `config_schema` class attribute (JSON Schema) on its integration class; agentcore reads it from `AGENTCORE_INTEGRATION_PLUGINS` at startup and renders a generic config form.
 
 **BaseInjector (agentcore-common) — generic retriever access:**
 ```python

From a1579e914ed661fb1f03d78bfe37f387413e83ea Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 15:30:26 +0200
Subject: [PATCH 09/16] =?UTF-8?q?docs:=20fix=20credential=20separation=20?=
 =?UTF-8?q?=E2=80=94=20per-DataSet=20keys=20in=20Integration.config,=20not?=
 =?UTF-8?q?=20env=20vars?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 specs/ai-agent-core-extraction.md | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index be740f03..4fb6ec5f 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -398,7 +398,7 @@ class Conversation(models.Model):
     dataset = FK(DataSet)
 ```
 
-**Sensitive credentials** (API keys, tokens) always go to environment variables — never stored in `Integration.config`.
+**Credential separation:** Global credentials shared across all DataSets (e.g. `OPENAI_API_KEY`) go to environment variables. Per-DataSet credentials (e.g. Medusa API key — each DataSet is a different store) go into `Integration.config` in the database, since there's no sensible way to put per-DataSet secrets in a flat env var namespace.
 
 ```python
 # enthusiast — e-commerce models reference DataSet directly
@@ -454,14 +454,17 @@ class ProductSearchTool(BaseFunctionTool):
 
 **Config cascade:**
 ```
-[1] settings.py / env vars    sensitive credentials only (OPENAI_API_KEY etc.)
-[2] DataSet                   llm_provider, llm_model,
-                              embedding_provider, embedding_model,
-                              embedding_dimensions, chunk_size, chunk_overlap
-[3] Agent config              system_prompt, tools, memory strategy
+[1] env vars          global credentials — OPENAI_API_KEY, ANTHROPIC_API_KEY
+                      (one per deployment, shared across all DataSets)
+[2] DataSet           llm_provider, llm_model,
+                      embedding_provider, embedding_model,
+                      embedding_dimensions, chunk_size, chunk_overlap
+[3] Integration       per-DataSet external system config — url, api_key
+                      (e.g. each DataSet has its own Medusa store + key)
+[4] Agent config      system_prompt, tools, memory strategy
 ```
 
-Embedding config lives on `DataSet`, not per-repository. All DataSet config is set in the UI at creation time — no settings file entries for these values.
+All DataSet and Integration config is set in the UI — no settings file entries for these values.
 
 ## Frontend Architecture
 

From 69a36d16a861687ecf80ecb5b79862ca9498e908 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 16:11:42 +0200
Subject: [PATCH 10/16] docs: simplify spec to high-level plan and direction

---
 specs/ai-agent-core-extraction.md | 587 +++++-------------------------
 1 file changed, 82 insertions(+), 505 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 4fb6ec5f..6c8ccc1b 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -4,567 +4,144 @@
 
 ---
 
-## Overview
+## Problem
 
-Extract the domain-agnostic AI agent framework from Enthusiast into a standalone platform called **agentcore** (placeholder name — final name TBD). Enthusiast becomes an e-commerce vertical plugin installed on top of agentcore. Other verticals (healthcare, logistics, etc.) can be built the same way.
+Enthusiast's AI agent infrastructure is tightly coupled with e-commerce domain concepts (products, documents, catalog). This prevents the agent framework from being reused in other domains and makes the codebase harder to reason about as each layer grows.
 
 ---
 
-## Problem Statement
+## Goal
 
-Enthusiast's AI agent infrastructure (conversation management, agent framework, LLM providers, memory, WebSocket streaming) is tightly coupled with e-commerce domain concepts (products, documents, DataSets). This prevents the agent core from being reused in other domains and makes the codebase harder to reason about as each layer grows.
+Extract a standalone AI agent platform (**agentcore** — name TBD) that is completely domain-agnostic. Enthusiast becomes an e-commerce vertical plugin that installs on top of agentcore. Other verticals (healthcare, logistics, etc.) can be built the same way.
 
 ---
 
-## Goals
+## Two Repositories
 
-- Decouple AI agent infrastructure from e-commerce domain logic
-- Make agentcore a general-purpose platform other verticals can build on
-- Enthusiast becomes a true plugin — installable on agentcore with no modifications to core
-- agentcore is useful standalone (without enthusiast) out of the box
+**`agentcore`** — the platform. A runnable Django project. Users clone it, configure settings, and install vertical plugins on top.
 
----
-
-## Non-Goals
-
-- Abstracting over LangChain — it stays as a hard dependency in agentcore
-- Building a plugin marketplace or auto-discovery mechanism — Django settings is sufficient
-- Merging into a monorepo — two separate repos from day one
-
----
-
-## Architecture
-
-### Repository Structure
-
-**Two separate repositories:**
-
-1. `github.com/upsidelab/agentcore` — the platform
-2. `github.com/upsidelab/enthusiast` — the e-commerce vertical plugin
-
----
-
-### agentcore repo (the platform)
-
-agentcore is a **runnable Django project**. Users clone/install it, configure settings, and install vertical plugins on top.
-
-```
-agentcore/
-  server/
-    manage.py
-    settings.py             # base settings, INSTALLED_APPS = ['agentcore']
-    settings_override.py    # env-based user config (add verticale here)
-    agentcore_project/      # Django project config (replaces old 'pecl' name)
-      urls.py
-      wsgi.py / asgi.py
-      celery.py
-    docker-compose.yml
-    agentcore/              # Django app
-      models/               # DataSet, Integration,
-                            # Conversation, Message, Agent, AgenticExecution
-      core/
-        builder.py          # AgentBuilder (Django implementation)
-        injector.py         # Injector (Django implementation)
-        memory/             # PersistentChatHistory, memory strategies
-        registries/         # LanguageModelRegistry, EmbeddingRegistry, etc.
-        repositories.py     # Django ORM implementations of base repos
-        retrievers/         # BaseVectorStoreRetriever (infrastructure only)
-        callbacks/          # WebSocket callback handler
-      consumers/            # Django Channels WebSocket consumer
-      conversation/         # ConversationManager
-      agentic_execution/    # AgenticExecution Django models, views, tasks
-      views.py
-      urls.py
-      serializers/
-      tasks.py
-      admin.py
-  frontend/                 # React 18 + TypeScript chat UI
-  plugins/
-    agentcore-common/       # Pure Python interfaces (PyPI: agentcore-common)
-      agents/               # BaseAgent, BaseAgentBuilder, ConfigType
-      tools/                # BaseTool, BaseFunctionTool, BaseLLMTool,
-                            # BaseFileTool, BaseAgentTool
-      agentic_execution/    # BaseAgenticExecutionDefinition, ExecutionResult,
-                            # ToolScratchpad, BaseExecutionValidator
-      registries/           # LanguageModelProvider, BaseLanguageModelRegistry,
-                            # EmbeddingProvider, BaseEmbeddingProviderRegistry
-      repositories/         # BaseRepository[T], BaseUserRepository,
-                            # BaseConversationRepository, BaseMessageRepository,
-                            # BaseDataSetRepository, BaseAgentRepository
-      injectors/            # BaseInjector
-      retrievers/           # BaseVectorStoreRetriever[T]
-      structures/           # TextContent, LLMFile, BaseContent
-      callbacks/            # ConversationCallbackHandler
-      config/               # AgentConfig, LLMConfig, tool configs
-      errors/               # BaseAgentFriendlyError
-    agentcore-model-openai/
-    agentcore-model-anthropic/
-    agentcore-model-google/
-    agentcore-model-mistral/
-    agentcore-model-ollama/
-    agentcore-model-azureopenai/
-```
-
-**What agentcore provides out of the box:**
-- Conversation management (create, respond, history)
-- Agent registration and execution (global registry, `AppConfig.ready()` pattern)
-- `ToolCallingAgent` — generic tool-calling agent, no built-in tools (plugins register tools)
-- WebSocket streaming of agent responses
-- Agentic execution engine (autonomous multi-step tasks with retries/validators)
-- LLM provider plugins (OpenAI, Anthropic, Google, Mistral, Ollama, Azure)
-- Memory strategies (persistent, limited, summary)
-- React chat UI
-- REST API + Django admin
+**`enthusiast`** — the e-commerce vertical. A Django app package installed into agentcore via `INSTALLED_APPS`. Has no `manage.py` of its own.
 
 ---
 
-### enthusiast repo (e-commerce vertical)
+## What agentcore Owns
 
-enthusiast is a **Django app package** installed into agentcore. It has no `manage.py` — agentcore is the project that runs it.
+agentcore is a pure AI agent framework. It knows nothing about products, documents, or e-commerce. It provides:
 
-```
-enthusiast/
-  plugins/
-    enthusiast-common/      # Thin e-commerce interfaces (PyPI: enthusiast-common)
-                            # NO dependency on agentcore-common
-      structures/           # ProductDetails, DocumentDetails, Address,
-                            # DocumentChunkDetails, ProductUpdateDetails
-      interfaces/           # ProductSourcePlugin, DocumentSourcePlugin,
-                            # ECommerceIntegrationPlugin
-      connectors/           # ECommercePlatformConnector (ABC)
-      retrievers/           # BaseProductRetriever
-    enthusiast/             # Django app (PyPI: enthusiast)
-      models/               # Product, ProductChunk, Document, DocumentChunk
-                            # all with FK to agentcore.DataSet
-      apps.py               # AppConfig.ready() registers builder, tools, integrations
-      sync/                 # Source synchronization engine (products + documents)
-      integrations/         # MedusaIntegration, ShopifyIntegration handlers
-      injector.py           # EnthusiastInjector — implements get_retriever(type)
-      builder.py            # EnthusiastAgentBuilder (extends BaseAgentBuilder)
-      repositories.py       # Django ORM implementations for e-commerce models
-      retrievers/           # ProductRetriever, DocumentRetriever (pgvector)
-      tools/                # ProductSearchTool, DocumentSearchTool, OrderManagementTool
-      admin.py
-      urls.py
-      serializers/
-    enthusiast-agent-product-search/
-    enthusiast-agent-catalog-enrichment/
-    enthusiast-agent-order-intake/
-    enthusiast-agent-user-manual-search/
-    enthusiast-agent-invoice-scanning/
-    enthusiast-source-medusa/
-    enthusiast-source-shopify/
-    enthusiast-source-woocommerce/
-    enthusiast-source-shopware/
-    enthusiast-source-solidus/
-    enthusiast-source-wordpress/
-    enthusiast-source-sanitycms/
-    enthusiast-source-sample/
-```
+- **DataSet** — the central tenant concept. Holds LLM config, embedding config, and is the anchor all plugin models reference via FK. Replaces the current Workspace.
+- **Conversation / Message / Agent** — core conversation management
+- **AgenticExecution** — autonomous multi-step task execution with retries
+- **ToolCallingAgent** — a generic tool-calling agent shipped out of the box. No built-in tools — plugins register tools via settings.
+- **Integration** — a single external system connection per DataSet (e.g. Medusa, Shopify). Type and config defined by the plugin. Configured in the UI.
+- **LLM provider plugins** — OpenAI, Anthropic, Google, Mistral, Ollama, Azure
+- **WebSocket streaming, memory strategies, React chat UI, REST API**
 
 ---
 
-### Package Dependency Graph
+## What enthusiast Owns
 
-```
-agentcore-common          (langchain, pydantic — no project deps)
-      ↑                              ↑
-agentcore (Django app)         agentcore-model-*
-
-
-enthusiast-common         (no dependency on agentcore-common — fully independent)
-      ↑                              ↑               ↑
-enthusiast (Django app)    enthusiast-agent-*    enthusiast-source-*
-      ↑                         ↑    ↑
-   agentcore              agentcore-common
-                          enthusiast-common
-                          enthusiast          # domain models (Product, Document, retrievers)
-```
+enthusiast is the e-commerce vertical. It adds:
 
-Key rule: **`enthusiast-common` has zero dependency on `agentcore-common`**. E-commerce interfaces are fully independent of the AI agent framework.
+- **Product / Document models** — with FK to `agentcore.DataSet`
+- **Sync engine** — pulls products and documents from Medusa, Shopify, etc. and stores embeddings
+- **E-commerce tools** — ProductSearchTool, DocumentSearchTool, OrderManagementTool
+- **AgentBuilder + Injector** — wires up e-commerce retrievers and tools for the agent
+- **Source plugins** — `enthusiast-source-medusa`, `enthusiast-source-shopify`, etc.
+- **Agent plugins** — ProductSearchAgent, CatalogEnrichmentAgent, OrderIntakeAgent, etc.
 
-**`BaseProductRetriever` inheritance:** `enthusiast-common` declares `BaseProductRetriever(ABC)` with no dependency on agentcore-common. The concrete `ProductRetriever` in `enthusiast` uses multiple inheritance — `ProductRetriever(BaseProductRetriever, BaseVectorStoreRetriever)` — picking up the agentcore-common interface at the Django app level where both packages are available.
+agentcore knows nothing about products or documents. That's enthusiast's domain.
 
 ---
 
-### Plugin Registration (Django settings)
+## Plugin System
 
-agentcore `settings.py` defines base config. Users extend via `settings_override.py`:
+Plugins register with agentcore via `settings_override.py`. One mechanism, no magic:
 
 ```python
-# agentcore/server/settings.py
-INSTALLED_APPS = [
-    'agentcore',
-    # vertical plugins added via settings_override
-]
-
-AGENTCORE_LANGUAGE_MODEL_PLUGINS = [
-    'agentcore_model_openai.OpenAILanguageModelProvider',
-    'agentcore_model_anthropic.AnthropicLanguageModelProvider',
-    'agentcore_model_google.GoogleLanguageModelProvider',
-    'agentcore_model_mistral.MistralLanguageModelProvider',
-    'agentcore_model_ollama.OllamaLanguageModelProvider',
-    'agentcore_model_azureopenai.AzureOpenAILanguageModelProvider',
-]
-AGENTCORE_EMBEDDING_PLUGINS = []
-AGENTCORE_AGENT_PLUGINS = []
-AGENTCORE_TOOL_PLUGINS = []
-AGENTCORE_BUILDER_PLUGINS = []
-AGENTCORE_INTEGRATION_PLUGINS = []
-
-# agentcore/server/settings_override.py (user-configured, env-based)
+# settings_override.py
 INSTALLED_APPS += ['enthusiast']
 
-AGENTCORE_AGENT_PLUGINS = [
-    'enthusiast_agent_product_search.ProductSearchAgent',
-    'enthusiast_agent_catalog_enrichment.CatalogEnrichmentAgent',
-    'enthusiast_agent_order_intake.OrderIntakeAgent',
-    'enthusiast_agent_user_manual_search.UserManualSearchAgent',
-    'enthusiast_agent_invoice_scanning.InvoiceScanningAgent',
-]
-AGENTCORE_TOOL_PLUGINS = [
-    'enthusiast.tools.ProductSearchTool',
-    'enthusiast.tools.DocumentSearchTool',
-    'enthusiast.tools.OrderManagementTool',
-]
-AGENTCORE_BUILDER_PLUGINS = [
-    'enthusiast.builder.EnthusiastAgentBuilder',
-]
-AGENTCORE_INTEGRATION_PLUGINS = [
-    'enthusiast.integrations.MedusaIntegration',
-    'enthusiast.integrations.ShopifyIntegration',
-]
+AGENTCORE_BUILDER_PLUGINS  = ['enthusiast.builder.EnthusiastAgentBuilder']
+AGENTCORE_TOOL_PLUGINS     = ['enthusiast.tools.ProductSearchTool', ...]
+AGENTCORE_AGENT_PLUGINS    = ['enthusiast_agent_product_search.ProductSearchAgent', ...]
+AGENTCORE_INTEGRATION_PLUGINS = ['enthusiast.integrations.MedusaIntegration', ...]
 ```
 
-Each vertical plugin follows the same pattern — never modifies agentcore settings directly.
+agentcore reads these lists at startup and loads the declared classes. No `AppConfig.ready()` registration calls.
 
 ---
 
-### How enthusiast extends agentcore
+## Integration Model
 
-enthusiast is registered entirely through `settings_override.py`. agentcore reads the settings lists at startup and loads the declared classes — no runtime `register()` calls, no `AppConfig.ready()` magic.
+Each DataSet has one Integration — a connection to an external system. The plugin defines the Integration type by extending `BaseIntegration`:
 
 ```python
-# enthusiast/injector.py
-from agentcore_common.injectors import BaseInjector
-
-class EnthusiastInjector(BaseInjector):
-    def get_retriever(self, repository_type: str):
-        if repository_type == 'products':
-            return self._product_retriever
-        elif repository_type == 'documents':
-            return self._document_retriever
-        raise ValueError(f"No retriever for repository type: {repository_type}")
-
-# enthusiast/builder.py
-from agentcore_common.agents import BaseAgentBuilder
-
-class EnthusiastAgentBuilder(BaseAgentBuilder):
-    def _build_injector(self) -> EnthusiastInjector:
-        # reads dataset.embedding_provider, dataset.embedding_model from DataSet
-        # builds product + document retrievers, passes to EnthusiastInjector
-        ...
-
-    def _build_tools(self) -> list[BaseTool]:
-        # instantiates tools from AGENTCORE_TOOL_PLUGINS
-        ...
-```
-
-**Repositories are code-defined, not UI-created.** When enthusiast is installed, every DataSet automatically has product and document retrieval capabilities — no "Add Repository" step in UI. The admin sees this reflected in "Agent Capabilities", not in a repository list.
-
-Enthusiast's models (`Product`, `Document`, `ProductChunk`, `DocumentChunk`) all have a direct FK to `DataSet` from agentcore. No OneToOne extension of DataSet is needed — all configuration lives in `DataSet` itself (LLM config, embedding config) or in enthusiast's own `Integration` records.
-
----
-
-## What Moves Where
-
-### From enthusiast → agentcore
-| Current location | New location |
-|---|---|
-| `plugins/enthusiast-common/` (generic parts) | `plugins/agentcore-common/` |
-| `plugins/enthusiast-model-*` | `plugins/agentcore-model-*` |
-| `server/agent/core/` | `server/agentcore/core/` |
-| `server/agent/` (Conversation, Message, Agent models) | `server/agentcore/models/` |
-| `server/agent/conversation/` | `server/agentcore/conversation/` |
-| `server/agent/agentic_execution/` (Django layer) | `server/agentcore/agentic_execution/` |
-| `server/agent/consumers/` | `server/agentcore/consumers/` |
-| `server/account/` | `server/account/` (stays, generic auth) |
-| `frontend/` | `agentcore/frontend/` |
-| `server/pecl/` (project config) | `agentcore/server/pecl/` |
-
-### New in agentcore (greenfield)
-| What | Notes |
-|---|---|
-| `agentcore/models/dataset.py` | `DataSet` model — replaces `Workspace`, holds LLM + embedding config |
-| `agentcore/models/integration.py` | `Integration` model — generic external system connector, type defined by plugin |
-| `agentcore/registry/` | Loads plugin classes from settings lists at startup (`AGENTCORE_*_PLUGINS`) |
-| `agentcore/agents/tool_calling.py` | `ToolCallingAgent` — generic tool-calling agent, no built-in tools |
-
-### Stays in enthusiast
-| Current location | Notes |
-|---|---|
-| `plugins/enthusiast-common/` (e-commerce parts) | Becomes thin `enthusiast-common` |
-| `plugins/enthusiast-agent-*` | All e-commerce agents |
-| `plugins/enthusiast-source-*` | All source plugins |
-| `server/catalog/` | Moves into `plugins/enthusiast/` (sync engine only, no DataSet) |
-| `server/sync/` | Moves into `plugins/enthusiast/sync/` |
-
-### Renamed
-| Old name | New name |
-|---|---|
-| `enthusiast-model-openai` | `agentcore-model-openai` |
-| `enthusiast-model-anthropic` | `agentcore-model-anthropic` |
-| `enthusiast-model-google` | `agentcore-model-google` |
-| `enthusiast-model-mistral` | `agentcore-model-mistral` |
-| `enthusiast-model-ollama` | `agentcore-model-ollama` |
-| `enthusiast-model-azureopenai` | `agentcore-model-azureopenai` |
-| `enthusiast_common.*` (generic imports) | `agentcore_common.*` |
-
----
-
-## Migration Strategy
-
-### Phase 1 — Build agentcore (green field, new repo)
-
-1. Create `github.com/upsidelab/agentcore`
-2. Copy and refactor:
-   - `enthusiast-common` → `agentcore-common` (strip all e-commerce types)
-   - `enthusiast-model-*` → `agentcore-model-*` (rename packages + imports)
-   - `server/agent/` → `agentcore/server/agentcore/` (Django app)
-   - `server/account/` → agentcore (generic auth)
-   - `server/pecl/` → agentcore project config
-   - `frontend/` → agentcore frontend
-3. agentcore runs standalone, all existing tests pass
-4. Publish `agentcore-common` and `agentcore` to PyPI (alpha)
-
-### Phase 2 — Migrate enthusiast (branch on enthusiast repo)
-
-1. Create branch `feature/agentcore-migration` on enthusiast
-2. Remove from enthusiast:
-   - `enthusiast-common` generic parts
-   - All `enthusiast-model-*` packages
-   - `server/agent/core/` (builder, injector, registries, memory)
-   - `server/agent/` (Conversation, Message, Agent Django models)
-   - `server/account/`
-   - `frontend/`
-3. Thin `enthusiast-common`: keep only e-commerce interfaces
-4. Update all imports: `enthusiast_common.*` → `agentcore_common.*`
-5. Add `agentcore` as dependency in `pyproject.toml`
-6. Implement `EnthusiastInjector`, `EnthusiastAgentBuilder` extending agentcore bases
-7. End-to-end tests: agentcore + enthusiast plugin working together
-8. Merge branch
-
-### Phase 3 — Release
-
-1. Publish `enthusiast-common` and `enthusiast` to PyPI
-2. `docker-compose.yml` in agentcore repo with enthusiast pre-installed as reference setup
-3. Update documentation
-
----
-
-## Data Model (resolved)
-
-`DataSet` replaces `Workspace` as the central tenant model and moves to agentcore. It is fully generic — no e-commerce concepts. Plugins do **not** extend DataSet via OneToOne — all shared configuration (LLM + embedding) lives directly on `DataSet`. Plugin models (e.g. `Product`, `Document`) reference `DataSet` via a plain FK.
-
-There is no `Repository` model in agentcore. Repositories are code-defined by plugins — installed automatically when a plugin is added to `INSTALLED_APPS`, not created through the UI.
+class MedusaIntegration(BaseIntegration):
+    type = 'medusa'
+    label = 'Medusa'
 
-```python
-# agentcore — all generic, no e-commerce concepts
-
-class DataSet(models.Model):
-    name = CharField()
-    owner = FK(User)
-    created_at = DateTimeField()
-    # LLM config — selected per DataSet in UI, credentials in env vars
-    llm_provider = CharField()
-    llm_model = CharField()
-    # Embedding config — agentcore stores these, plugins read and use them
-    embedding_provider = CharField()
-    embedding_model = CharField()
-    embedding_dimensions = IntegerField()
-    chunk_size = IntegerField()
-    chunk_overlap = IntegerField()
-
-class Integration(models.Model):
-    """External system connection (e.g. Medusa, Shopify). One per DataSet."""
-    dataset = OneToOneField(DataSet, on_delete=CASCADE)
-    type = CharField()       # e.g. 'medusa', 'shopify' — registered by plugin
-    config = JSONField()     # URLs, non-sensitive config — schema defined by plugin
-
-class Agent(models.Model):
-    dataset = FK(DataSet)
-
-class Conversation(models.Model):
-    dataset = FK(DataSet)
-```
-
-**Credential separation:** Global credentials shared across all DataSets (e.g. `OPENAI_API_KEY`) go to environment variables. Per-DataSet credentials (e.g. Medusa API key — each DataSet is a different store) go into `Integration.config` in the database, since there's no sensible way to put per-DataSet secrets in a flat env var namespace.
-
-```python
-# enthusiast — e-commerce models reference DataSet directly
-class Product(models.Model):
-    dataset = FK("agentcore.DataSet")
-    ...
-
-class Document(models.Model):
-    dataset = FK("agentcore.DataSet")
-    ...
-```
-
-agentcore has **no knowledge** of what `type` means for Integration — it is a black box. The plugin declares a `config_schema` class attribute (JSON Schema) on its integration class; agentcore reads it from `AGENTCORE_INTEGRATION_PLUGINS` at startup and renders a generic config form.
-
-**BaseInjector (agentcore-common) — generic retriever access:**
-```python
-class BaseInjector(ABC):
-    @abstractmethod
-    def get_retriever(self, repository_type: str) -> BaseVectorStoreRetriever:
-        pass
-
-    @property
-    @abstractmethod
-    def chat_history(self) -> BaseChatMessageHistory:
-        pass
-
-    @property
-    @abstractmethod
-    def tool_scratchpad(self) -> ToolScratchpad:
-        pass
+    def get_config_schema(self): ...   # fields for the UI form
+    def test_connection(self, config): ...
+    def get_client(self, config): ...
 ```
 
-No hardcoded `product_retriever` or `document_retriever` — those are enthusiast concerns.
+agentcore renders a generic config form in the UI based on the schema the plugin provides. Integration credentials (e.g. Medusa API key) are stored per-DataSet in the database — not in env vars, because each DataSet connects to a different store.
 
-**EnthusiastInjector (enthusiast) — implements retriever lookup by type:**
-```python
-class EnthusiastInjector(BaseInjector):
-    def get_retriever(self, repository_type: str) -> BaseVectorStoreRetriever:
-        if repository_type == 'products':
-            return self._product_retriever
-        elif repository_type == 'documents':
-            return self._document_retriever
-        raise ValueError(f"No retriever for repository type: {repository_type}")
-```
+---
 
-**enthusiast tools use the generic interface:**
-```python
-class ProductSearchTool(BaseFunctionTool):
-    def run(self, query: str):
-        retriever = self._injector.get_retriever('products')
-        return retriever.search(query)
-```
+## Package Structure
 
-**Config cascade:**
-```
-[1] env vars          global credentials — OPENAI_API_KEY, ANTHROPIC_API_KEY
-                      (one per deployment, shared across all DataSets)
-[2] DataSet           llm_provider, llm_model,
-                      embedding_provider, embedding_model,
-                      embedding_dimensions, chunk_size, chunk_overlap
-[3] Integration       per-DataSet external system config — url, api_key
-                      (e.g. each DataSet has its own Medusa store + key)
-[4] Agent config      system_prompt, tools, memory strategy
 ```
+agentcore/
+  plugins/
+    agentcore-common/     # Pure Python ABCs — BaseAgent, BaseAgentBuilder,
+                          # BaseTool, BaseInjector, BaseVectorStoreRetriever,
+                          # BaseIntegration, etc.
+    agentcore-model-*/    # LLM provider plugins (renamed from enthusiast-model-*)
+  server/
+    agentcore/            # Django app
+    frontend/             # React UI
 
-All DataSet and Integration config is set in the UI — no settings file entries for these values.
-
-## Frontend Architecture
-
-agentcore's frontend provides a **complete, working UI without any plugin injection**.
-
-**agentcore frontend covers:**
-```
-Conversations     ← chat, history, WebSocket streaming
-DataSets          ← list, create, configure (LLM + embedding)
-  └── Integrations  ← add/configure external systems (generic — type + config form)
-Agent Capabilities  ← auto-discovered from registry (read-only, code-defined)
-Settings          ← LLM providers, embedding providers
+enthusiast/
+  plugins/
+    enthusiast-common/    # Pure Python e-commerce structs — ProductDetails,
+                          # DocumentDetails, BaseProductRetriever, etc.
+                          # Zero dependency on agentcore-common.
+    enthusiast/           # Django app — Product, Document, tools, builder, injector
+    enthusiast-agent-*/   # Agent plugins
+    enthusiast-source-*/  # Source sync plugins (Medusa, Shopify, etc.)
 ```
 
-**Repositories are not managed in the UI.** When enthusiast is installed, product and document retrieval capabilities appear automatically in "Agent Capabilities" — the admin does not create or configure them. Only `Integration` records (e.g. Medusa API connection) require UI configuration.
-
-**enthusiast is pure backend.** No `bundle.js`, no `window.agentcore.registerPlugin()`, no staticfiles frontend. The plugin injection system is not needed.
+Key rule: `enthusiast-common` has **zero dependency on `agentcore-common`**. E-commerce interfaces are fully independent of the AI agent framework.
 
 ---
 
-### Custom frontend (deferred, consult with Filip)
+## Migration Plan
 
-If a team wants a richer UI beyond what agentcore's generic views provide — e.g. a full product catalog grid with images and filters, or custom tool output renderers that show `<ProductCard>` instead of JSON in the chat — that's a separate decision.
+### Phase 1 — Build agentcore (new repo, green field)
+- Extract `enthusiast-common` generic parts → `agentcore-common`
+- Rename `enthusiast-model-*` → `agentcore-model-*`
+- Move agent infrastructure (Conversation, Agent, AgenticExecution, ConversationManager) → agentcore Django app
+- Add DataSet model (replaces Workspace), Integration model
+- agentcore runs standalone with a working chat UI
 
-**Before building any custom frontend, schedule a meeting with Filip (frontend developer).** Topics:
-- Is agentcore's generic UI sufficient for the e-commerce use case, or do we need a custom Catalog page?
-- Chat UI library — is there something worth adopting (e.g. assistant-ui)?
-- If custom frontend is needed: separate repo, NPM packages, or something else?
-- Tool output renderers — do we need them, and how should they work?
+### Phase 2 — Migrate enthusiast (branch on enthusiast repo)
+- Remove everything that moved to agentcore
+- Thin `enthusiast-common` to e-commerce structs only
+- Implement `EnthusiastAgentBuilder` and `EnthusiastInjector` extending agentcore-common bases
+- Product / Document models reference `agentcore.DataSet` via FK
+- End-to-end: agentcore + enthusiast plugin working together
 
-No decisions locked in here.
+### Phase 3 — Release
+- Publish packages to PyPI
+- Reference `docker-compose.yml` with enthusiast pre-installed
+- "Build your own vertical" developer guide
 
 ---
 
 ## Open Questions
 
 - **Final name for agentcore** — placeholder only, needs branding discussion
-- **PyPI namespace** — check `agentcore` availability before publishing
-- **Versioning strategy** — agentcore and enthusiast version independently
-- **Integration config schema** — how does agentcore know what fields to show when configuring a plugin-defined Integration type? Recommendation: plugin declares a JSON Schema on its integration class (class attribute), agentcore reads it from `AGENTCORE_INTEGRATION_PLUGINS` and renders a generic form (e.g. via `react-jsonschema-form`). Same pattern as Airbyte connector config. Needs confirmation before building the Integration configuration UI.
-- **Custom frontend** — agentcore's generic UI covers DataSet/Integration management and a read-only Agent Capabilities view. Whether enthusiast needs a richer Catalog page (products grid, document browser) or custom chat tool renderers is deferred. Consult with Filip before any frontend work begins.
-
----
-
-## Plugin Developer Documentation (needed before public release)
-
-Before agentcore can be used by third parties, we need a "Build your own vertical" guide. enthusiast is the reference implementation, but someone building a healthcare or logistics plugin shouldn't need to read its source code to understand what to implement.
-
-The guide should cover:
-
-### What agentcore exposes (the extension points)
-
-**Must implement** — these are the two classes every vertical plugin must provide:
-
-| Class | Where | What to implement |
-|---|---|---|
-| `BaseInjector` | `agentcore-common` | `get_retriever(type)`, `chat_history`, `tool_scratchpad` |
-| `BaseAgentBuilder` | `agentcore-common` | `_build_injector()`, `_build_llm_registry()`, `_build_tools()`, `_build_agent()` |
-
-`BaseConversationRepository`, `BaseDataSetRepository`, and all other repository bases are implemented by agentcore itself in `agentcore/core/repositories.py`. Plugins use them — they do not re-implement them.
-
-**Can implement** — optional extension points that unlock additional capabilities:
-
-| Class | What it adds |
-|---|---|
-| `BaseAgent` subclass | Custom agent with domain-specific `get_answer()` logic |
-| `BaseFunctionTool` | A simple tool the agent can call (e.g. `lookup_patient_record`) |
-| `BaseLLMTool` | A tool that itself calls an LLM (e.g. summariser, classifier) |
-| `BaseAgentTool` | A tool that spawns a sub-agent |
-| `BaseAgenticExecutionDefinition` | An autonomous multi-step task with retry/validation loop |
-| `LanguageModelProvider` | A new LLM provider (if not covered by agentcore-model-*) |
-
-**Django integration** — what the plugin's Django app must/can provide:
-
-| Item | Required? | Purpose |
-|---|---|---|
-| `INSTALLED_APPS` entry | required | Django discovers models, migrations, admin |
-| `AGENTCORE_BUILDER_PLUGINS` entry | required | agentcore loads your AgentBuilder |
-| `AGENTCORE_TOOL_PLUGINS` entries | required | agentcore loads your tools |
-| `AGENTCORE_AGENT_PLUGINS` entries | required | agentcore exposes your agents in the UI |
-| `AGENTCORE_INTEGRATION_PLUGINS` entries | optional | registers integration types with config schema |
-
-### What the guide should walk through step by step
-
-1. Create a new Python package (pip-installable)
-2. Define your domain models with FK to `agentcore.DataSet`
-3. Implement `BaseInjector.get_retriever(type)` for your data types
-4. Implement `BaseAgentBuilder` — wires up injector, reads DataSet embedding config, builds tools
-5. Write domain-specific tools using `self._injector.get_retriever('your_type')`
-6. Add entries to `settings_override.py`: `AGENTCORE_BUILDER_PLUGINS`, `AGENTCORE_TOOL_PLUGINS`, `AGENTCORE_AGENT_PLUGINS`
-7. Ship it: `pip install yourplugin` + add settings entries
-
-enthusiast itself serves as the living reference for all of the above.
-
----
-
-## Success Criteria
-
-- agentcore runs standalone with a working chat UI and conversation API, zero e-commerce imports
-- enthusiast installs into agentcore via `INSTALLED_APPS` and `pip install enthusiast`
-- A hypothetical healthcare plugin could follow the same pattern as enthusiast
-- All existing enthusiast tests pass after migration
-- No circular dependencies between packages
+- **PyPI namespace** — check `agentcore` availability
+- **Versioning** — agentcore and enthusiast version independently
+- **Frontend for rich plugin UI** — agentcore's generic UI covers DataSet, Integration, chat. Whether enthusiast needs a richer Catalog view (products grid, document browser) is deferred. Consult with Filip before any frontend work begins.

From da063c1402fb41c4e14492e8cf25b0e1af100afb Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 16:17:09 +0200
Subject: [PATCH 11/16] docs: add vertical plugin contract, repositories
 concept, honest frontend note

---
 specs/ai-agent-core-extraction.md | 105 ++++++++++++++++++++----------
 1 file changed, 70 insertions(+), 35 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 6c8ccc1b..11e78b79 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -24,68 +24,98 @@ Extract a standalone AI agent platform (**agentcore** — name TBD) that is comp
 
 ---
 
-## What agentcore Owns
+## agentcore as the Building Block
 
-agentcore is a pure AI agent framework. It knows nothing about products, documents, or e-commerce. It provides:
+agentcore is a pure AI agent framework — it knows nothing about products, documents, patients, or any other domain. It provides the infrastructure that all verticals share:
 
-- **DataSet** — the central tenant concept. Holds LLM config, embedding config, and is the anchor all plugin models reference via FK. Replaces the current Workspace.
+- **DataSet** — central tenant concept. Holds LLM config, embedding config. All plugin models anchor to it via FK. Replaces the current Workspace.
 - **Conversation / Message / Agent** — core conversation management
 - **AgenticExecution** — autonomous multi-step task execution with retries
-- **ToolCallingAgent** — a generic tool-calling agent shipped out of the box. No built-in tools — plugins register tools via settings.
-- **Integration** — a single external system connection per DataSet (e.g. Medusa, Shopify). Type and config defined by the plugin. Configured in the UI.
+- **ToolCallingAgent** — generic tool-calling agent. No built-in tools — plugins bring their own.
+- **Integration** — one external system connection per DataSet (type and config defined by the plugin, configured in the UI)
 - **LLM provider plugins** — OpenAI, Anthropic, Google, Mistral, Ollama, Azure
-- **WebSocket streaming, memory strategies, React chat UI, REST API**
+- **WebSocket streaming, memory strategies, REST API**
+
+A vertical plugin fills in everything domain-specific: what data to index, how to search it, what tools to expose to the agent.
 
 ---
 
-## What enthusiast Owns
+## How a Vertical Plugin Works
 
-enthusiast is the e-commerce vertical. It adds:
+A plugin is responsible for three things:
 
-- **Product / Document models** — with FK to `agentcore.DataSet`
-- **Sync engine** — pulls products and documents from Medusa, Shopify, etc. and stores embeddings
-- **E-commerce tools** — ProductSearchTool, DocumentSearchTool, OrderManagementTool
-- **AgentBuilder + Injector** — wires up e-commerce retrievers and tools for the agent
-- **Source plugins** — `enthusiast-source-medusa`, `enthusiast-source-shopify`, etc.
-- **Agent plugins** — ProductSearchAgent, CatalogEnrichmentAgent, OrderIntakeAgent, etc.
+**1. Repositories — the domain knowledge**
 
-agentcore knows nothing about products or documents. That's enthusiast's domain.
+The plugin defines what data sources exist and how to search them. These are not models in agentcore — they are defined entirely by the plugin. Examples:
 
----
+| Vertical | Repositories |
+|---|---|
+| enthusiast (e-commerce) | Products, Documents |
+| healthcare | Patient records, Clinical notes |
+| logistics | Shipments, Warehouses |
 
-## Plugin System
+The plugin owns the models (with FK to `agentcore.DataSet`), the sync logic, the embeddings, and the vector search. agentcore is unaware of any of this.
 
-Plugins register with agentcore via `settings_override.py`. One mechanism, no magic:
+**2. Integration — the external system**
+
+Each DataSet connects to one external system. The plugin defines the Integration type:
 
 ```python
-# settings_override.py
-INSTALLED_APPS += ['enthusiast']
+class MedusaIntegration(BaseIntegration):
+    type = 'medusa'
+    label = 'Medusa'
 
-AGENTCORE_BUILDER_PLUGINS  = ['enthusiast.builder.EnthusiastAgentBuilder']
-AGENTCORE_TOOL_PLUGINS     = ['enthusiast.tools.ProductSearchTool', ...]
-AGENTCORE_AGENT_PLUGINS    = ['enthusiast_agent_product_search.ProductSearchAgent', ...]
-AGENTCORE_INTEGRATION_PLUGINS = ['enthusiast.integrations.MedusaIntegration', ...]
+    def get_config_schema(self): ...   # drives the UI config form
+    def test_connection(self, config): ...
+    def get_client(self, config): ...
 ```
 
-agentcore reads these lists at startup and loads the declared classes. No `AppConfig.ready()` registration calls.
+Integration config (URL, API key) is stored per-DataSet in the database — not in env vars, because each DataSet connects to a different store instance.
+
+**3. AgentBuilder + Tools — how the agent is assembled**
+
+The plugin provides a builder that wires up its repositories and tools into an agent that agentcore can run:
+
+```python
+class EnthusiastAgentBuilder(BaseAgentBuilder):
+    def build(self, dataset, conversation):
+        # reads embedding config from dataset
+        # builds product + document retrievers
+        # instantiates injector and tools
+        # returns a ToolCallingAgent ready to answer questions
+        ...
+```
 
 ---
 
-## Integration Model
+## Plugin Registration
 
-Each DataSet has one Integration — a connection to an external system. The plugin defines the Integration type by extending `BaseIntegration`:
+Plugins register with agentcore via `settings_override.py`:
 
 ```python
-class MedusaIntegration(BaseIntegration):
-    type = 'medusa'
-    label = 'Medusa'
+# settings_override.py
+INSTALLED_APPS += ['enthusiast']
 
-    def get_config_schema(self): ...   # fields for the UI form
-    def test_connection(self, config): ...
-    def get_client(self, config): ...
+AGENTCORE_BUILDER_PLUGINS     = ['enthusiast.builder.EnthusiastAgentBuilder']
+AGENTCORE_TOOL_PLUGINS        = ['enthusiast.tools.ProductSearchTool', ...]
+AGENTCORE_AGENT_PLUGINS       = ['enthusiast_agent_product_search.ProductSearchAgent', ...]
+AGENTCORE_INTEGRATION_PLUGINS = ['enthusiast.integrations.MedusaIntegration', ...]
 ```
 
-agentcore renders a generic config form in the UI based on the schema the plugin provides. Integration credentials (e.g. Medusa API key) are stored per-DataSet in the database — not in env vars, because each DataSet connects to a different store.
+agentcore reads these lists at startup and loads the declared classes. One mechanism, no magic.
+
+---
+
+## What enthusiast Brings
+
+enthusiast is the reference implementation of a vertical plugin:
+
+- **Product / Document models** — with FK to `agentcore.DataSet`
+- **Sync engine** — pulls data from Medusa, Shopify, etc. and stores embeddings
+- **Tools** — ProductSearchTool, DocumentSearchTool, OrderManagementTool
+- **AgentBuilder + Injector** — wires up e-commerce retrievers and tools
+- **Source plugins** — `enthusiast-source-medusa`, `enthusiast-source-shopify`, etc.
+- **Agent plugins** — ProductSearchAgent, CatalogEnrichmentAgent, OrderIntakeAgent, etc.
 
 ---
 
@@ -116,6 +146,12 @@ Key rule: `enthusiast-common` has **zero dependency on `agentcore-common`**. E-c
 
 ---
 
+## Frontend
+
+> **Note:** At this stage there is no frontend plan beyond writing it manually. agentcore ships a React UI for chat, DataSet management, and Integration configuration. Any richer plugin-specific UI (e.g. a Catalog page for products and documents) requires manual frontend development — no injection mechanism exists. This is a known gap to address in a future iteration, ideally after a consultation with a frontend developer.
+
+---
+
 ## Migration Plan
 
 ### Phase 1 — Build agentcore (new repo, green field)
@@ -144,4 +180,3 @@ Key rule: `enthusiast-common` has **zero dependency on `agentcore-common`**. E-c
 - **Final name for agentcore** — placeholder only, needs branding discussion
 - **PyPI namespace** — check `agentcore` availability
 - **Versioning** — agentcore and enthusiast version independently
-- **Frontend for rich plugin UI** — agentcore's generic UI covers DataSet, Integration, chat. Whether enthusiast needs a richer Catalog view (products grid, document browser) is deferred. Consult with Filip before any frontend work begins.

From 2020f58a2f8c0e51c3149a66723c14aa6a321497 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 16:25:18 +0200
Subject: [PATCH 12/16] docs: add visual diagrams showing agentcore/enthusiast
 connection and runtime flow

---
 specs/ai-agent-core-extraction.md | 63 +++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 11e78b79..dada11d7 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -38,6 +38,69 @@ agentcore is a pure AI agent framework — it knows nothing about products, docu
 
 A vertical plugin fills in everything domain-specific: what data to index, how to search it, what tools to expose to the agent.
 
+```
+                        ┌─────────────────────────────────────────┐
+                        │               agentcore                 │
+                        │                                         │
+                        │  DataSet ◄──────────────── FK ◄──────┐  │
+                        │  Conversation                         │  │
+                        │  Agent                                │  │
+                        │  AgenticExecution                     │  │
+                        │  ToolCallingAgent ◄── uses tools ──┐  │  │
+                        │  Integration (1 per DataSet)        │  │  │
+                        │                                     │  │  │
+                        │  settings_override.py:              │  │  │
+                        │    AVAILABLE_AGENTS       ──────────┼──┼──┼──► loads agent classes
+                        │    AGENTCORE_TOOL_PLUGINS ──────────┘  │  │
+                        │    AGENTCORE_BUILDER_PLUGINS            │  │
+                        │    AGENTCORE_INTEGRATION_PLUGINS        │  │
+                        └─────────────────────────────────────────┘
+                                           ▲
+                                           │ INSTALLED_APPS += ['enthusiast']
+                                           │ + settings lists
+                                           │
+                        ┌─────────────────────────────────────────┐
+                        │               enthusiast                │
+                        │                                         │
+                        │  Product  ──────────────────── FK ──────┘
+                        │  Document ──────────────────── FK ──────┘
+                        │                                         │
+                        │  EnthusiastAgentBuilder                 │
+                        │    └─ builds: injector + tools          │
+                        │                                         │
+                        │  ProductSearchTool                      │
+                        │  DocumentSearchTool                     │
+                        │  OrderManagementTool                    │
+                        │                                         │
+                        │  MedusaIntegration                      │
+                        │  enthusiast-source-medusa (sync)        │
+                        └─────────────────────────────────────────┘
+```
+
+```
+User message
+    │
+    ▼
+ConversationManager (agentcore)
+    │  czyta AGENTCORE_BUILDER_PLUGINS z settings
+    │  ładuje EnthusiastAgentBuilder
+    ▼
+EnthusiastAgentBuilder (enthusiast)
+    │  czyta dataset.embedding_model
+    │  buduje ProductRetriever, DocumentRetriever
+    │  zwraca ToolCallingAgent z narzędziami
+    ▼
+ToolCallingAgent (agentcore)
+    │  LangChain tool-calling loop
+    │  wywołuje ProductSearchTool.run(query)
+    ▼
+ProductSearchTool (enthusiast)
+    │  vector search na ProductChunk w pgvector
+    │  zwraca wyniki
+    ▼
+LLM generuje odpowiedź → WebSocket → User
+```
+
 ---
 
 ## How a Vertical Plugin Works

From a585883f20a521a36397d6f797f0109152a1f39f Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 16:26:35 +0200
Subject: [PATCH 13/16] =?UTF-8?q?docs:=20fix=20diagram=20=E2=80=94=20Engli?=
 =?UTF-8?q?sh=20only,=20fix=20ASCII=20alignment?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 specs/ai-agent-core-extraction.md | 91 ++++++++++++++++---------------
 1 file changed, 46 insertions(+), 45 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index dada11d7..daee694b 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -39,42 +39,43 @@ agentcore is a pure AI agent framework — it knows nothing about products, docu
 A vertical plugin fills in everything domain-specific: what data to index, how to search it, what tools to expose to the agent.
 
 ```
-                        ┌─────────────────────────────────────────┐
-                        │               agentcore                 │
-                        │                                         │
-                        │  DataSet ◄──────────────── FK ◄──────┐  │
-                        │  Conversation                         │  │
-                        │  Agent                                │  │
-                        │  AgenticExecution                     │  │
-                        │  ToolCallingAgent ◄── uses tools ──┐  │  │
-                        │  Integration (1 per DataSet)        │  │  │
-                        │                                     │  │  │
-                        │  settings_override.py:              │  │  │
-                        │    AVAILABLE_AGENTS       ──────────┼──┼──┼──► loads agent classes
-                        │    AGENTCORE_TOOL_PLUGINS ──────────┘  │  │
-                        │    AGENTCORE_BUILDER_PLUGINS            │  │
-                        │    AGENTCORE_INTEGRATION_PLUGINS        │  │
-                        └─────────────────────────────────────────┘
-                                           ▲
-                                           │ INSTALLED_APPS += ['enthusiast']
-                                           │ + settings lists
-                                           │
-                        ┌─────────────────────────────────────────┐
-                        │               enthusiast                │
-                        │                                         │
-                        │  Product  ──────────────────── FK ──────┘
-                        │  Document ──────────────────── FK ──────┘
-                        │                                         │
-                        │  EnthusiastAgentBuilder                 │
-                        │    └─ builds: injector + tools          │
-                        │                                         │
-                        │  ProductSearchTool                      │
-                        │  DocumentSearchTool                     │
-                        │  OrderManagementTool                    │
-                        │                                         │
-                        │  MedusaIntegration                      │
-                        │  enthusiast-source-medusa (sync)        │
-                        └─────────────────────────────────────────┘
+┌──────────────────────────────────────────┐
+│                agentcore                 │
+│                                          │
+│  DataSet         ◄── FK (from plugin) ◄──┼──┐
+│  Conversation                            │  │
+│  Agent                                   │  │
+│  AgenticExecution                        │  │
+│  ToolCallingAgent                        │  │
+│  Integration (1 per DataSet)             │  │
+│                                          │  │
+│  settings_override.py:                   │  │
+│    AVAILABLE_AGENTS            ──────────┼──┼──► loads classes
+│    AGENTCORE_TOOL_PLUGINS      ──────────┼──┼──► loads classes
+│    AGENTCORE_BUILDER_PLUGINS   ──────────┼──┼──► loads classes
+│    AGENTCORE_INTEGRATION_PLUGINS ────────┼──┼──► loads classes
+└──────────────────────────────────────────┘  │
+                    ▲                          │
+                    │  INSTALLED_APPS +=       │
+                    │  ['enthusiast']          │
+                    │  + settings lists        │
+                    │                          │
+┌──────────────────────────────────────────┐  │
+│               enthusiast                 │  │
+│                                          │  │
+│  Product  ──────────────────── FK ───────┼──┘
+│  Document ──────────────────── FK ───────┼──┘
+│                                          │
+│  EnthusiastAgentBuilder                  │
+│    builds: injector + tools              │
+│                                          │
+│  ProductSearchTool                       │
+│  DocumentSearchTool                      │
+│  OrderManagementTool                     │
+│                                          │
+│  MedusaIntegration                       │
+│  enthusiast-source-medusa (sync)         │
+└──────────────────────────────────────────┘
 ```
 
 ```
@@ -82,23 +83,23 @@ User message
     │
     ▼
 ConversationManager (agentcore)
-    │  czyta AGENTCORE_BUILDER_PLUGINS z settings
-    │  ładuje EnthusiastAgentBuilder
+    │  reads AGENTCORE_BUILDER_PLUGINS from settings
+    │  loads EnthusiastAgentBuilder
     ▼
 EnthusiastAgentBuilder (enthusiast)
-    │  czyta dataset.embedding_model
-    │  buduje ProductRetriever, DocumentRetriever
-    │  zwraca ToolCallingAgent z narzędziami
+    │  reads dataset.embedding_model
+    │  builds ProductRetriever, DocumentRetriever
+    │  returns ToolCallingAgent with tools
     ▼
 ToolCallingAgent (agentcore)
     │  LangChain tool-calling loop
-    │  wywołuje ProductSearchTool.run(query)
+    │  calls ProductSearchTool.run(query)
     ▼
 ProductSearchTool (enthusiast)
-    │  vector search na ProductChunk w pgvector
-    │  zwraca wyniki
+    │  vector search on ProductChunk via pgvector
+    │  returns results
     ▼
-LLM generuje odpowiedź → WebSocket → User
+LLM generates response → WebSocket → User
 ```
 
 ---

From 027dbe40c0c9f4142f604d14530080291d116855 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 16:56:41 +0200
Subject: [PATCH 14/16] docs: repositories are code-defined, shown read-only in
 UI, name TBD

---
 specs/ai-agent-core-extraction.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index daee694b..2317d347 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -120,6 +120,8 @@ The plugin defines what data sources exist and how to search them. These are not
 
 The plugin owns the models (with FK to `agentcore.DataSet`), the sync logic, the embeddings, and the vector search. agentcore is unaware of any of this.
 
+Repositories are **code-defined** — the admin does not create them in the UI. They exist automatically when the plugin is installed. The UI shows them read-only per DataSet so the admin can see what knowledge sources are available. The exact name for this UI section is TBD (deferred to the frontend discussion).
+
 **2. Integration — the external system**
 
 Each DataSet connects to one external system. The plugin defines the Integration type:

From 3269b96de0defc0d3790dd6cae213209972b7fc1 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 18:01:22 +0200
Subject: [PATCH 15/16] =?UTF-8?q?docs:=20Integration=20is=20FK=20not=20One?=
 =?UTF-8?q?ToOne=20=E2=80=94=20one=20per=20type=20per=20DataSet?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 specs/ai-agent-core-extraction.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 2317d347..2053cf5f 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -47,7 +47,7 @@ A vertical plugin fills in everything domain-specific: what data to index, how t
 │  Agent                                   │  │
 │  AgenticExecution                        │  │
 │  ToolCallingAgent                        │  │
-│  Integration (1 per DataSet)             │  │
+│  Integration (1 per type per DataSet)    │  │
 │                                          │  │
 │  settings_override.py:                   │  │
 │    AVAILABLE_AGENTS            ──────────┼──┼──► loads classes
@@ -124,7 +124,7 @@ Repositories are **code-defined** — the admin does not create them in the UI.
 
 **2. Integration — the external system**
 
-Each DataSet connects to one external system. The plugin defines the Integration type:
+A DataSet can have multiple integrations — one per type (e.g. Medusa + Shopify on the same DataSet). The plugin defines the Integration type:
 
 ```python
 class MedusaIntegration(BaseIntegration):

From e641320ca71786e2e165ad302dca4bc17dfa8d57 Mon Sep 17 00:00:00 2001
From: Dawid Mularczyk <dawid.mularczyk@onet.pl>
Date: Mon, 25 May 2026 18:06:44 +0200
Subject: [PATCH 16/16] docs: remove healthcare and logistics sections from AI
 agent core extraction

---
 specs/ai-agent-core-extraction.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/specs/ai-agent-core-extraction.md b/specs/ai-agent-core-extraction.md
index 2053cf5f..bb4e8227 100644
--- a/specs/ai-agent-core-extraction.md
+++ b/specs/ai-agent-core-extraction.md
@@ -115,8 +115,6 @@ The plugin defines what data sources exist and how to search them. These are not
 | Vertical | Repositories |
 |---|---|
 | enthusiast (e-commerce) | Products, Documents |
-| healthcare | Patient records, Clinical notes |
-| logistics | Shipments, Warehouses |
 
 The plugin owns the models (with FK to `agentcore.DataSet`), the sync logic, the embeddings, and the vector search. agentcore is unaware of any of this.