Merge commit 'e0fa223591'
This commit is contained in:
commit
e0d499d3d1
8 changed files with 428 additions and 46 deletions
117
shared/README.md
117
shared/README.md
|
|
@ -1,25 +1,43 @@
|
|||
# shared/ — framework-neutral core
|
||||
# portfolio-optimiser-commons
|
||||
|
||||
This directory holds the parts of the project that are **independent of any AI agent
|
||||
framework** and are meant to be **shared, unchanged, between both reference
|
||||
implementations**:
|
||||
Framework-neutral shared core of the portfolio-optimiser method: the normative specs, example bundles and golden fixtures vendored by both reference implementations.
|
||||
|
||||
- **this repository** — the method built on Microsoft Agent Framework (MAF);
|
||||
- **a sibling repository** (built later, in sequence) — the same method on the
|
||||
**Claude Agents SDK**.
|
||||
[](LICENSE)
|
||||
|
||||
Sharing one identical core is what makes the two implementations a *fair comparison*:
|
||||
both consume the same concept, the same example data, and the same expected outcomes,
|
||||
so the only thing that differs is the agent framework itself.
|
||||
This repository is the **source of truth** for everything in the portfolio-optimiser method
|
||||
that is **independent of any AI agent framework**. It holds no runnable code — only
|
||||
normative specifications, example data, and expected outcomes.
|
||||
|
||||
## Contents (growing)
|
||||
Two reference implementations consume it, unchanged, as a `git subtree` at `shared/`:
|
||||
|
||||
- [`CONCEPT.md`](CONCEPT.md) — the business concept, written for a non-specialist
|
||||
(e.g. a business developer at another company).
|
||||
- [`portfolio-optimiser`](https://git.fromaitochitta.com/open/portfolio-optimiser) — the
|
||||
method on **Microsoft Agent Framework (MAF)**;
|
||||
- [`portfolio-optimiser-claude`](https://git.fromaitochitta.com/open/portfolio-optimiser-claude)
|
||||
— the same method on the **Claude Agent SDK**.
|
||||
|
||||
Sharing one identical core is what makes the two implementations a *fair comparison*: both
|
||||
consume the same concept, the same example data, and the same expected outcomes, so the only
|
||||
thing that differs is the agent framework itself. The second implementation is built from the
|
||||
specifications alone, without reverse-engineering the reference code.
|
||||
|
||||
## Contents
|
||||
|
||||
- [`method-spec.md`](method-spec.md) — the **normative method specification**, framework-neutral
|
||||
(the prose never names a concrete agent toolkit — enforced by a guard test): the 8-step loop,
|
||||
the verdict JSON contract, the inbox/outbox folder contract, the promotion-gate semantics, the
|
||||
IR projection + golden suite as the only ground truth, and the budget/provenance requirements.
|
||||
- [`ingest-spec.md`](ingest-spec.md) — the **normative ingest specification**, framework-neutral
|
||||
(same guard rule): the deterministic ingest step that materializes real data sources as OKF
|
||||
bundles BEFORE the loop — the polymorphic manifest schema (file/CSV, SQL, HTTP as extension
|
||||
point), the credential-reference rule, the verdict-layer reservation, the ingest provenance
|
||||
frontmatter with an explicit timestamp, the index-generation requirement, and the
|
||||
golden-extraction format.
|
||||
- [`CONCEPT.md`](CONCEPT.md) — the business concept, written for a non-specialist (e.g. a
|
||||
business developer at another company). Written in Norwegian.
|
||||
- [`examples/bygg-energi-mikro/`](examples/bygg-energi-mikro/) — the first example knowledge
|
||||
bundle (OKF / LLM-wiki): one office building, one LED-retrofit measure, with a seed expert
|
||||
verdict encoding the realization gap and a golden-suite of expected validator outcomes. A
|
||||
small **dev fixture** for exercising the agentic loop; a realistic full-scale example comes later.
|
||||
verdict encoding the realization gap and a golden-suite of expected validator outcomes. A small
|
||||
**dev fixture** for exercising the agentic loop; a realistic full-scale example comes later.
|
||||
- [`examples/nav-golden-hierarchy/`](examples/nav-golden-hierarchy/) and
|
||||
[`examples/nav-golden-escape/`](examples/nav-golden-escape/) — the **nav-golden** fixture class:
|
||||
`bundle/` in, `expected-read-context.md` out, exercising the navigation contract (method-spec §3
|
||||
|
|
@ -33,45 +51,52 @@ so the only thing that differs is the agent framework itself.
|
|||
framework-neutral Agent Skill: a `SKILL.md` persona prompt (energy-advisor / M&V role + the
|
||||
realization-gap methodology the validator cannot compute) and a canonical
|
||||
`references/example-verdict.json`. Both reference implementations instantiate the reviewer from
|
||||
this one artifact; `shared/` stays pure data (each stack reads the JSON with its own loader).
|
||||
- [`method-spec.md`](method-spec.md) — the **normative method specification**, framework-neutral
|
||||
(the prose never names a concrete agent toolkit — enforced by a guard test): the 8-step loop,
|
||||
the verdict JSON contract, the inbox/outbox folder contract, the promotion-gate semantics, the
|
||||
IR projection + golden suite as the only ground truth, and the budget/provenance requirements.
|
||||
The sibling implementation is built from this spec alone, without reverse-engineering the
|
||||
reference code.
|
||||
- [`ingest-spec.md`](ingest-spec.md) — the **normative ingest specification**, framework-neutral
|
||||
(same guard rule as the method spec): the deterministic ingest step that materializes real
|
||||
data sources as OKF bundles BEFORE the loop — the polymorphic manifest schema (file/CSV, SQL,
|
||||
HTTP as extension point), the credential-reference rule, the verdict-layer reservation, the
|
||||
ingest provenance frontmatter with an explicit timestamp, the index-generation requirement,
|
||||
and the golden-extraction format.
|
||||
this one artifact; this repository stays pure data (each stack reads the JSON with its own loader).
|
||||
- [`docs/plan/`](docs/plan/) — the decision record: how each ruling in the specifications above was
|
||||
arrived at, including the ones that were later reversed. Working documents, not normative, and
|
||||
written in a mix of Norwegian and English.
|
||||
|
||||
## Rules
|
||||
## Vendoring this repository
|
||||
|
||||
- **Nothing in here may import or depend on a specific agent framework.** If it does,
|
||||
it does not belong in `shared/`.
|
||||
- **Repo layout (decision R1, realized 2026-07-03):** the shared core lives in its own
|
||||
repository, [`portfolio-optimiser-commons`](https://git.fromaitochitta.com/ktg/portfolio-optimiser-commons)
|
||||
— the **source of truth**. Each implementation repo consumes it as a **git subtree**
|
||||
at this unchanged `shared/` path (so tests and the `PORTFOLIO_SHARED_ROOT` default
|
||||
resolver are unaffected). Do not edit commons content anywhere else without syncing.
|
||||
This repository is **vendored, not installed** — there is no package to add. Each consuming
|
||||
repository carries it as a `git subtree` under `shared/`, so the specs and fixtures are present in
|
||||
a normal checkout with no extra tooling.
|
||||
|
||||
## Subtree sync (pull-only — run from the consuming repo's root)
|
||||
Register the remote once, from the consuming repository's root:
|
||||
|
||||
The remote is registered as `commons`
|
||||
(`ssh://git@git.fromaitochitta.com/ktg/portfolio-optimiser-commons.git`).
|
||||
```sh
|
||||
git remote add commons https://git.fromaitochitta.com/open/portfolio-optimiser-commons.git
|
||||
git subtree add --prefix=shared commons main --squash
|
||||
```
|
||||
|
||||
**All edits land in commons first** (clone it, commit, push there), then each
|
||||
consuming repo pulls them in:
|
||||
Then pull updates with:
|
||||
|
||||
```sh
|
||||
git subtree pull --prefix=shared commons main --squash
|
||||
```
|
||||
|
||||
**Never run `git subtree push` from a consuming repo.** Observed 2026-07-03: because
|
||||
this repo's history contains commits that create/delete the `shared/` prefix, the
|
||||
push re-split leaked the consumer's *entire* history into commons (cleaned up by
|
||||
force-push the same day). Pull-only keeps commons the clean source of truth.
|
||||
**Sync is pull-only. All edits land here first** — commit and push in this repository, then pull
|
||||
them into each consumer.
|
||||
|
||||
See the target picture for the full architecture: `docs/plan/2026-06-26-maalbilde-agentic-loop.md`.
|
||||
**Never run `git subtree push` from a consuming repository.** Observed 2026-07-03: because a
|
||||
consumer's history contains commits that create and delete the `shared/` prefix, the push re-split
|
||||
leaked the consumer's *entire* history into this repository (cleaned up by force-push the same
|
||||
day). Pull-only keeps this repository the clean source of truth.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- **Not a runnable system.** No pipeline, no CLI, no package. The specifications describe
|
||||
behaviour; the two implementation repositories provide it.
|
||||
- **No framework dependency.** Nothing here may import or depend on a specific agent framework.
|
||||
If it does, it does not belong in this repository — that is what "framework-neutral" buys, and a
|
||||
guard test in each consumer enforces it for the two normative specs.
|
||||
- **Not a general-purpose knowledge-format standard.** The bundle layout follows the upstream Open
|
||||
Knowledge Format where it applies; this repository does not seek to replace or extend it beyond
|
||||
what the method needs.
|
||||
- **Not a home for implementation decisions.** Anything true of only one of the two stacks belongs
|
||||
in that stack's repository, not here.
|
||||
- **No inbound patches through this forge.** See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE) © 2026 Kjell Tore Guttormsen
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue