generated from coulomb/repo-seed
79 lines
5.4 KiB
Markdown
79 lines
5.4 KiB
Markdown
# markitect-main Scope Assessment For kontextual-engine
|
|
|
|
This assessment compares `/home/worsch/markitect-main` with the
|
|
`kontextual-engine` PRD, FRS, and intent documents.
|
|
|
|
## Summary
|
|
|
|
`markitect-main` contains the seed ideas for this repo, but they are mixed with
|
|
syntax tooling, UI, plugins, provider adapters, finance, issue tracking, and
|
|
project-specific utilities. `kontextual-engine` should migrate concepts and
|
|
tests selectively, then reimplement the runtime contract as a headless service
|
|
and programmatic API.
|
|
|
|
The most important inheritance is not old module structure. It is the concept
|
|
of a durable infospace-like knowledge environment with typed artifacts,
|
|
relationships, evaluation/composition workflows, and agent-operable context.
|
|
|
|
Detailed follow-up:
|
|
|
|
- `docs/markitect-tool-reuse-boundary.md`
|
|
- `docs/system-layer-extraction-inventory.md`
|
|
- `docs/system-layer-migration-backlog.md`
|
|
|
|
## In-Scope Candidates
|
|
|
|
| FRS area | markitect-main evidence | Recommendation |
|
|
| --- | --- | --- |
|
|
| FR-001 to FR-004 knowledge persistence | `infrastructure/repositories/`, `infrastructure/connection_manager.py`, `docs/WORKSPACE_AND_DATABASES.md`, migrations under `migrations/prompts/` | Reimplement a storage abstraction early. Reuse lessons from filesystem/SQLite split, but do not inherit workspace-local assumptions blindly. |
|
|
| FR-010 to FR-011 organization and relationships | `markitect/infospace/models.py`, `relation_models.py`, `relation_parser.py`, `graph_export.py`, examples under `examples/infospace-with-history/` | Migrate vocabulary and relationship tests where generic. Keep domain-specific example content as fixtures only. |
|
|
| FR-020 to FR-021 ingestion and normalization | `markitect/infospace/pipeline.py`, `entity_parser.py`, `classifier.py`, packaging/proxy docs, asset/document managers | Define ingestion interfaces that call external format tools. Markdown-specific parsing should route through `markitect-tool`. |
|
|
| FR-030 to FR-031 query and retrieval | `markitect/infospace/evaluate.py`, `evaluation_io.py`, `classification_io.py`, search plugin docs | Reimplement query as service/programmatic contract over persisted artifacts, metadata, and relationships. Avoid CLI/search-plugin coupling. |
|
|
| FR-040 to FR-041 transformation and composition | `markitect/infospace/composition.py`, `markitect/packaging/transclusion/`, `docs/composition-guide.md`, prompt dependency resolution roadmap | Keep composition/workflow ideas. Delegate document-level transforms to `markitect-tool`; engine tracks operation state and derived artifacts. |
|
|
| FR-050 to FR-052 workflow orchestration | `roadmap/prompt-dependency-resolution/`, `migrations/prompts/`, quality tables, run manifests, batch processor | Reimplement workflow model around explicit runs, steps, dependencies, inputs, outputs, and structured errors. |
|
|
| FR-060 to FR-061 AI interaction/context | `markitect/helper/knowledge.py`, `markitect/llm/`, evaluation/classification modules | Preserve agent use cases and context needs. Use `llm-connect` for providers and keep prompts/workflow state auditable. |
|
|
| FR-070 to FR-071 external tooling | `markitect/plugins/`, capabilities architecture, `pyproject.toml` file dependencies | Build adapter boundaries, not embedded capability code. First adapter should likely target `markitect-tool`. |
|
|
| FR-080 to FR-091 API and errors | `markitect/query_paradigms/`, production error handling, GraphQL docs | Define stable Python API first, then service API. Structured errors should be part of the first implementation slice. |
|
|
|
|
## Out Of Scope For kontextual-engine
|
|
|
|
- `markitect/core/`, `markitect/schema/`, `markitect/explode_variants/`, and
|
|
document transform primitives: move/reimplement in `markitect-tool`.
|
|
- `src/*.js`, `testdrive-jsui`, rendering plugins, static assets, browser
|
|
integration: not headless engine scope.
|
|
- `markitect/llm/*` provider implementations: use `llm-connect`.
|
|
- `markitect/finance/`, `issue_tracker/`, `profile/`, `tddai`, Gitea tooling,
|
|
and release-management helpers: unrelated product scope.
|
|
- Domain content from examples: useful as fixtures only when testing generic
|
|
engine behavior.
|
|
- GraphQL as a default interface: old docs are evidence of API needs, not a
|
|
commitment to GraphQL.
|
|
|
|
## Migration Principles
|
|
|
|
1. Start from the `kontextual-engine` PRD/FRS, not legacy package names.
|
|
2. Migrate tests and fixtures before code when behavior is clearly in scope.
|
|
3. Treat legacy code as reference material unless a module is already isolated
|
|
and aligned with the new runtime boundary.
|
|
4. Keep syntax, provider, UI, and domain layers outside this repo.
|
|
5. Make persistence and operation state explicit before adding AI workflows.
|
|
6. Prefer API/programmatic contracts first; CLI can be administrative later.
|
|
|
|
## Initial Architecture Target
|
|
|
|
```text
|
|
kontextual_engine/
|
|
artifacts/ artifact model, metadata, lifecycle operations
|
|
collections/ grouping, domain/collection membership, relationships
|
|
storage/ repository interfaces and backends
|
|
ingest/ format-agnostic ingestion adapters and normalization
|
|
query/ retrieval over content, metadata, and relationships
|
|
workflows/ runs, steps, dependencies, derived outputs
|
|
context/ agent context assembly and operation surfaces
|
|
integrations/ markitect-tool, llm-connect, storage adapters
|
|
api/ programmatic and service-facing contracts
|
|
```
|
|
|
|
The first implementation workplan should validate this shape against migrated
|
|
tests before committing to a framework or storage backend.
|