Технические средства платформы ЦИФРА

1. ДОКУМЕНТЫ
   - Спецификации (DESIGN.md)
   - Документация проектов (PROJECT.md, ROADMAP.md)
   - Код агентов (Python файлы)
   - Конфигурация (YAML, JSON)

2. ПРОЕКТЫ
   - Создание из шаблонов
   - Жизненный цикл (active → archived)
   - Связи между компонентами
   - Метаданные (версия, дата, автор)

3. АГЕНТЫ
   - Регистрация агентов
   - Вызов агентов (Task очередь)
   - Состояние агентов (контекст)
   - Координация между агентами
   - Логирование действий

4. ЗНАНИЯ (Knowledge Base)
   - Templates библиотека
   - Components каталог
   - История решений (Git)
   - Метрики и аналитика

pip install jinja2

# Шаблон
template = """
# {{ project_name }} — Спецификация

**Версия:** {{ version }}
**Дата:** {{ date }}

## Описание
{{ description }}
"""

# Использование
from jinja2 import Template
tmpl = Template(template)
result = tmpl.render(
    project_name="DocumentAgent",
    version="1.0.0",
    date="2025-11-10",
    description="Агент документации"
)

# Простые случаи
doc = f"""
# {project_name} — Спецификация
**Версия:** {version}
"""

from string import Template

tmpl = Template("# $project_name — Спецификация")
result = tmpl.substitute(project_name="DocumentAgent")

pip install markdown

import markdown
md = markdown.Markdown()
html = md.convert("# Header\n\nText")
# Результат: HTML

pip install mistune

import mistune
ast = mistune.create_markdown(renderer=None)
tree = ast("# Header\n\nText")
# Результат: AST (Abstract Syntax Tree)

import re

# Извлечь заголовки
headers = re.findall(r'^#+\s+(.+)$', markdown_text, re.MULTILINE)

# Извлечь метаданные
version = re.search(r'\*\*Версия:\*\*\s+(.+)', markdown_text)

pip install jsonschema

schema = {
    "type": "object",
    "properties": {
        "version": {"type": "string"},
        "status": {"enum": ["draft", "approved"]}
    },
    "required": ["version", "status"]
}

from jsonschema import validate
validate(instance=data, schema=schema)

pip install pydantic

from pydantic import BaseModel
from datetime import datetime

class DesignSpec(BaseModel):
    version: str
    date: datetime
    status: str

# Валидация
spec = DesignSpec(
    version="1.0.0",
    date="2025-11-10",
    status="draft"
)

def validate_design_md(content):
    required_sections = [
        "# ОПРЕДЕЛЕНИЕ",
        "# КОНТЕКСТ",
        "# АНАЛИЗ"
    ]

    for section in required_sections:
        if section not in content:
            raise ValueError(f"Missing section: {section}")

    return True

import shutil
import os

# Копирование директории
shutil.copytree(
    'templates/streamlit-mvp-v1/structure',
    'projects/myapp'
)

# Замена переменных в файлах
for root, dirs, files in os.walk('projects/myapp'):
    for file in files:
        if file.endswith('.md') or file.endswith('.py'):
            path = os.path.join(root, file)
            with open(path, 'r') as f:
                content = f.read()

            # Замена
            content = content.replace('{{PROJECT_NAME}}', 'myapp')

            with open(path, 'w') as f:
                f.write(content)

pip install cookiecutter

# Структура шаблона с {{cookiecutter.project_name}}
cookiecutter templates/streamlit-mvp-v1/
# Интерактивно спрашивает переменные

class ProjectGenerator:
    def __init__(self, workspace):
        self.workspace = workspace

    def create_from_template(self, template_name, project_name, variables):
        template_path = f"{self.workspace}/templates/{template_name}"
        project_path = f"{self.workspace}/projects/{project_name}"

        # Копирование
        shutil.copytree(template_path, project_path)

        # Замена переменных через Jinja2
        self._replace_variables(project_path, variables)

        return project_path

---
version: 1.0.0
created_at: 2025-11-10
template: streamlit-mvp-v1
status: active
---

# Проект Marketplace

Описание...

pip install python-frontmatter

import frontmatter

# Чтение
with open('PROJECT.md') as f:
    post = frontmatter.load(f)

print(post['version'])  # 1.0.0
print(post.content)     # Markdown без frontmatter

# projects/marketplace/project.yaml
name: marketplace
version: 1.0.0
created_at: 2025-11-10
template: streamlit-mvp-v1
status: active

import sqlite3

conn = sqlite3.connect('platform/.claude/projects.db')

CREATE TABLE projects (
    name TEXT PRIMARY KEY,
    version TEXT,
    created_at TIMESTAMP,
    template TEXT,
    status TEXT
)

status: active  # active | archived | deprecated

projects/
├── active/
│   └── marketplace/
├── archived/
│   └── old-project/
└── deprecated/
    └── legacy-app/

from transitions import Machine

class Project:
    states = ['draft', 'active', 'archived', 'deprecated']

    transitions = [
        {'trigger': 'activate', 'source': 'draft', 'dest': 'active'},
        {'trigger': 'archive', 'source': 'active', 'dest': 'archived'},
        {'trigger': 'deprecate', 'source': '*', 'dest': 'deprecated'},
    ]

class AgentAPI:
    def __init__(self):
        self.agents = {}  # name -> agent_instance

    def register_agent(self, agent):
        self.agents[agent.name] = agent
        print(f"✅ Registered: {agent.name}")

    def call_agent(self, name, task):
        return self.agents[name].execute(task)

# platform/config/agents.yaml
agents:
  DocumentAgent:
    enabled: true
    module: platform.agents.document_agent
    class: DocumentAgent

  CodeAgent:
    enabled: true
    module: platform.agents.code_agent
    class: CodeAgent

import importlib

def load_agents_from_config():
    with open('platform/config/agents.yaml') as f:
        config = yaml.safe_load(f)

    agents = {}
    for name, cfg in config['agents'].items():
        if cfg['enabled']:
            module = importlib.import_module(cfg['module'])
            agent_class = getattr(module, cfg['class'])
            agents[name] = agent_class(workspace)

    return agents

# CentralAgent
result1 = api.call_agent("DocumentAgent", task1)
result2 = api.call_agent("CodeAgent", task2)
result3 = api.call_agent("GitAgent", task3)

import asyncio

async def workflow():
    task1 = api.call_agent_async("DocumentAgent", task1)
    task2 = api.call_agent_async("CodeAgent", task2)

    # Параллельное выполнение
    results = await asyncio.gather(task1, task2)

# С Celery
from celery import Celery

app = Celery('cifra', broker='redis://localhost:6379')

@app.task
def run_agent(agent_name, task):
    return api.call_agent(agent_name, task)

# Использование
result = run_agent.delay("DocumentAgent", task)
result.get()  # Ждём результата

class BaseAgent:
    def __init__(self):
        self.context = {}  # В памяти

# platform/.claude/agents/DocumentAgent_context.yaml
last_project: marketplace
templates_used:
  - streamlit-mvp-v1
documents_created: 15

CREATE TABLE agent_context (
    agent_name TEXT PRIMARY KEY,
    context JSON,
    updated_at TIMESTAMP
)

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('platform/.claude/agents.log'),
        logging.StreamHandler()
    ]
)

logger = logging.getLogger('DocumentAgent')
logger.info("Created PROJECT.md for marketplace")

pip install structlog

import structlog

log = structlog.get_logger()
log.info(
    "document_created",
    agent="DocumentAgent",
    project="marketplace",
    file="PROJECT.md",
    duration=1.5
)

# Вывод: JSON
# {"event": "document_created", "agent": "DocumentAgent", ...}

# platform/.claude/session-2025-11-10.md

## 14:30 - DocumentAgent
- Создан PROJECT.md для marketplace
- Использован шаблон: streamlit-mvp-v1
- Время: 1.5s

# components/catalog.yaml
formatters:
  - name: format_price
    path: components/shared/lib/formatters.py
    description: "Форматирование цены в рубли"
    usage_count: 45
    tags: [formatting, price, currency]

validators:
  - name: validate_inn
    path: components/shared/lib/validators.py
    description: "Валидация ИНН"
    usage_count: 23
    tags: [validation, inn, business]

import yaml

with open('components/catalog.yaml') as f:
    catalog = yaml.safe_load(f)

# Поиск по тегам
results = [c for c in catalog['formatters'] if 'price' in c['tags']]

CREATE VIRTUAL TABLE components_fts USING fts5(
    name,
    path,
    description,
    tags
);

-- Поиск
SELECT * FROM components_fts WHERE components_fts MATCH 'price';

pip install whoosh

from whoosh.index import create_in
from whoosh.fields import Schema, TEXT, ID

schema = Schema(
    name=ID(stored=True),
    path=TEXT(stored=True),
    description=TEXT,
    tags=TEXT
)

# Индексация
ix = create_in("indexdir", schema)
writer = ix.writer()
writer.add_document(
    name="format_price",
    path="components/shared/lib/formatters.py",
    description="Форматирование цены",
    tags="formatting price currency"
)
writer.commit()

# Поиск
from whoosh.qparser import QueryParser
with ix.searcher() as searcher:
    query = QueryParser("tags", ix.schema).parse("price")
    results = searcher.search(query)

pip install openai faiss-cpu

import openai
import faiss
import numpy as np

# 1. Создать embeddings для всех компонентов
descriptions = [
    "Форматирование цены в рубли",
    "Валидация ИНН",
    # ...
]

embeddings = []
for desc in descriptions:
    response = openai.Embedding.create(
        input=desc,
        model="text-embedding-ada-002"
    )
    embeddings.append(response['data'][0]['embedding'])

embeddings = np.array(embeddings)

# 2. Создать FAISS индекс
dimension = embeddings.shape[1]  # 1536 для ada-002
index = faiss.IndexFlatL2(dimension)
index.add(embeddings)

# 3. Поиск
query = "нужно форматировать деньги"
query_embedding = openai.Embedding.create(
    input=query,
    model="text-embedding-ada-002"
)['data'][0]['embedding']

distances, indices = index.search(
    np.array([query_embedding]),
    k=5  # топ-5 результатов
)

# indices[0] содержит индексы наиболее похожих компонентов

pip install sentence-transformers

from sentence_transformers import SentenceTransformer
model = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')

# Embeddings
embeddings = model.encode(descriptions)

# Поиск (cosine similarity)
from sklearn.metrics.pairwise import cosine_similarity
query_embedding = model.encode(["нужно форматировать деньги"])
similarities = cosine_similarity(query_embedding, embeddings)

# Топ-5
top_indices = similarities[0].argsort()[-5:][::-1]

pip install gitpython

from git import Repo

repo = Repo('/opt/claude-workspace')

# История коммитов
commits = list(repo.iter_commits('master', max_count=100))
for commit in commits:
    print(f"{commit.hexsha[:7]} - {commit.message}")

# Поиск в истории
commits_with_agent = [
    c for c in commits
    if 'DocumentAgent' in c.message
]

# Diff между версиями
diff = repo.git.diff('HEAD~1', 'HEAD')

import subprocess

# История
result = subprocess.run(
    ['git', 'log', '--oneline', '-10'],
    capture_output=True,
    text=True
)
print(result.stdout)

# Обязательно
pip install anthropic          # Claude API
pip install pyyaml             # Конфигурация

# Опционально (полезно)
pip install python-frontmatter # Метаданные в Markdown
pip install pytest             # Тестирование
pip install click              # CLI

Документы:
  - Markdown
  - f-strings (шаблоны)
  - regex (парсинг метаданных)

Проекты:
  - shutil + os (копирование)
  - YAML frontmatter (метаданные)
  - Статус в YAML

Агенты:
  - AgentAPI (реестр в памяти)
  - agents.yaml (конфигурация)
  - Синхронные вызовы
  - Python logging
  - YAML (состояние агентов)

Знания:
  - YAML catalog
  - Git (через subprocess или GitPython)
  - Простой поиск (линейный)

Фаза 2:
  - Jinja2 (шаблоны)
  - Pydantic (валидация)
  - structlog (логирование)
  - GitPython (анализ истории)

Фаза 3:
  - asyncio (параллелизм)
  - Whoosh (полнотекстовый поиск)
  - SQLite (метрики)

Фаза 4:
  - Celery (распределённое выполнение)
  - Semantic Search (Sentence Transformers)
  - State Machine (сложные переходы)