coulomb/markitect-main
2
0
Fork 0
Code Issues 61 Pull Requests Actions Projects 12 Releases 1 Wiki Activity

feat(llm): add LLM integration module with OpenRouter and Claude Code adapters

Browse Source 
Implements markitect/llm/ package with concrete LLMAdapter implementations:
- OpenRouterAdapter: HTTP via urllib with retry/backoff on 429/5xx
- ClaudeCodeAdapter: subprocess-based Claude CLI with stdin piping
- Factory pattern: create_adapter("openrouter") or create_adapter("claude-code")
- API key resolution chain: constructor > env var > project-root key file
- 42 unit tests, 2 integration tests (gated on API key / CLI availability)

Also adds the infospace-with-history example with Wealth of Nations VSM
analysis pipeline, templates, schemas, source chapters, and processed
output for chapters 1-2. process_chapters.py now supports --provider
and --model flags for automatic LLM-driven processing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-02-11 01:17:58 +01:00
parent 360c3b1de2
commit fecc2fd4fa
82 changed files with 43767 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
examples/infospace-with-history/output/metrics/metrics-prompt.md Normal file
View File

@@ -0,0 +1,323 @@
# Assess Completeness & Consistency Metrics
You are a quality assurance analyst evaluating the completeness and
consistency of a growing information space that maps classical economics
to the Viable System Model.
## All Chapter Analyses
<!-- Source: book-1-chapter-01-analysis.md -->
# Chapter Analysis: Book I, Chapter 1 — Of the Division of Labour
## Chapter Summary
Smith opens *The Wealth of Nations* by identifying the division of labour as
the primary cause of improvement in the productive powers of labour. Using the
celebrated pin-factory example, he demonstrates that ten workers collaborating
under a division of labour can produce 48,000 pins per day, compared to fewer
than 20 each if working independently — a productivity gain of over 240-fold.
He attributes this gain to three mechanisms: increased dexterity through
specialisation, time saved by eliminating task-switching, and the invention
of labour-saving machinery stimulated by focused attention on single operations.
Smith extends the argument from the workshop to society at large, showing that
the separation of trades advances furthest in the most developed countries,
and that the resulting multiplication of production creates a "universal
opulence" reaching even the lowest social ranks. He illustrates this with the
day-labourer's woollen coat, whose production requires the co-operation of
thousands of workers across dozens of trades and multiple countries.
## Entities Extracted
| # | Entity | Type | Economic Domain | Description |
|---|--------|------|-----------------|-------------|
| 1 | Division of labour | Concept | Production | Separation of work into specialised tasks to increase productive power |
| 2 | Productive powers of labour | Concept | Production | Capacity of labour to produce output per worker per unit time |
| 3 | Dexterity of the workman | Concept | Production | Skill and speed acquired through repeated specialised operation |
| 4 | Saving of time | Concept | Production | Elimination of time lost in switching between tasks |
| 5 | Invention of machinery | Mechanism | Production | Development of labour-saving machines stimulated by specialisation |
| 6 | Separation of trades | Mechanism | Production | Emergence of distinct occupations as separate specialisations |
| 7 | The workman | Actor | Production | Individual labourer performing productive specialised work |
| 8 | The philosopher | Actor | General Theory | Observer-specialist who combines knowledge across fields |
| 9 | Universal opulence | Concept | Distribution | Material well-being extending to all social ranks |
| 10 | Exchange | Mechanism | Exchange | Trading surplus production for goods produced by others |
| 11 | Co-operation of labour | Mechanism | Production | Interdependent collaboration across trades and locations |
| 12 | Manufactures | Concept | Production | Sector of production transforming raw materials through specialised operations |
| 13 | Agriculture | Concept | Production | Sector of production with limited division of labour due to seasonal constraints |
**Total entities: 13**
## VSM Mappings
| Entity | VSM Concept | Strength | Key Rationale |
|--------|------------|----------|---------------|
| Division of labour | S1 (Operations) | Strong | Defines internal architecture of operational units |
| Division of labour | Recursion | Strong | Operates at multiple levels: workshop, trade, nation |
| Productive powers of labour | S1 (Operations) | Strong | Key performance indicator of S1 effectiveness |
| Dexterity of the workman | S1 (Operations) | Strong | Self-optimisation capacity of individual S1 elements |
| Saving of time | S2 (Coordination) | Moderate | Eliminates oscillation between work modes |
| Invention of machinery | S4 (Intelligence) | Strong | Adaptive innovation driven by focused observation |
| Separation of trades | S1 (Operations) | Strong | Differentiation of S1 into distinct operational units |
| The workman | S1 (Operations) | Strong | Fundamental S1 element at lowest recursion level |
| The philosopher | S4 (Intelligence) | Strong | Environmental scanning and cross-domain synthesis |
| Universal opulence | Viability | Moderate | Emergent outcome of a functioning viable system |
| Exchange | S2 (Coordination) | Strong | Primary coordination mechanism between S1 units |
| Co-operation of labour | S2 (Coordination) | Moderate | Observable result of effective S2 coordination |
| Manufactures | S1 (Operations) | Strong | Major S1 domain with high internal differentiation |
| Agriculture | S1 (Operations) | Strong | S1 domain constrained by environment in differentiation |
**Total mappings: 14** (some entities map to multiple VSM concepts)
## VSM Coverage
| System | Covered | Entities Mapped | Notes |
|--------|---------|-----------------|-------|
| S1 (Operations) | Yes | Division of labour, productive powers, dexterity, separation of trades, the workman, manufactures, agriculture | Dominant system — chapter focuses on operational structure |
| S2 (Coordination) | Yes | Saving of time, exchange, co-operation of labour | Present through coordination mechanisms |
| S3 (Control) | No | — | No entities map to internal regulation or resource allocation |
| S3* (Audit) | No | — | No entities map to monitoring or verification |
| S4 (Intelligence) | Yes | Invention of machinery, the philosopher | Innovation and environmental scanning |
| S5 (Policy) | No | — | No entities map to identity, policy, or purpose |
| Recursion | Yes | Division of labour | Multi-level operation explicitly noted |
| Variety | No | — | Not explicitly addressed in this chapter |
| Requisite Variety | No | — | Not explicitly addressed |
| Attenuation/Amplification | No | — | Not explicitly addressed |
| Algedonic Signals | No | — | Not explicitly addressed |
| Autonomy | No | — | Implicit but not directly discussed |
| Viability | Yes | Universal opulence | System-level outcome |
**Systems covered: S1, S2, S4 (3 of 5 primary systems)**
**Systems not covered: S3, S3*, S5**
**Key concepts covered: Recursion, Viability (2 of 7)**
## Gaps & Observations
### Uncovered Systems
- **S3 (Control)**: The chapter does not discuss regulation, resource allocation,
or governance of operational units. Smith's "invisible hand" and regulatory
structures appear in later chapters.
- **S3* (Audit)**: No monitoring or verification mechanisms are discussed.
- **S5 (Policy)**: The chapter does not address sovereign authority, economic
policy, or the purpose of the commonwealth. Smith's brief reference to
"a well-governed society" hints at S5 but does not develop it.
### Difficult Mappings
- **Saving of time** maps only moderately to S2 because it describes the
elimination of a coordination problem rather than a coordination mechanism
itself.
- **Universal opulence** maps to Viability rather than a specific system,
making it a systemic property rather than a structural element.
### Emerging Themes
1. **S1 dominance**: This chapter is overwhelmingly about operational structure.
As the opening chapter of the book, it establishes the productive foundation
before introducing regulatory and policy layers in subsequent chapters.
2. **Recursion as implicit structure**: Smith's analysis naturally operates at
multiple recursive levels (worker → workshop → trade → nation) even though
he does not use systems-theoretic language.
3. **Innovation feedback loop**: The connection between S1 (specialised workers)
and S4 (invention/philosophy) represents a key feedback loop in the viable
system: operational focus generates adaptive innovation.
### Suggestions for Enriching Coverage
- **S3 coverage** is likely to emerge in chapters on wages, profits, and market
regulation (Book I, Chapters 7-10).
- **S5 coverage** should appear in Book IV (political economy) and Book V
(sovereign revenue).
- **Variety and requisite variety** may emerge when Smith discusses market size
(Chapter 3) and the limitations of regulation.
- Later chapters on money (Chapter 4) and prices (Chapters 5-7) should
strengthen S2 coverage through the price mechanism.
### Cross-chapter Anticipations
Several entities from this chapter will likely recur and deepen in subsequent
chapters:
- **Division of labour** → Chapter 2 (its cause) and Chapter 3 (its limits)
- **Exchange** → Chapter 4 (money as medium of exchange)
- **Productive powers** → Chapters 5-7 (price theory as measure of output)
## VSM Framework Reference
---
id: vsm-framework
name: vsm_framework
artifact_type: content
description: Stafford Beer's Viable System Model reference for economic analysis
version: 1.0.0
---
# Stafford Beer's Viable System Model (VSM)
The Viable System Model (VSM) is a model of the organisational structure of any
autonomous system capable of producing itself. It was created by management
cybernetician Stafford Beer in his books *Brain of the Firm* (1972) and
*The Heart of Enterprise* (1979).
## Core Principle: Viability
A viable system is any system organised in such a way as to meet the demands
of surviving in a changing environment. One of the prime features of systems
that survive is that they are adaptable. The VSM expresses a model for a
viable system, which is an abstracted cybernetic description applicable to
any organisation that is a going concern.
## The Five Systems
### System 1 (S1) — Operations
The primary activities that produce the organisation's purpose. These are the
operational units that directly create value. Each operational element is itself
a viable system (the principle of recursion).
**In economic terms:** Productive enterprises, factories, farms, workshops,
individual labourers performing specialised tasks, merchant operations.
**Key properties:** Autonomy within constraints, self-organisation,
direct engagement with the environment.
### System 2 (S2) — Coordination
The information channels and bodies that allow the primary activities in
System 1 to communicate with each other and that allow System 3 to monitor
and coordinate activities. System 2 dampens oscillations and resolves
conflicts between operational units.
**In economic terms:** Market price mechanisms, trade customs, standard
weights and measures, commercial law, banking clearinghouses, trade guilds.
**Key properties:** Anti-oscillatory, dampening, scheduling, conflict
resolution, standardisation.
### System 3 (S3) — Control / Operational Management
The structures and controls that establish the rules, resources, rights,
and responsibilities of System 1 and provide an interface between Systems 1
and Systems 4/5. System 3 represents the day-to-day control of the
organisation. It optimises the internal environment.
**In economic terms:** Government regulation of trade, taxation policy, labour
laws, enforcement of contracts, the "invisible hand" as emergent internal
regulation, guilds and corporations governing members.
**Key properties:** Internal regulation, resource allocation, accountability,
synergy extraction, performance management.
### System 3* (S3*) — Audit / Monitoring
The audit and monitoring channel that allows System 3 to verify information
coming from System 1 through channels other than those provided by System 2.
System 3* provides sporadic, direct access to operational reality.
**In economic terms:** Market inspections, quality checks, auditing of accounts,
surprise investigations into trade practices, verification of weights and measures.
**Key properties:** Sporadic direct investigation, reality checking, bypassing
normal reporting channels.
### System 4 (S4) — Intelligence / Adaptation
The bodies and processes that look outward to the environment to monitor
how the organisation needs to adapt to remain viable. System 4 captures
all relevant information about the outside-and-then environment. It is
responsible for strategic responses.
**In economic terms:** Foreign intelligence about trade opportunities,
market research, new technology adoption, colonial exploration and trade
route development, understanding of foreign economic systems.
**Key properties:** Environmental scanning, future orientation, strategic
planning, modelling, research and development.
### System 5 (S5) — Policy / Identity
The policy-making body that balances demands from Systems 3 and 4 and defines
the identity, values, and purpose of the organisation. System 5 provides
closure to the whole system and represents its supreme authority.
**In economic terms:** Sovereign authority, constitutional principles governing
economic policy, national economic identity, the philosophical foundations
of economic systems (mercantilism vs. free trade), the overarching purpose
of the commonwealth.
**Key properties:** Identity, ethos, supreme command, policy closure,
balancing internal and external perspectives.
## Key Concepts
### Recursion
Every viable system contains and is contained in a viable system. The same
five-system structure recurs at every level of organisation. A workshop is
a viable system within a factory, which is a viable system within an
industry, which is a viable system within a national economy.
### Variety
A measure of the number of possible states of a system. The Law of Requisite
Variety (Ashby's Law) states that only variety can absorb variety. A
controller must have at least as much variety as the system it controls.
### Requisite Variety
The principle that for effective regulation, the variety of the regulator
must match the variety of the system being regulated. This is achieved
through variety attenuation (reducing the variety coming up from operations)
and variety amplification (increasing the variety of management's responses).
### Attenuation and Amplification
Variety engineering mechanisms. Attenuation reduces variety (e.g., reporting
summaries, statistical aggregation, standardisation). Amplification increases
variety (e.g., delegation, empowerment, decentralisation).
### Algedonic Signals
Emergency signals that bypass the normal management hierarchy to alert
higher systems of critical situations requiring immediate attention. Named
from the Greek words for pain (algos) and pleasure (hedone).
**In economic terms:** Market panics, famine signals, sudden price collapses,
trade embargoes, economic crises that demand immediate sovereign intervention.
### Autonomy
The degree of freedom granted to operational units (System 1) to self-organise
within constraints set by System 3. Beer argued that maximum autonomy
consistent with systemic cohesion yields maximum viability.
### Viability
The capacity of a system to maintain a separate existence and survive in a
changing environment. A viable system continuously adapts while maintaining
its identity.
## Instructions
1. Review all chapter analyses produced so far.
2. Compute the following completeness metrics:
- **VSM Concept Coverage**: Percentage of VSM concepts (S1, S2, S3, S3*, S4, S5,
plus key concepts like recursion, variety, requisite variety, autonomy,
viability, attenuation/amplification, algedonic signals) that have at
least one mapping. List covered and uncovered concepts.
- **Chapter Coverage**: Percentage of source chapters processed.
- **Entity Count**: Total number of distinct economic entities extracted.
- **Mapping Count**: Total number of entity-to-VSM mappings created.
3. Compute the following consistency metrics:
- **Terminology Consistency** (score 0.0-1.0): Whether the same economic
concept is named consistently across all documents. Flag inconsistencies.
- **Cross-reference Integrity** (score 0.0-1.0): Whether all entity references
in mappings point to existing entities. Flag broken references.
- **Schema Compliance** (percentage): Percentage of output documents that
contain all required sections per their respective schemas.
4. Produce a metrics report summarizing the current state of the information space.
## Output Format
Output a single markdown document with sections for each metric category:
Completeness Metrics, Consistency Metrics, and Recommendations.

152
examples/infospace-with-history/output/metrics/metrics-report.md Normal file
View File

@@ -0,0 +1,152 @@
# Infospace Metrics Report
**Report Date:** 2026-02-10
**Chapters Processed:** 1 of 35
---
## Completeness Metrics
### VSM Concept Coverage
**Coverage: 5 of 12 concepts (41.7%)**
| Concept | Covered | Mapping Count |
|---------|---------|---------------|
| S1 (Operations) | Yes | 8 |
| S2 (Coordination) | Yes | 3 |
| S3 (Control) | No | 0 |
| S3* (Audit) | No | 0 |
| S4 (Intelligence) | Yes | 2 |
| S5 (Policy) | No | 0 |
| Recursion | Yes | 1 |
| Variety | No | 0 |
| Requisite Variety | No | 0 |
| Attenuation/Amplification | No | 0 |
| Algedonic Signals | No | 0 |
| Viability | Yes | 1 |
| Autonomy | No | 0 |
**Uncovered concepts:** S3, S3*, S5, Variety, Requisite Variety,
Attenuation/Amplification, Algedonic Signals, Autonomy
**Assessment:** Coverage is concentrated on S1 (Operations), which is expected
for the opening chapter focused on production. The remaining concepts require
chapters addressing regulation (S3), policy (S5), and information management
(S3*, variety engineering).
### Chapter Coverage
**Coverage: 1 of 35 chapters (2.9%)**
| Book | Chapters Available | Chapters Processed |
|------|-------------------|-------------------|
| Introduction | 1 | 0 |
| Book I | 11 | 1 |
| Book II | 6 | 0 |
| Book III | 4 | 0 |
| Book IV | 10 | 0 |
| Book V | 3 | 0 |
### Entity Count
**Total distinct entities: 13**
| Economic Domain | Count |
|----------------|-------|
| Production | 10 |
| Distribution | 1 |
| Exchange | 1 |
| General Theory | 1 |
| Consumption | 0 |
| Accumulation | 0 |
| Regulation | 0 |
**Assessment:** Entity extraction is heavily skewed toward Production, reflecting
the chapter's content. Domains like Accumulation and Regulation will require
Book II and Book V chapters respectively.
### Mapping Count
**Total mappings: 14**
Mapping strength distribution:
- Strong: 11 (78.6%)
- Moderate: 3 (21.4%)
- Weak: 0 (0.0%)
---
## Consistency Metrics
### Terminology Consistency
**Score: 1.0**
With only one chapter processed, no cross-chapter terminology conflicts exist.
All entity names follow Smith's own terminology and the naming conventions
specified in the extraction rules. No synonyms detected.
**Flagged issues:** None
### Cross-reference Integrity
**Score: 1.0**
All entity references in mapping documents point to entities defined in the
entities output. No broken references detected.
**Flagged issues:** None
### Schema Compliance
**Compliance: 100%**
| Document Type | Total | Compliant | Non-compliant |
|--------------|-------|-----------|---------------|
| Entity documents | 13 | 13 | 0 |
| Mapping documents | 14 | 14 | 0 |
| Analysis documents | 1 | 1 | 0 |
All documents contain their required sections as defined by their respective
schemas.
---
## Recommendations
### Priority Actions
1. **Process remaining Book I chapters** to build S2 and S3 coverage through
price theory (Chapters 5-7) and wage/profit regulation (Chapters 8-10).
2. **Process Book IV chapters** for S5 (Policy) coverage, as these address
political economy systems (mercantilism, free trade).
3. **Process Book V chapters** for S3 (Control) coverage through sovereign
revenue and public administration.
### Coverage Gaps to Watch
- **Variety and requisite variety** are core VSM concepts that may not map
directly to Smith's vocabulary. Consider whether Smith's discussions of
market size, competition, and information asymmetry can be mapped to
variety management.
- **Algedonic signals** may appear in discussions of famine, market crises,
or economic distress in later chapters.
- **S3* (Audit)** is the most difficult system to map in classical economics.
Watch for discussions of market inspections, trade regulation enforcement,
or quality verification.
### Quality Notes
- Current consistency scores (1.0 across all metrics) will be the baseline.
As more chapters are processed, terminology conflicts and cross-reference
issues are likely to emerge and should be actively managed.
- The high proportion of Strong mappings (78.6%) is appropriate for Chapter 1
given its focus on operations, which map cleanly to S1. Later chapters
covering more abstract economic concepts may yield more Moderate and Weak
mappings.